NAME

Zenoss - Perl interface to the Zenoss JSON API

SYNOPSIS

    use Zenoss;
    use Data::Dumper;

    # Create a Zenoss object
    my $api = Zenoss->connect(
        {
            username    => 'admin',
            password    => 'zenoss',
            url         => 'http://zenossinstance:8080',
        }
    );

    # Issue a request to get all devices from Zenoss Monitoring System
    my $response = $api->device_getDevices();

    # $response is now an instance of Zenoss::Response
    # now we can do things like
    print $response->json();
    print $response->http_code();

    # get the response in a perl reference
    my $ref = $response->decoded();
    print Dumper $ref;

    # Query events, with history, and only return
    # events that have a severity of 0,1,2,3,4 or 5
    my $events = $api->events_query(
        {
            history => JSON::true,
            params  => {
                severity => [0,1,2,3,4,5],
            }
        }
    );

PREREQUISITES

Zenoss version >= 3.0 is required

DESCRIPTION

The Zenoss Perl module ties components together that are vital to communicating with the Zenoss JSON API. This module is a full service implementation that provides access to all documented API calls by the Zenoss Monitoring System. Essentially, anything that can be accomplished via the Zenoss UI can be done programmatically via Perl.

To get an idea of what requests can be issued to the Zenoss JSON API, please review the documentation for the following modules.

Zenoss::Router::DetailNav
Zenoss::Router::Device
Zenoss::Router::Events
Zenoss::Router::Messaging
Zenoss::Router::Mib
Zenoss::Router::Network
Zenoss::Router::Process
Zenoss::Router::Report
Zenoss::Router::Search
Zenoss::Router::Service
Zenoss::Router::Template
Zenoss::Router::Tree
Zenoss::Router::ZenPack

The documentation for these modules was mostly taken from the Zenoss JSON API docs. Keep in mind that their (Zenoss Monitoring System) programming is based around python, so descriptions such as dictionaries will be represented as hashes in Perl.

METHODS

Available methods provided by this module.

$obj->connect({})

This method instantiates an instance of Zenoss. Currently it accepts the following arguments. Note, these arguments are described in detail at Zenoss::Connector.

username
password
url
timeout

NOTES

Here are some notes regarding this interface.

Zenoss JSON API Arguments

Arguments in methods

When calling the various router methods available, note that any argument you submit will be converted to JSON and transmitted to the Zenoss API.

For example:

    $api->device_getDevices(
        {
            foo => 'bar',
        }
    );

The above code will transmit an argument, in JSON, of foo with a value of bar to the API.

Its also interesting to point out that each router method has an argument definition hard coded. If you attempt to call a method that requires a specific argument, and its omitted, it will croak.

JSON true, false, null

Some router methods accept boolean arguments. In the event that you need to use a true, false or null, the value can be submitted with:

JSON::true
JSON::false
JSON::null

For sake of clarity, say we need to add a device, but we want to also want to model the device after its added. Reading Zenoss::Router::Device states that $obj->device_addDevice() has an available argument of 'model', which is a boolean. With that said we can do the following:

    my $response = $api->device_addDevice(
        {
            deviceName  => 'testdevice',
            deviceClass => '/Server/Linux',
            model       => JSON::true,
        }
    );

Error handling

Some methods Carp, so its always good to always try and trap exceptions. This is mostly limited to when attempting to establish connections to the API, API timeouts, and argument checking. Error handling of Zenoss API responses can be handled with the available methods in Zenoss::Response.

DOCUMENTATION

Please let me know if there is trouble with the documentation. I attempted to put a vast amount of information together all at once, so there may be some mistakes. If you have a question about implementing something described in the documentation, let me know so I can clarify. However, please do not take advantage of this and only ask a question if you're really stuck.

BUGS

Please open bug tickets at <https://rt.cpan.org>

AUTHOR

Patrick Baker <patricksbaker@gmail.com>

COPYRIGHT AND LICENSE

This module is free software: you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You can obtain the Artistic License 2.0 by either viewing the LICENSE file provided with this distribution or by navigating to <http://opensource.org/licenses/artistic-license-2.0.php>.