/ 
Opsview-StatusAPI-0.02
River stage zero No dependents
/ Opsview::StatusAPI

NAME

Opsview::StatusAPI - Module to help you query the Opsview Status API

SYNOPSIS

use Opsview::StatusAPI;

my $api = Opsview::StatusAPI->new(
  'user' => 'opsview_user',
  'password' => 'opsview_password',
  'host' => 'opsview.example.com',
  'secure' => 1
);

my $status = $api->hostgroup();

DESCRIPTION

This module queries the Opsview Status API for you, returning data structures as appropiate.

Documetation of the Status API is here: http://docs.opsview.com/doku.php?id=opsview-community:api

Note: this module only queries the "status API", it doesn't understand about the API to create/delete objects

Note2: the data structures returned are only deserialized by this module. Different versions of Opsview may return different data structures.

CONSTRUCTOR

new(user => 'user', 'password' => 'pass', 'host' => 'host.name.com', secure => [0|1])

Create the object. Only the host parameter is required. If not specified, the constructor will die.

Optionally you can pass secure => 1 to make the object access the status API via HTTPS

METHODS

host($hostname [, $filter])

retrieve monitoring information for $hostname. Additionally apply a filter.

This is really a shortcut for:

$api->service({'host' => $hostname, ...filter... })

user([$value])

Set/Retrieve the user for the API.

password([$value])

Set/Retrieve the password for the API.

service($filter)

service()

If called without parameters, will return info for all services. See FILTERS for information on how

The returned data structure will be something like this:

{  'service' => {
     'summary' => {
       'handled' => 15,
       'unhandled' => 0,
       'service' => {
         'ok' => 14,
         'handled' => 14,
         'unhandled' => 0,
         'total' => 14
       },
       'total' => 15,
       'host' => {
         'handled' => 1,
         'unhandled' => 0,
         'up' => 1,
       'total' => 1
     }
   },
  'list' => [
    { 'icon' => 'debian',
      'summary' => {
        'handled' => 14,
        'unhandled' => 0,
        'total' => 14
      },
      'unhandled' => '0',
      'downtime' => 0,
      'name' => 'servername.example.com',
      'alias' => 'Description of the server',
      'state' => 'up'
      'services' => [
        { 'max_check_attempts' => '3',
          'state_duration' => 5893554,
          'name' => '/',
          'output' => 'DISK OK - free space: / 12207 MB (42% inode=-):',
          'current_check_attempt' => '1',
          'state' => 'ok',
          'service_object_id' => '176',
          'unhandled' => '0',
          'downtime' => 0,
          'last_check' => '2010-06-02 00:32:20',
          'perfdata_available' => '1'
        },
        ... one hashref for each service in the host ...
      ]
    },
    ... one hashref for each host returned ...
  ]
}

hostgroup()

hostgroup($hostgroup_id)

If called without parameters, it will return the information about the root hostgroup. If hostgroup_id is passed, it will return information about the hostgroup with that ID.

The returned data structure will be something like this:

{ 'summary' => {
    'handled' => 20,
    'unhandled' => 2,
    'service' => {
        'ok' => 14,
        'critical' => 2,
        'handled' => 16,
        'unhandled' => 2,
        'warning' => 4,
        'total' => 18
    },
    'total' => 20,
    'host' => {
        'handled' => 2,
        'unhandled' => 0,
        'up' => 2,
        'total' => 2
    }
  },
  'list' => [
    {   'hosts' => {
          'handled' => 1,
          'unhandled' => 0,
          'up' => {
            'handled' => 1
          },
          'total' => 1
        },
        'hostgroup_id' => '3',
        'services' => {
          'ok' => {
            'handled' => 3
          },
          'handled' => 3,
          'highest' => 'warning',
          'unhandled' => 1,
          'warning' => {
            'unhandled' => 1
          },
          'total' => 4
        },
        'downtime' => undef,
        'name' => 'Hostgroup Name'
    },
    ...
  ]
}

FILTERS

A filter is a hashref that can contain the following keys with these values:

hostgroupid => id, # the id of a hostgroup
host => 'host',    # the name of a host
state => 0, 1, 2, 3, 'ok, 'warning', 'critical', 'unknown' # 0 == 'ok', 3 == 'unknown'
filter => 'handled' | 'unhandled' # filter by handled or unhandled services

If you want all unhandled warnings, the filter would be

{ 'filter' => 'unhandled', 'state' => 'warning' }

keys can also have multiple values: if you want only WARNINGS and CRITICALS

{ 'state' => [ 1, 2 ] }

AUTHOR

Jose Luis Martinez
CPAN ID: JLMARTIN
CAPSiDE
jlmartinez@capside.com
http://www.pplusdomain.net

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

http://www.opsview.org/

http://docs.opsview.com/doku.php?id=opsview-community:api