Geneos-API

 view release on metacpan or  search on metacpan

lib/Geneos/API.pm  view on Meta::CPAN

    # get stream "News" on sampler "Channels" in the managed entity "Zoo"
    my $stream = $api->get_sampler("Zoo","Channels")->get_stream("News");

    # add a message to the stream
    $stream->add_message("Funky beats Cheeky in a chess boxing match!");

=head1 DESCRIPTION

C<Geneos::API> is a Perl module that implements ITRS XML-RPC Instrumentation API.
It can be used to create clients for both Geneos API and API Steams plug-ins.
The plug-in acts as an XML-RPC server.

Geneos C<Samplers>, C<Data Views> and C<Streams> are represented by instances of C<Geneos::API::Sampler>, C<Geneos::API::Sampler::View> and C<Geneos::API::Sampler::Stream> classes.
This provides easy to use building blocks for developing monitoring applications.

This module comes with its own XML-RPC module based on L<XML::LibXML> as ITRS implementation of XML-RPC does not conform to the XML-RPC standard and therefore most of the available XML-RPC modules cannot be used. The client uses L<LWP::UserAgent> and...

The module also provides customizable error and debug hanlders.

=head1 INSTALLATION

One of the easiest ways is to run:

    perl -MCPAN -e'install Geneos::API'

This will download and install the latest production version available from CPAN.

Alternatively, use any other method that suits you.

=head1 METHODS

=head2 Constructor

=head3 C<new>

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

C<$url> is required and must be in the format:

C<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

=head3 Options

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

    my $api = Geneos::API->new("http://localhost:7036/xmlrpc", {
        api => {
            # XML-RPC API options:
            raise_error => 1,
        },
        ua  => {
            # UserAgent options:
            keep_alive => 20,
            timeout => 60,
        },
    });

=head4 B<api> - XML-RPC options

=over

=item * C<< raise_error >>

Force errors to raise exceptions via C<Carp::croak>

=item * C<< print_error >>

Force errors to raise warnings via C<Carp::carp>

=item * C<< error_handler >>

Custom error handler. See L</error_handler> section for more details.

=item * C<< debug_handler >>

Debug handler. See L</Debugging> section for more details.

=back

The order of precedence for error handling is as follows:

=over

=item * C<< error_handler >>

=item * C<< raise_error >>

=item * C<< print_error >>

=back

If neither is set, the errors won't be reported and L</error> method will need to be called to check if the latest call generated an error or not.

Example

    # force errors to raise exceptions:
    my $api = Geneos::API->new("http://example.com:7036/xmlrpc", {api=>{raise_error=>1,},});

=head4 B<ua> - UserAgent options

=over

=item * C<< any options supported by L<LWP::UserAgent> >>

=back

If no LWP::UserAgent options are passed to the constructor, the keep alive will be enabled with the total capacity of 10. In other words, the two calls below are identical:

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

    # is identical to
    $api = Geneos::API->new("http://localhost:7036/xmlrpc", {
        ua  => {
            keep_alive => 10,
        },
    });

    # but different to (keep alive disabled):
    $api = Geneos::API->new("http://localhost:7036/xmlrpc", {
        ua  => {},
    });

Note that if you pass the LWP::UserAgent options, the keep alive default won't be applied:

    # keep alive is not enabled
    $api = Geneos::API->new("http://localhost:7036/xmlrpc", {
        ua  => {
            timeout => 300,
        },
    });

Examples:

    # sets http timeout to 30 seconds and implicitly disables keep alive:
    $api = Geneos::API->new("http://example.com:7036/xmlrpc", {
        ua => {
           timeout=>30,
        },
    });

    # sets the agent name to "geneos-client/1.00"
    $api = Geneos::API->new("http://example.com:7036/xmlrpc", {
        ua => {
           agent=>"geneos-client/1.00",
        },
    });

=head2 API and API Streams Function Calls

There are three classes that represent Samplers, Views and Streams.

Samplers are represented by the internal C<Geneos::API::Sampler> class.
First, a sampler object must be created using C<get_sampler> method:

=head3 C<get_sampler>

    $api->get_sampler($managed_entity, $sampler_name)
    $api->get_sampler($managed_entity, $sampler_name, $type_name)

This method doesn't check whether the sampler exists. Use C<$type_name> parameter only if the sampler is a part of that type

Returns sampler object.

    $sampler = $api->get_sampler($managed_entity, $sampler_name, $type_name)

This will create a Sampler object representing a sampler with the name C<$sampler_name> in the managed entity C<$managed_entity>. You can call any method from the section L</"Sampler methods"> on this object.

To reference samplers which are part of a type, use $type_name parameter:

    # This will get sampler "Monkeys" in type "Animals" on managed entity "Zoo":
    $sampler_in_type = $api->get_sampler("Zoo", "Monkeys", "Animals")

    # If the sampler is assigned directly to managed entity:
    $sampler = $api->get_sampler("Zoo", "Monkeys")

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

    # if the view already exists
    $view = $sampler->get_view($view_name, $group_heading)

    # if the view does not exist yet and you want to create it
    $view = $sampler->create_view($view_name, $group_heading)

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

Streams are represented by the internal C<Geneos::API::Sampler::Stream> class. In order to create an instance of this class, you can use:

    $stream = $sampler->get_stream($stream_name)

Once the object is created, you can call any of the L</"Stream methods"> on it.

=head2 Sampler methods

lib/Geneos/API.pm  view on Meta::CPAN

        }
        else {
            my $s = $self->{doc}->createElement("string");
            $s->appendTextNode($scalar);
            $node->appendChild($s);
        }
    }

    sub parse_hash {
        my ($self, $node, $hash) = @_;

        my $struct = $self->{doc}->createElement("struct");
           $node->appendChild($struct);

           foreach (keys %$hash) {
               my $member = $self->{doc}->createElement("member");
               $struct->appendChild($member);

               my $name = $self->{doc}->createElement("name");
               $name->appendTextNode($_);
               $member->appendChild($name);

               $self->parse($member, $hash->{$_});
           }
    }

    sub parse_array {
        my ($self, $node, $args) = @_;

        my $array = $self->{doc}->createElement("array");
        $node->appendChild($array);

        my $data = $self->{doc}->createElement("data");
        $array->appendChild($data);

        $self->parse($data, $_) for @$args;
    }

    sub parse_code {
        my ($self, $node, $code) = @_;

        my ($type, $data) = $code->();

        my $e = $self->{doc}->createElement($type);
        $e->appendTextNode($data);
        $node->appendChild($e);
    }

    ########################################################################
    #
    # package Geneos::API::XMLRPC
    #
    # XML-RPC client
    # The reason for yet another XML-RPC implementation is that
    # because Geneos XML-RPC does not conform to the XML-RPC standard:
    #
    # * '-', '(' and ')' characters may be used in the method names
    # * the values do not default to type 'string'
    #
    # Among other reasons, ensuring that HTTP1.1 is used to take advantage
    # of the keep alive feature supported by Geneos XML-RPC server
    #
    ########################################################################

    package Geneos::API::XMLRPC;

    use LWP::UserAgent;
    use Time::HiRes qw(gettimeofday);

    # -----------
    # Constructor

    sub new {
        my $this = shift;

        my $class = ref($this) || $this;
        my $self = {};
        bless $self, $class;

        $self->_init(@_);
    }

    # ---------------
    # Private methods

    sub _init {
        my ($self, $url, $opts) = @_;

        $self->{_url} = $url;

        $opts ||= {};
        $opts->{ua} ||= {};

        # set up the UserAgent
        $self->{_ua} = LWP::UserAgent->new(%{$opts->{ua}});

        return $self;
    }

    # --------------
    # Public methods

    sub request {
        my ($self, $method, @params) = @_;

        # record the start time
        $self->{_t0} = [gettimeofday];

        # prepare the XML-RPC request
        $self->{_xmlrpc_request} = Geneos::API::XMLRPC::Request->new($method, @params);

        # create an http request
        $self->{_http_request} = HTTP::Request->new("POST",$self->{_url});

        $self->{_http_request}->header('Content-Type' => 'text/xml');
        $self->{_http_request}->add_content_utf8($self->{_xmlrpc_request}->content);

        # send the http request
        $self->{_http_response} = $self->{_ua}->request($self->{_http_request});

        # parse the http response

lib/Geneos/API.pm  view on Meta::CPAN

    #

    sub view_exists {
        my ($self, $view, $group) = @_;
        $self->call("viewExists", "${group}-${view}");
    }

    sub remove_view {shift->call("removeView", @_)}

    # -----------------------------------------------
    # Retrieves the value of a sampler parameter that
    # has been defined in the gateway configuration
    #
    # Returns the parameter text written in the gateway configuration
    #

    sub get_parameter {shift->call("getParameter", @_)}

    sub sign_on {shift->call("signOn", @_)}

    sub sign_off {shift->call("signOff")}

    sub heartbeat {shift->call("heartbeat")}

    ######################################
    #
    # package Geneos::API
    #
    # Implements the Geneos XML-RPC API
    #
    ######################################

    package Geneos::API;

    our $VERSION = '1.00';

    use base 'Geneos::API::Base';
    use Carp;
    use Time::HiRes qw(tv_interval);

    use constant DEFAULT_TOTAL_CAPACITY => 10;

    # ---------------
    # Private methods

    sub _init {
        my ($self, $url, $opts) = @_;

        # the url must be present
        croak "Geneos::API->new was called without URL!" unless $url;

        # if options are passed - it must be a hashref
        if ($opts) {
            croak "Options for Geneos::API->new must be passed as a HASHREF!" unless ref($opts) eq 'HASH';
        }
        else {
            # init the options
            $opts ||= {};
        }

        # enable keep alive by default
        $opts->{ua} ||= {keep_alive=>DEFAULT_TOTAL_CAPACITY,};

        # no api options are set by default
        $opts->{api} ||= {};

        $self->{_xmlrpc} = Geneos::API::XMLRPC->new($url, $opts);
        $self->{_opts} = $opts;

        # ----------------------
        # init the error handler

        if (ref($opts->{api}{error_handler}) eq 'CODE') {
            $self->error_handler($opts->{api}{error_handler});
        }
        elsif ($opts->{api}{raise_error}) {
            $self->error_handler(
                sub {croak("$_[0]->{code} $_[0]->{message}")}
            );
        }
        elsif ($opts->{api}{print_error}) {
            $self->error_handler(
                sub {carp("$_[0]->{code} $_[0]->{message}")}
            );
        }

        # ----------------------
        # init the debug handler

        if ($opts->{api}{debug_handler}) {
            $self->debug_handler($opts->{api}{debug_handler});
        }

        return $self;
    }

    sub _method {shift;@_}

    # --------------
    # Public methods

    # ---------------------
    # get/set error handler

    sub error_handler {
        my ($self, $handler) = @_;

        if (ref($handler) eq 'CODE') {
            $self->{_error_handler} = $handler;
        }
        elsif ($handler) {
            carp("argument for error_handler must be a coderef but got: ", ref($handler));
        }

        return $self->{_error_handler};
    }

    # --------------------
    # remove error handler

    sub remove_error_handler {shift->{_error_handler}=undef;}