The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Geneos-API-0.10
River stage zero No dependents
/ Geneos::API

NAME

Geneos::API - Handy Perl interface to ITRS Geneos XML-RPC Instrumentation API

VERSION

Version 0.10

SYNOPSIS

    use Geneos::API;

    # open API to NetProbe running on example.com and port 7036
    my $api = Geneos::API->new("http://example.com:7036/xmlrpc");

    # get the sampler "Keeper" in the managed entity "Zoo"
    my $sampler = $api->get_sampler("Zoo", "Keeper");

    # create view "Monkeys" in the group "Animals"
    my $view = $sampler->create_view("Monkeys", "Animals");

    # prepare some data
    my $monkeys = [
        ["Name",   "Type"  ],
        ["Funky",  "Monkey"],
        ["Cheeky", "Dog"   ]
    ];

    # populate the view
    $view->update_entire_table($monkeys);

DESCRIPTION

Geneos::API is a Perl module that implements ITRS XML-RPC Instrumentation API

METHODS

Constructor

$api->new($url, $options)

$url is required and must be in the form:

http://host:port/path

For example:

my $api = Geneos::API->new("http://localhost:7036/xmlrpc");

XML-RPC Client is initialized upon call to the API constructor

Options

The constructor accepts a reference to the options hash as optional second parameter:

my $api = Geneos::API->new("http://localhost:7036/xmlrpc", { api => {raise_error => 1,}, ua => {timeout => 5,}, });

api - XML-RPC options

  • raise_error

    Force errors to raise exceptions via Carp::croak

  • print_error

    Force errors to raise warnings via Carp::carp

raise_error take precedence over print_error. If neither is set, the errors won't be reported and $api-error> method will need to be called to check if the latest call generated an error or not.

ua - UserAgent options

Error handling

$api->raise_error()

Get the raise_error attribute value

Returns true is the raise_error attribute is set or false othersise

If the raise_error attribute is set, errors generated by API calls will be passed to Carp::croak

If none of the above are set

$api->print_error()

Get the print_error attribute value

Returns true is the print_error attribute is set or false othersise

If the print_error attribute is set, errors generated by API calls will be passed to Carp::carp

print_error attribute is ignored if raise_error is set.

$api->status_line

Returns the string "<code> <message>". Returns undef if there is no error.

$api->error

Get the error produced by the last api call.

Returns reference to the error hash or undef if the last call produced no error. The hash contains three elements:

  • code

    HTTP or XML-RPC error code.

  • message

    Error description.

  • class

    The component that produced the error: HTTP or XML-RPC.

API Function Calls

There are two classes that represent Samplers and Views. First, a sampler object must be created:

$sampler = $api->get_sampler(managedEntity, samplerName)

This will create a Sampler object representing a sampler with the name "samplerName" in the managed entity "managedEntity". You can call any method from the section "Sampler calls" on this object.

Views are represented by the internal Geneos::API::Sampler::View class. In order to create an instance of this class, you can use:

$view = $sampler->get_view(viewName, groupHeading)

if the view already exists, or

$view = $sampler->create_view(viewNmae, groupHeading)

if the view does not exist yet and you want to create one.

Once the view object is created, you can call any of the "View calls" on it.

These methods are described below:

Sampler calls

$api->get_sampler(managedEntity, sampler)

This method doesn't check whether the sampler exists.

Returns sampler object.

$sampler->create_view(viewName, groupHeading)

Creates a new, empty view in the specified sampler under the specified groupHeading. This method will create a view and returns the object representing it. An error will be produced if the view already exists.

Returns OK on successful completion.

$sampler->get_view(viewName, groupHeading)

The view must already exist. This method will NOT check that the view extists or not. Use $sampler-view_exists> method for that.

Returns an object representing the view viewName.

$sampler->view_exists(viewName)

Checks whether a particular view exists in this sampler. viewName should be in the form group-view.

Returns true if the view exists, false otherwise.

$sampler->remove_view(viewName)

Removes a view that has been created with createView.

Returns OK on successful completion.

$sampler->get_parameter(parameterName)

Retrieves the value of a sampler parameter that has been defined in the gateway configuration.

Returns the parameter text written in the gateway configuration.

$sampler->sign_on(period)

period - The maximum time between updates before samplingStatus becomes FAILED

Commits the API client to provide at least one heartbeat or update to the view within the time period specified.

Returns OK on successful completion.

$sampler->sign_off()

Cancels the commitment to provide updates to a view.

Returns OK on successful completion.

$sampler->heartbeat()

Prevents the sampling status from becoming failed when no updates are needed to a view and the client is signed on.

Returns on successful completion.

View calls

$view->add_table_row(rowName,data)

Adds a new, table row to the specified view and populates it with data Returns OK on successful completion.

$view->remove_table_row(rowName)

Removes an existing row from the specified view.

Returns OK on successful completion.

$view->add_headline(headlineName)

Adds a headline variable to the view.

Returns OK on successful completion.

$view->remove_headline(headlineName)

Removes a headline variable from the view.

Returns OK on successful completion.

$view->update_variable(variableName, newValue)

Can be used to update either a headline variable or a table cell. If the variable name contains a period (.) then a cell is assumed, otherwise a headline variable is assumed.

Returns OK on successful completion.

$view->update_headline(headlineName, newValue)

Updates a headline variable.

Returns OK on successful completion.

$view->update_table_cell(cellName, newValue))

Updates a single cell in a table. The standard row.column format should be used to reference a cell.

Returns OK on successful completion.

$view->update_table_row(rowName, newValue))

Updates an existing row from the specified view with the new values provided.

Returns OK on successful completion.

$view->add_table_column(columnName)

Adds another column to the table.

Returns OK on successful completion.

$view->update_entire_table(newTable)

Updates the entire table for a given view. This is useful if the entire table will change at once or the table is being created for the first time. The array passed should be two dimensional. The first row should be the column headings and the first column of each subsequent row should be the name of the row. The array should be at least 2 columns by 2 rows. Once table columns have been defined, they cannot be changed by this method.

Returns OK on successful completion.

$view->column_exists(columnName)

Check if the headline variable exists.

Returns true if the column exists, false otherwise.

$view->row_exists(rowName)

Check if the headline variable exists.

Returns true if the row exists, false otherwise.

$view->headline_exists(headlineName)

Check if the headline variable exists.

Returns true if the headline variable exists, false otherwise.

$view->get_column_count()

Return the column count of the view.

Returns the number of columns in the view. This includes the rowName column.

$view->get_row_count()

Return the headline count of the view.

Returns the number of headlines in the view. This includes the samplingStatus headline.

$view->get_headline_count()

Returns the number of headlines in the view. This includes the samplingStatus headline.

$view->get_column_names()

Returns the names of existing columns in the view. This includes the rowNames column name.

$view->get_row_names()

Returns the names of existing rows in the view

$view->get_headline_names()

Returns the names of existing headlines in the view. This includes the samplingStatus headline.

$view->get_row_names_older_than(epoch)

epoch - The timestamp against which to compare row update time. The timestamp should be provided as Unix timestamp, i.e. number of seconds elapsed since UNIX epoch.

Returns the names of rows whose update time is older than the time provided.

NetProbe Function Calls

$api->managed_entity_exists(managedEntity)

Checks whether a particular Managed Entity exists on this NetProbe containing any API or API-Streams samplers. Returns true if the Managed Entity exists, false otherwise

$api->sampler_exists(managedEntity, sampler)

Checks whether a particular API or API-Streams sampler exists on this NetProbe Returns true if sampler exists, false otherwise

$api->gateway_connected()

Checks whether the Gateway is connected to this NetProbe Returns true if the Gateway is connected, false otherwise

Gateway Function Calls

$api->add_managed_entity($managed_entity, $data_section)

Adds the managed entity to the particular data section Returns true on success, false otherwise

ONLINE RESOURCES AND SUPPORT

AUTHOR

Ivan Dmitriev, <tot@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2014 by Ivan Dmitriev

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.3 or, at your option, any later version of Perl 5 you may have available.