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

cpanm Opsview::StatusAPI

perl -MCPAN -e shell
install Opsview::StatusAPI