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
Columns: 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
Columns: name contacts",
	      { Columns => [2] }
	   );

	you can link 2 columns in a hash result set

	   my %hash = @{
	     $ml->selectcol_arrayref(
	       "GET hosts
Columns: 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
Stats: 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
Columns: 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
Columns: name alias state",
	  { Backends => [ 'key1', 'key4' ] }
	);

   Columns
	   only return the given column indexes

	   my $array_ref = $ml->selectcol_arrayref(
	      "GET hosts
Columns: 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
Columns: 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
Columns: 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
Stats: state = 0
Stats: 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
Columns: state as status"
	);

       Stats queries could be aliased too:

	my $stats = $ml->selectall_arrayref(
	  "GET hosts
Stats: 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
Columns: 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.

perl v5.12.3							    2011-04-22					       Monitoring::Livestatus(3pm)