Provided by: libmonitoring-livestatus-perl_0.74-1_all 
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");
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, <nierlein@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2009 by Sven Nierlein
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.