Monitoring::Livestatus(3pm)

User Contributed Perl Documentation

Monitoring::Livestatus(3pm)

NAME¶

Monitoring::Livestatus - Perl API for check_mk livestatus to access runtime data from Nagios and Icinga

SYNOPSIS¶

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

DESCRIPTION¶

This module connects via socket/tcp to the check_mk livestatus addon for Nagios and Icinga. You first have to install and activate the mklivestatus addon in your monitoring installation.

CONSTRUCTOR¶

new ( [ARGS] )¶

Creates an "Monitoring::Livestatus" object. "new" takes at least the socketpath. Arguments are in key-value pairs. See EXAMPLES for more complex variants.

socket: path to the UNIX socket of check_mk livestatus

server: use this server for a TCP connection

peer: alternative way to set socket or server, if value contains ':' server is used, else socket

name: human readable name for this connection, defaults to the the socket/server address

verbose: verbose mode

line_seperator: ascii code of the line seperator, defaults to 10, (newline)

column_seperator: ascii code of the column seperator, defaults to 0 (null byte)

list_seperator: ascii code of the list seperator, defaults to 44 (comma)

host_service_seperator: ascii code of the host/service seperator, 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

use_threads: only used with multiple backend connections. Default is to don't threads where available. As threads in perl are causing problems with tied resultset and using more memory. Querys are usually faster without threads, except for very slow backends connections.

If the constructor is only passed a single argument, it is assumed to be a the "peer" specification. Use either socker OR server.

METHODS¶

do¶

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

Send a single statement without fetching the result. Always returns true.

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
    );

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

    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 croak 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

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

marked_bad¶

 $ml->marked_bad()

returns true if the current connection is marked down

disable¶

 $ml->disable()

disables this connection, returns the last state.

enable¶

 $ml->enable()

enables this connection, returns the last state.

QUERY OPTIONS¶

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

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 L<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 dont 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 L<COLUMN ALIAS> for detailed explainaton

Slice¶

  see L<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.

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' }
   }
 );

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) {
        croak($Monitoring::Livestatus::ErrorMessage);
    }

EXAMPLES¶

Multibackend Configuration¶

    use Monitoring::Livestatus;
    my $ml = Monitoring::Livestatus->new(
      name       => 'multiple connector',
      verbose   => 0,
      keepalive => 1,
      peer      => [
            {
                name => 'DMZ Monitoring',
                peer => '50.50.50.50:9999',
            },
            {
                name => 'Local Monitoring',
                peer => '/tmp/livestatus.socket',
            },
            {
                name => 'Special Monitoring',
                peer => '100.100.100.100:9999',
            }
      ],
    );
    my $hosts = $ml->selectall_arrayref("GET hosts");

AUTHOR¶

Sven Nierlein, <nierlein@cpan.org>

COPYRIGHT AND LICENSE¶

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

2011-04-22

perl v5.12.3

Source file:	Monitoring::Livestatus.3pm.en.gz (from libmonitoring-livestatus-perl 0.74-1)
Source last updated:	2011-06-05T20:05:09Z
Converted to HTML:	2018-08-09T23:05:18Z

NAME¶

SYNOPSIS¶

DESCRIPTION¶

CONSTRUCTOR¶

new ( [ARGS] )¶

METHODS¶

do¶

selectall_arrayref¶

selectall_hashref¶

selectcol_arrayref¶

selectrow_array¶

selectrow_arrayref¶

selectrow_hashref¶

selectscalar_value¶

errors_are_fatal¶

warnings¶

verbose¶

peer_addr¶

peer_name¶

peer_key¶

marked_bad¶

disable¶

enable¶

QUERY OPTIONS¶

AddPeer¶

Backend¶

Columns¶

Deepcopy¶

Limit¶

Rename¶

Slice¶

Sum¶

COLUMN ALIAS¶

ERROR HANDLING¶

EXAMPLES¶

Multibackend Configuration¶

SEE ALSO¶

AUTHOR¶

COPYRIGHT AND LICENSE¶