Monito...status(3pm)

📦
version 0.86 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Monitoring::Livestatus — the Perl API for check_mk livestatus, so you can pull runtime data straight out of Nagios and Icinga. It's giving "I have access to everything happening in your monitoring stack." ✨

(psst, this page is Monitoring::Livestatus, section 3pm — that's Perl module docs, bestie — from the User Contributed Perl Documentation girlies. 💅)

🌸 SYNOPSIS 🌸

use Monitoring::Livestatus;
my $ml = Monitoring::Livestatus->new(
  socket => '/var/lib/livestatus/livestatus.sock'
);
my $hosts = $ml->selectall_arrayref("GET hosts");

okay literally three lines and you're already querying. main character energy. 🦋

✨ DESCRIPTION ✨

So this module connects via socket/tcp to the livestatus addon for Naemon, Nagios, Icinga and Shinken. 🫶

Heads up bestie: you have to install and activate the livestatus addon in your monitoring installation first. No addon, no vibes. 😭

🎀 CONSTRUCTOR 🎀

new ( [ARGS] )

Creates a Monitoring::Livestatus object. new takes at least the socketpath. Arguments come in key-value pairs, like a little dictionary of love. 💖

  • socket — path to the UNIX socket of check_mk livestatus 🧚
  • server — server address, for when you're doing a TCP connection 🌈
  • peer — an alternative way to set socket or server: if the value contains ':', then server gets used, otherwise socket. sneaky but iconic.
  • name — a human readable name for this connection, defaults to the the socket/server address ⭐
  • verbose — verbose mode 👀
  • line_separator — ascii code of the line separator, defaults to 10, (newline) 🌸
  • column_separator — ascii code of the column separator, defaults to 0 (null byte) 🫧
  • list_separator — ascii code of the list separator, defaults to 44 (comma) 🍓
  • host_service_separator — ascii code of the host/service separator, defaults to 124 (pipe) 💅
  • keepalive — enable keepalive. Default is off 💀
  • errors_are_fatal — errors will die with an error message. Default: on 😤
  • warnings — show warnings; currently only querys without Columns: Header will result in a warning 🙈
  • timeout — set a general timeout. Used for connect and querys, no default ⌛
  • query_timeout — set a query timeout. Used for retrieving querys, Default 60sec ⏱️
  • connect_timeout — set a connect timeout. Used for initial connections, default 5sec ⚡
If the constructor is only passed a single argument, it is assumed to be a the peer specification. Use either socket OR server, bestie, not both. Pick a lane. 🚦

💜 METHODS 💜

do

do($statement)
do($statement, %opts)

Send a single statement without fetching the result. Always returns true. no notes, it just does the thing. ✅

selectall_arrayref

selectall_arrayref($statement)
selectall_arrayref($statement, %opts)
selectall_arrayref($statement, %opts, $limit )

Sends a query and returns an array reference of arrays 🎀

my $arr_refs = $ml->selectall_arrayref("GET hosts");

to get an array of hash references do something like

my $hash_refs = $ml->selectall_arrayref(
  "GET hosts", { Slice => {} }
);

to get an array of hash references from the first 2 returned rows only

my $hash_refs = $ml->selectall_arrayref(
  "GET hosts", { Slice => {} }, 2
);

you may use limit to limit the result to this number of rows 👑

column aliases can be defined with a rename hash

my $hash_refs = $ml->selectall_arrayref(
  "GET hosts", {
    Slice => {},
    rename => {
      'name' => 'host_name'
    }
  }
);

selectall_hashref

selectall_hashref($statement, $key_field)
selectall_hashref($statement, $key_field, %opts)

Sends a query and returns a hashref with the given key 🔑

my $hashrefs = $ml->selectall_hashref("GET hosts", "name");

selectcol_arrayref

selectcol_arrayref($statement)
selectcol_arrayref($statement, %opt )

Sends a query an returns an arrayref for the first columns 🌈

my $array_ref = $ml->selectcol_arrayref("GET hosts\nColumns: name");

$VAR1 = [
          'localhost',
          'gateway',
        ];

returns an empty array if nothing was found 🕳️

to get a different column use this

my $array_ref = $ml->selectcol_arrayref(
   "GET hosts\nColumns: name contacts",
   { Columns => [2] }
);

you can link 2 columns in a hash result set

my %hash = @{
  $ml->selectcol_arrayref(
    "GET hosts\nColumns: name contacts",
    { Columns => [1,2] }
  )
};

produces a hash with host the contact assosiation 💞

$VAR1 = {
          'localhost' => 'user1',
          'gateway'   => 'user2'
        };

selectrow_array

selectrow_array($statement)
selectrow_array($statement, %opts)

Sends a query and returns an array for the first row 🥇

my @array = $ml->selectrow_array("GET hosts");

returns undef if nothing was found 😶🌫️

selectrow_arrayref

selectrow_arrayref($statement)
selectrow_arrayref($statement, %opts)

Sends a query and returns an array reference for the first row 🎯

my $arrayref = $ml->selectrow_arrayref("GET hosts");

returns undef if nothing was found 😶🌫️

selectrow_hashref

selectrow_hashref($statement)
selectrow_hashref($statement, %opt)

Sends a query and returns a hash reference for the first row 🍒

my $hashref = $ml->selectrow_hashref("GET hosts");

returns undef if nothing was found 😶🌫️

selectscalar_value

selectscalar_value($statement)
selectscalar_value($statement, %opt)

Sends a query and returns a single scalar 1️⃣

my $count = $ml->selectscalar_value("GET hosts\nStats: state = 0");

returns undef if nothing was found 😶🌫️

errors_are_fatal

errors_are_fatal()
errors_are_fatal($value)

Enable or disable fatal errors. When enabled the module will confess on any error. 💀

returns the current setting if called without new value 🔍

warnings

warnings()
warnings($value)

Enable or disable warnings. When enabled the module will carp on warnings. 🐟

returns the current setting if called without new value 🔍

verbose

verbose()
verbose($values)

Enable or disable verbose output. When enabled the module will dump out debug output 🗣️

returns the current setting if called without new value 🔍

peer_addr

$ml->peer_addr()

returns the current peer address 📍

when using multiple backends, a list of all addresses is returned in list context 📜

peer_name

$ml->peer_name()
$ml->peer_name($string)

if new value is set, name is set to this value ✏️

always returns the current peer name 📛

when using multiple backends, a list of all names is returned in list context 📜

peer_key

$ml->peer_key()

returns a uniq key for this peer 🔐

post_processing

$ml->post_processing($result, $options, $keys)

returns postprocessed result. ✨

Useful when using select based io. 🧠

🦋 QUERY OPTIONS 🦋

In addition to the normal query syntax from the livestatus addon, it is possible to set column aliases in various ways. so many ways, pick your fave.

AddPeer

adds the peers name, addr and key to the result set: 🏷️

my $hosts = $ml->selectall_hashref(
  "GET hosts\nColumns: name alias state",
  "name",
  { AddPeer => 1 }
);

Backend

send the query only to some specific backends. Only useful when using multiple backends. 🎛️

my $hosts = $ml->selectall_arrayref(
  "GET hosts\nColumns: name alias state",
  { Backends => [ 'key1', 'key4' ] }
);

Columns

only return the given column indexes 🔢

my $array_ref = $ml->selectcol_arrayref(
   "GET hosts\nColumns: name contacts",
   { Columns => [2] }
);

see selectcol_arrayref for more examples 👀

Deepcopy

deep copy/clone the result set. 🧬

Only effective when using multiple backends and threads. This can be safely turned off if you don't change the result set. If you get an error like "Invalid value for shared scalar" error" this should be turned on.

my $array_ref = $ml->selectcol_arrayref(
   "GET hosts\nColumns: name contacts",
   { Deepcopy => 1 }
);

Limit

Just like the Limit: <nr> option from livestatus itself. In addition you can add a start,length limit. ✂️

my $array_ref = $ml->selectcol_arrayref(
   "GET hosts\nColumns: name contacts",
   { Limit => "10,20" }
);

This example will return 20 rows starting at row 10. You will get row 10-30. 📏

Cannot be combined with a Limit inside the query because a Limit will be added automatically. 🚫

Adding a limit this way will greatly increase performance and reduce memory usage. 🚀

This option is multibackend safe contrary to the Limit: part of a statement. Sending a statement like GET...Limit: 10 with 3 backends will result in 30 rows. Using this options, you will receive only the first 10 rows. 👑

Rename

see COLUMN ALIAS for detailed explainaton 🏷️

Slice

see selectall_arrayref for detailed explainaton 🍰

Sum

The Sum option only applies when using multiple backends. The values from all backends with be summed up to a total. ➕

my $stats = $ml->selectrow_hashref(
  "GET hosts\nStats: state = 0\nStats: state = 1",
  { Sum => 1 }
);

🌈 COLUMN ALIAS 🌈

In addition to the normal query syntax from the livestatus addon, it is possible to set column aliases in various ways. (yes, this is the same intro as above, they really wanted you to know 💅)

A valid Columns: Header could look like this:

my $hosts = $ml->selectall_arrayref(
  "GET hosts\nColumns: state as status"
);

Stats queries could be aliased too:

my $stats = $ml->selectall_arrayref(
  "GET hosts\nStats: state = 0 as up"
);

This syntax is available for: Stats, StatsAnd, StatsOr and StatsGroupBy 📚

An alternative way to set column aliases is to define rename option key/value pairs:

my $hosts = $ml->selectall_arrayref(
  "GET hosts\nColumns: name", {
    rename => { 'name' => 'hostname' }
  }
);

extract_keys_from_stats_statement

extract_keys_from_stats_statement($statement)

Extract column keys from statement. 🔍

😭 ERROR HANDLING 😭

Errorhandling can be done like this:

use Monitoring::Livestatus;
my $ml = Monitoring::Livestatus->new(
  socket => '/var/lib/livestatus/livestatus.sock'
);
$ml->errors_are_fatal(0);
my $hosts = $ml->selectall_arrayref("GET hosts");
if($Monitoring::Livestatus::ErrorCode) {
    confess($Monitoring::Livestatus::ErrorMessage);
}

turn off the fatal errors, check the error code, confess about it. the full drama arc. 🎭

👀 SEE ALSO 👀

For more information about the query syntax and the livestatus plugin installation see the Livestatus page: http://mathias-kettner.de/checkmk_livestatus.html 🌐

👑 AUTHOR 👑

Sven Nierlein, 2009-present, <sven@nierlein.org> 💌

Copyright (C) by Sven Nierlein

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

and that's the whole page bestie, no cap. perl v5.40.1 · 2025-05-15 — now go query something iconic. ✨💖🦋

📦 where this page comes from