VERSION

SYNOPSIS

use strict;
use SNMP::Extension::PassPersist;
# create the object
my $extsnmp = SNMP::Extension::PassPersist->new;
# add a few OID entries
$extsnmp->add_oid_entry($oid, $type, $value);
$extsnmp->add_oid_entry($oid, $type, $value);
# run the program
$extsnmp->run;

Typical setup for a "pass_persist" program:

    use strict;
    use SNMP::Extension::PassPersist;
    my $extsnmp = SNMP::Extension::PassPersist->new(
        backend_collect => \&update_tree
    );
    $extsnmp->run;
    sub update_tree {
        my ($self) = @_;
        # add a serie of OID entries
        $self->add_oid_entry($oid, $type, $value);
        ...
        # or directly add a whole OID tree
        $self->add_oid_tree(\%oid_tree);
    }

DESCRIPTION

When in "pass_persist" mode, it provides a mechanism to spare resources by quitting from the main loop after a given number of idle cycles.

This module can use "Sort::Key::OID" when it is available, for sorting OIDs faster than with the internal pure Perl function.

METHODS

new()

Examples:

For a "pass" command, most attributes are useless:

    my $extsnmp = SNMP::Extension::PassPersist->new;

For a "pass_persist" command, you'll usually want to at least set the "backend_collect" callback:

    my $extsnmp = SNMP::Extension::PassPersist->new(
        backend_collect => \&update_tree,
        idle_count      => 10,      # no more than 10 idle cycles
        refresh         => 10,      # refresh every 10 sec
    );

run()

• process the command line arguments in order to decide in which mode the program has to be executed
• call the backend init callback
• call the backend collect callback a first time

Then, when in "pass" mode, the corresponding SNMP command is executed, its result is printed on the output filehandle, and "run()" returns.

When in "pass_persist" mode, "run()" enters a loop, reading Net-SNMP queries on its input filehandle, processing them, and printing result on its output filehandle. The backend collect callback is called every "refresh" seconds. If no query is read from the input after "idle_count" cycles, "run()" returns.

add_oid_entry(FUNC_OID, FUNC_TYPE, FUNC_VALUE)

add_oid_tree(HASH)

dump_oid_tree()

ATTRIBUTES

backend_collect

backend_fork

backend_init

backend_pipe

dispatch

    dispatch => {
        SNMP_CMD  =>  { nargs => NUMBER_ARGS,  code => CODEREF },
        ...
    }

where the SNMP command is always in lowercase, "nargs" gives the number of arguments expected by the command and "code" the callback reference.

You should not modify this table unless you really know what you're doing.

heap

idle_count

input

oid_tree

    oid_tree => {
        FUNC_OID  =>  [ FUNC_TYPE, FUNC_VALUE ],
        ...
    }

where "FUNC_OID" is the absolute OID of the SNMP function, "FUNC_TYPE" the function type ("integer", "counter", "gauge", etc), and "FUNC_VALUE" the function value.

You should not directly modify this hash but instead use the appropriate methods for adding OID entries.

output

refresh

CALLBACKS

In the specific case of a program running in "pass_persist" mode with a forked backend, the callbacks are only executed in the child process (the forked backend).

The currently implemented callbacks are:

• init

  This callback is called once, before the first collect invocation and before the main loop. It can be accessed and modified through the "backend_init" attribute.

• collect

  This callback is called every "refresh" seconds so the user can update the OID tree using the "add_oid_entry()" and "add_oid_tree()" methods.

Examples

    my $extsnmp = SNMP::Extension::PassPersist->new(
        backend_collect => \&update_tree,
    );
    sub update_tree {
        my ($self) = @_;
        # fetch the number of running processes
        my $nb_proc = @{ Proc::ProcessTable->new->table };
        $self->add_oid_entry(".1.3.6.1.4.1.32272.10", gauge", $nb_proc);
    }

A more advanced example is when there is a need to connect to a database, in which case both the init and collect callback need to be defined:

    my $extsnmp = SNMP::Extension::PassPersist->new(
        backend_init    => \&connect_db,
        backend_collect => \&update_tree,
    );
    sub connect_db {
        my ($self) = @_;
        my $heap = $self->heap;
        # connect to a database
        my $dbh = DBI->connect($dsn, $user, $password);
        $heap->{dbh} = $dbh;
    }
    sub update_tree {
        my ($self) = @_;
        my $heap = $self->heap;
        # fetch the number of records from a given table
        my $dbh = $heap->{dbh};
        my $sth = $dbh->prepare_cached("SELECT count(*) FROM whatever");
        $sth->execute;
        my ($count) = $sth->fetchrow_array;
        $self->add_oid_entry(".1.3.6.1.4.1.32272.20", "gauge", $count);
    }

SUPPORT

    perldoc SNMP::Extension::PassPersist

You can also look for information at:

• Search CPAN

  <http://search.cpan.org/dist/SNMP-Extension-PassPersist>

• Meta CPAN

  <https://metacpan.org/release/SNMP-Extension-PassPersist>

• RT: CPAN's request tracker

  <http://rt.cpan.org/Public/Dist/Display.html?Name=SNMP-Extension-PassPersist>

• AnnoCPAN: Annotated CPAN documentation

  <http://annocpan.org/dist/SNMP-Extension-PassPersist>

• CPAN Ratings

  <http://cpanratings.perl.org/d/SNMP-Extension-PassPersist>

AUTHOR

COPYRIGHT & LICENSE

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