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

NAME

Log::Dispatch::SNMP - Object for logging to SNMP servers

VERSION

Version 0.02

SYNOPSIS

If you're using Log::Dispatch:

    use Log::Dispatch::SNMP;

    # *OPTIONAL* parameters (and their default values)
    # name                         - defaults to a unique one
    # max_level                    - defaults to no maximum
    # ManagementHostTrapListenPort - defaults to 162
    # LocalTrapSendPort            - defaults to 161
    # CommunityString              - defaults to 'public'
    # GenericTrapType              - defaults to 6
    #
    # other parameters are *REQUIRED*
    
    my $snmp = Log::Dispatch::SNMP->new(
                 name      => 'snmp',
                 min_level => 'debug',
                 max_level => 'error',
                 
                 ManagementHost               => '192.168.0.1',
                 ManagementHostTrapListenPort => 162,
                 EnterpriseOID                => '1.1.1.1.1.1.1.1.1.1.1',
                 LocalIPAddress               => '127.0.0.1',
                 LocalTrapSendPort            => 161,
                 GenericTrapType              => 6,
                 SpecificTrapType             => 0,
                 ApplicationTrapOID           => '2.2.2.2.2.2.2.2.2.2.2',
                 CommunityString              => 'public',
    );

    $snmp->log( level => 'alert', message => "houston, we have a problem.\n" );

Or even better, if you're using Log::Log4perl, just set the appender options on your configuration file (or string) and you're good to go:

    log4perl.category.Foo.Bar = INFO SNMPTrap
    
    log4perl.appender.SNMPTrap = Log::Dispatch::SNMP;
    log4perl.appender.SNMPTrap.ManagementHost = 192.168.0.1
    log4perl.appender.SNMPTrap.ManagementHostTrapListenPort = 162
    log4perl.appender.SNMPTrap.EnterpriseOID=1.1.1.1.1.1.1.1.1.1.1
    log4perl.appender.SNMPTrap.LocalIPAddress=127.0.0.1
    log4perl.appender.SNMPTrap.LocalTrapSendPort=161
    log4perl.appender.SNMPTrap.GenericTrapType=6
    log4perl.appender.SNMPTrap.SpecificTrapType=0
    log4perl.appender.SNMPTrap.ApplicationTrapOID=2.2.2.2.2.2.2.2.2.2.2
    log4perl.appender.SNMPTrap.CommunityString=public
    log4perl.appender.SNMPTrap.ForwardStackTraceWithTrap=true
    log4perl.appender.SNMPTrap.Threshold=DEBUG
    log4perl.appender.SNMPTrap.layout=PatternLayout
    log4perl.appender.SNMPTrap.layout.ConversionPattern=%d,%p,[%t],[%c],%m%n

You can also share the same Log4j configuration file of any Java-based application using SNMPTrapAppender (log4j-snmp-trap-appender):

    # write this in your Perl code, 
    # before you call Log::Log4perl::init()
    $Log::Log4perl::JavaMap::user_defined{'org.apache.log4j.ext.SNMPTrapAppender'}
        = 'Log::Dispatch::SNMP';

...but please note that you will *not* be able to use the special Layout Class SnmpDelimitedConversionPatternLayout for multiple VarBinds. At least not for now :)

DESCRIPTION

Log::Dispatch::SNMP is an appender to send logging messages to a specified management host in SNMP-managed networks (with a MLM or SMNP management console of some kind), commonly found in large and/or distributed networks. It should be used under the Log::Dispatch system or other compatible logging environments such as Log::Log4perl.

Note that this appender does not attempt to provide full access to the SNMP API, so you cannot use it as an interface to SNMP GET or SET calls (you should check Net::SNMP and others for this). All we do is pass your logging event as a TRAP.

Log::Log4perl Integration

Remember that, if you're using Log4perl, you don't have to directly instantiate any dispatcher on your code - Log4perl will do that for you tranparently. So, if you're using this module with Log4perl, just remember to set the parameters in your configuration file (usually 'log4perl.conf'). Please refer to the SYNOPSIS under this document for syntax information, and to the Log::Log4Perl documentation for further information on using Log4perl.

METHODS

new

Instantiates a new logging object. It takes the following parameters (all are required, except when otherwise noted):

name (optional)

A string containing the name of the logging object. This is useful if you want to refer to the object later, e.g. to log specifically to it or remove it (Log4perl users don't need this at all, as specific logs can be easily done via its configuration).

By default a unique name will be generated. You should not depend on the form of generated names, as they may change.

min_level *REQUIRED*

A string ('warning') or integer ('3') containing the minimum logging level this object will accept. Please refer to the Log::Dispatcher documentation for further information.

ManagementHost *REQUIRED*

A string containing the SNMP server host name (i.e. the destination for your traps)

ManagementHostTrapListenPort (optional)

The port number the SNMP server is listening to. This parameter is optional, and defaults to port 162.

EnterpriseOID *REQUIRED*

A string containing the Enterprise Object Identifier (EOID).

LocalIPAddress *REQUIRED*

A string containing the local IP address.

LocalTrapSendPort (optional)

The port number to use locally. This parameter is optional, and defaults to port 161.

GenericTrapType (optional)

A number with the Generic Trap type. This parameter is optional, and defaults to 6 which corresponds to "enterpriseSpecific" (what you usually want under message logging).

SpecificTrapType *REQUIRED*

A number with the specific Trap type.

ApplicationTrapOID *REQUIRED*

A string containing the Object Identifier (OID) for the Application.

CommunityString (optional)

A string containing the SNMP community name. This parameter is optional, and defaults to 'public'.

log_message( message => $ )

Format and sends the given message. This method generally should NOT be called directly. Instead, you should use the log() method on your chosen logging interface.

WHAT IS IT WITH ALL THESE LONG/WEIRD-NAMED PARAMETERS?

I know, I know. As much as I loved to name stuff like 'ManagementHostTrapListenPort' into something more simple (and perlish) like 'remote_port', I've kept the original Java names to support interoperability and interchangeability with Log4j and easen the learning curve for Java folks migrating to Perl :)

I might introduce more perlish synonyms for all the long-and-mixed-cased atributes if you ask for them via RT or email.

AUTHOR

Breno G. de Oliveira, <garu at cpan.org>

BUGS

Please report any bugs or feature requests to bug-log-dispatch-snmp at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-Dispatch-SNMP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Log::Dispatch::SNMP

You can also look for information at:

ACKNOWLEDGEMENTS

Many thanks to Dave Rolsky for his Log::Dispatch framework, to Michael Schilli for Log::Log4perl and to David Town for Net::SNMP.

This module's functionality is based on http://code.google.com/p/log4j-snmp-trap-appender/

SEE ALSO

Log::Dispatch Log::Log4perl Net::SNMP

COPYRIGHT & LICENSE

Copyright 2009-2010 Breno G. de Oliveira, all rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.