org.apache.log4j.ext
Class SNMPTrapAppender

java.lang.Object
  extended by org.apache.log4j.AppenderSkeleton
      extended by org.apache.log4j.ext.SNMPTrapAppender
All Implemented Interfaces:
org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler

public class SNMPTrapAppender
extends org.apache.log4j.AppenderSkeleton

An appender to send formatted logging event strings to a specified managment host (typically, a MLM of some sort, but could also be an SNMP management console) in the form of an SNMP trap.

This appender does not attempt to provide full access to the SNMP API. In particular, use of this appender does not make an SNMP agent out of the calling application. You cannot use this appender as an interface to do SNMP GET or SET calls -- all it does is pass on your logging event as a TRAP.

This appender uses a helper class which serves as the interface to the SNMP sub-system. This class must implement the SnmpTrapSenderFacade interface. The concrete implementation class you want to use must be specified in your properties file -- see the examples below. The implementation class must provide a parameterless constructor -- this is the constructor that Log4J will use to instantiate the class using the class name in the properties file.

There are three implementation classes provided with this appender; the JoeSNMPTrapSender, the WengsoftSNMPTrapSender and the NetSnmpCommandLineTrapSender classes. If you fail to specify an implementation in your properties file, or if there is a problem finding, loading or instantiating the implementation that you do specify, the appender will fall back to using the JoeSNMPTrapSender implementation as a default.

You can and should, as your needs dictate, write your own implementation of SnmpTrapSenderFacade, using the underlying SNMP library of your choice. In this case, the implementations provided with the appender should serve as adequate examples for how this might be done.

Here's a sample of what you would need in an XML configuration file to configure this appender:

<appender name="TRAP_LOG" class="org.apache.log4j.ext.SNMPTrapAppender"> <param name="ImplementationClassName" value="org.apache.log4j.ext.JoeSNMPTrapSender"/> <param name="ManagementHost" value="127.0.0.1"/> <param name="ManagementHostTrapListenPort" value="162"/> <param name="EnterpriseOID" value="1.3.6.1.4.1.24.0"/> <param name="LocalIPAddress" value="127.0.0.1"/> <param name="LocalTrapSendPort" value="161"/> <param name="GenericTrapType" value="6"/> <param name="SpecificTrapType" value="12345678"/> <param name="CommunityString" value="public"/> <param name="ForwardStackTraceWithTrap" value="true"/> <param name="Threshold" value="DEBUG"/> <param name="ApplicationTrapOID" value="1.3.6.1.4.1.24.12.10.22.64"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d,%p,[%t],[%c],%m%n"/> </layout> </appender>
To configure an otherwise identical appender that uses a different implementation class, you would simply change the value of the "ImplementationClassName", as in the following example:
<appender name="TRAP_LOG" class="org.apache.log4j.ext.SNMPTrapAppender"> <param name="ImplementationClassName" value="org.apache.log4j.ext.WengsoftSNMPTrapSender"/> <param name="ManagementHost" value="127.0.0.1"/> <param name="ManagementHostTrapListenPort" value="162"/> <param name="EnterpriseOID" value="1.3.6.1.4.1.24.0"/> <param name="LocalIPAddress" value="127.0.0.1"/> <param name="LocalTrapSendPort" value="161"/> <param name="GenericTrapType" value="6"/> <param name="SpecificTrapType" value="12345678"/> <param name="CommunityString" value="public"/> <param name="ForwardStackTraceWithTrap" value="true"/> <param name="Threshold" value="DEBUG"/> <param name="ApplicationTrapOID" value="1.3.6.1.4.1.24.12.10.22.64"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d,%p,[%t],[%c],%m%n"/> </layout> </appender>
To configure the appender to use a delimited conversion pattern, to allow multiple VarBinds, you would drop the parameter <param name="ApplicationTrapOID" value="1.3.6.1.4.1.24.12.10.22.64"/> from the configuration, and change the Layout class to SnmpDelimitedConversionPatternLayout. You would then need to set the appropriate parameters of the Layout class. See SnmpDelimitedConversionPatternLayout for an explanation of using multiple VarBinds.
<appender name="TRAP_LOG" class="org.apache.log4j.ext.SNMPTrapAppender"> <param name="ImplementationClassName" value="org.apache.log4j.ext.WengsoftSNMPTrapSender"/> <param name="ManagementHost" value="127.0.0.1"/> <param name="ManagementHostTrapListenPort" value="162"/> <param name="EnterpriseOID" value="1.3.6.1.4.1.24.0"/> <param name="LocalIPAddress" value="127.0.0.1"/> <param name="LocalTrapSendPort" value="161"/> <param name="GenericTrapType" value="6"/> <param name="SpecificTrapType" value="12345678"/> <param name="CommunityString" value="public"/> <param name="ForwardStackTraceWithTrap" value="true"/> <param name="Threshold" value="DEBUG"/> <layout class="org.apache.log4j.ext.SnmpDelimitedConversionPatternLayout"> <param name="ValuePairDelim" value="/"/> <param name="VarDelim" value=";"/> <param name="ConversionPattern" value="%p;1.3.6.1.4.1.24.100.1/%m;1.3.6.1.4.1.24.100.2/%C{1};1.3.6.1.4.1.24.100.3" /> </layout> </appender>

Here's a sample of what you would need in a properties configuration file to configure this appender:

log4j.appender.TRAP_LOG=org.apache.log4j.ext.SNMPTrapAppender
log4j.appender.TRAP_LOG.ImplementationClassName=org.apache.log4j.ext.JoeSNMPTrapSender
log4j.appender.TRAP_LOG.ManagementHost=127.0.0.1
log4j.appender.TRAP_LOG.ManagementHostTrapListenPort=162
log4j.appender.TRAP_LOG.EnterpriseOID=1.3.6.1.4.1.24.0
log4j.appender.TRAP_LOG.LocalIPAddress=127.0.0.1
log4j.appender.TRAP_LOG.LocalTrapSendPort=161
log4j.appender.TRAP_LOG.GenericTrapType=6
log4j.appender.TRAP_LOG.SpecificTrapType=12345678
log4j.appender.TRAP_LOG.ApplicationTrapOID=1.3.6.1.4.1.24.12.10.22.64
log4j.appender.TRAP_LOG.CommunityString=public
log4j.appender.TRAP_LOG.ForwardStackTraceWithTrap=true
log4j.appender.TRAP_LOG.Threshold=DEBUG
log4j.appender.TRAP_LOG.layout=org.apache.log4j.PatternLayout
log4j.appender.TRAP_LOG.layout.ConversionPattern=%d,%p,[%t],[%c],%m%n

Here's an example using the properties file format the uses the delimited conversion pattern technique to allow multiple VarBinds:

log4j.appender.TRAP_LOG=org.apache.log4j.ext.SNMPTrapAppender
log4j.appender.TRAP_LOG.ImplementationClassName=org.apache.log4j.ext.JoeSNMPTrapSender
log4j.appender.TRAP_LOG.ManagementHost=127.0.0.1
log4j.appender.TRAP_LOG.ManagementHostTrapListenPort=162
log4j.appender.TRAP_LOG.EnterpriseOID=1.3.6.1.4.1.24.0
log4j.appender.TRAP_LOG.LocalIPAddress=127.0.0.1
log4j.appender.TRAP_LOG.LocalTrapSendPort=161
log4j.appender.TRAP_LOG.GenericTrapType=6
log4j.appender.TRAP_LOG.SpecificTrapType=12345678
log4j.appender.TRAP_LOG.CommunityString=public
log4j.appender.TRAP_LOG.ForwardStackTraceWithTrap=true
log4j.appender.TRAP_LOG.Threshold=DEBUG
log4j.appender.TRAP_LOG.layout=org.apache.log4j.ext.SnmpDelimitedConversionPatternLayout
log4j.appender.TRAP_LOG.layout.ValuePairDelim=/
log4j.appender.TRAP_LOG.layout.VarDelim=;
log4j.appender.TRAP_LOG.layout.ConversionPattern= %p;1.3.6.1.4.1.24.100.1/%m;1.3.6.1.4.1.24.100.2/%C{1};1.3.6.1.4.1.24.100.3

Version 1.2.8
2001-09-29
changes --- 2001-10-03: mwm : made changes needed to support v.1.1.1 of the SNMPTrapSenderFacade
2002-09-02: mwm : changed to be compatible with Log4J v. 1.2.x
2002-10-03: mwm : Made changes, mainly in #append, to deal with the new SnmpTrapSenderFacade interface architecture.
2002-10-15: mwm: Included the SysUpTimeResolver contributed by Thomas Muller.
2002-10-15: mwm : changed the sysUpTime value to a long, to cope with the SysUpTimeResolver mechanism.
2002-12-10: mwm : minor tweaks and prettying up of code.
2003-03-21: mwm : incorporated the first cut of Matt Monks's code to use a delimited conversion pattern string to allow mutliple VarBinds to be attached to the trap PDU.
2003-03-22: mwm : after reading Ceki's fine new book on Log4J, made several changes (for example, to the implementation of #close) to correct deficiencies in this class as an implementation of AppenderSkeleton. Also improved/added handling of the stack trace of the Throwable associated with the LoggingEvent, again inspired by Ceki's example in the new book.
2003-03-23: mwm : building on Matt Monks's ideas, added the SnmpDelimitedConversionPatternLayout, and used it to refactor the handling of the delimited conversion pattern case.

Author:
Mark Masterson (m.masterson@computer.org), http://www.m2technologies.net/,
Thomas Muller (ttm@online.no),
Matt Monks (Matthew.Monks@netdecisions.com)

Field Summary
 
Fields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold
 
Constructor Summary
SNMPTrapAppender()
          Default constructor.
SNMPTrapAppender(org.apache.log4j.Layout layoutValue)
          Construct the appender with the specified Layout.
 
Method Summary
protected  void append(org.apache.log4j.spi.LoggingEvent event)
          Uses an instance of SnmpTrapSenderFacade to send the String returned by Layout.format() as the message(s) of an SNMP trap.
 void close()
          Sets the state of the Appender to "closed".
 java.lang.String getApplicationTrapOID()
          Get the trap OID that will be sent in the SNMP PDU for this app.
 java.lang.String getCommunityString()
          Get the community string set for the SNMP session this appender will use.
 java.lang.String getEnterpriseOID()
          Get the enterprise OID that will be sent in the SNMP PDU.
 java.lang.String getForwardStackTraceWithTrap()
          Gets the flag that determines if the contents of the stack trace of any Throwable in the LoggingEvent should be added as VarBinds to the trap PDU.
Default is FALSE.
 int getGenericTrapType()
          Get the generic trap type set for this SNMP PDU.
 java.lang.String getImplementationClassName()
          Get the value of the concrete class that implements the SnmpTrapSenderFacade interface.
 java.lang.String getLocalIPAddress()
          Get the IP address of the host that is using this appender to send SNMP traps.
 int getLocalTrapSendPort()
          Get the value of the port that will be used to send traps out from the local host.
 java.lang.String getManagementHost()
          Get the numeric, dotted-decimal IP address of the remote host that traps will be sent to, as a String.
 int getManagementHostTrapListenPort()
          Get the port used on the remote host to listen for SNMP traps.
 int getSpecificTrapType()
          Get the specific trap type set for this SNMP PDU.
 long getSysUpTime()
          Deprecated. Now using the excellent SysUpTimeResolver idea from Thomas Muller
 SysUpTimeResolver getSysUpTimeResolver()
          Gets the concrete instance of an implementation of the SysUpTimeResolver interface that is being used by the appender.
 boolean requiresLayout()
          Implemented to return "true" .
 void setApplicationTrapOID(java.lang.String applicationTrapOIDValue)
          Set the trap OID that will be sent in the SNMP PDU for this app.
 void setCommunityString(java.lang.String communityStringValue)
          Set the community string set for the SNMP session this appender will use.
 void setEnterpriseOID(java.lang.String enterpriseOIDValue)
          Set the enterprise OID that will be sent in the SNMP PDU.
 void setForwardStackTraceWithTrap(java.lang.String forwardStackTraceWithTrap)
          Sets the flag that determines if the contents of the stack trace of any Throwable in the LoggingEvent should be added as VarBinds to the trap PDU.
Default is FALSE.
 void setGenericTrapType(int genericTrapTypeValue)
          Set the generic trap type for this SNMP PDU.
 void setImplementationClassName(java.lang.String implementationClassNameValue)
          Set the value of the concrete class that implements the SnmpTrapSenderFacade interface.
 void setLocalIPAddress(java.lang.String localIPAddressValue)
          Set the IP address of the host that is using this appender to send SNMP traps.
 void setLocalTrapSendPort(int localTrapSendPortValue)
          Set the value of the port that will be used to send traps out from the local host.
 void setManagementHost(java.lang.String managementHostValue)
          Set the IP address of the remote host that traps should be sent to.
 void setManagementHostTrapListenPort(int managementHostTrapListenPortValue)
          Set the port used on the remote host to listen for SNMP traps.
 void setSpecificTrapType(int specificTrapTypeValue)
          Set the specific trap type for this SNMP PDU.
 void setSysUpTime(long sysUpTimeValue)
          Deprecated. Now using the excellent SysUpTimeResolver idea from Thomas Muller, but if you set this value in the properties file, the appender will use that value, to maintain backwards compatibility.
 void setSysUpTimeResolver(java.lang.String value)
          See SysUpTimeResolver.
 
Methods inherited from class org.apache.log4j.AppenderSkeleton
activateOptions, addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SNMPTrapAppender

public SNMPTrapAppender()
Default constructor.


SNMPTrapAppender

public SNMPTrapAppender(org.apache.log4j.Layout layoutValue)
Construct the appender with the specified Layout.

Method Detail

requiresLayout

public boolean requiresLayout()
Implemented to return "true" .

Specified by:
requiresLayout in interface org.apache.log4j.Appender
Specified by:
requiresLayout in class org.apache.log4j.AppenderSkeleton

append

protected void append(org.apache.log4j.spi.LoggingEvent event)
Uses an instance of SnmpTrapSenderFacade to send the String returned by Layout.format() as the message(s) of an SNMP trap. If the various properties have not been intialized, the defaults will be used.

Specified by:
append in class org.apache.log4j.AppenderSkeleton

close

public void close()
Sets the state of the Appender to "closed".

Specified by:
close in interface org.apache.log4j.Appender
Specified by:
close in class org.apache.log4j.AppenderSkeleton

getManagementHost

public java.lang.String getManagementHost()
Get the numeric, dotted-decimal IP address of the remote host that traps will be sent to, as a String.


setManagementHost

public void setManagementHost(java.lang.String managementHostValue)
Set the IP address of the remote host that traps should be sent to.

Parameters:
managementHostValue - -- the IP address of the remote host, in numeric, dotted-decimal format, as a String. E.g. "10.255.255.1"

getManagementHostTrapListenPort

public int getManagementHostTrapListenPort()
Get the port used on the remote host to listen for SNMP traps. The standard is 162.


setManagementHostTrapListenPort

public void setManagementHostTrapListenPort(int managementHostTrapListenPortValue)
Set the port used on the remote host to listen for SNMP traps. The standard is 162.

Parameters:
managementHostTrapListenPortValue - -- any valid TCP/IP port

getEnterpriseOID

public java.lang.String getEnterpriseOID()
Get the enterprise OID that will be sent in the SNMP PDU.

Returns:
A String, formatted as an OID E.g. "1.3.6.1.2.1.1.2.0" -- this OID would point to the standard sysObjectID of the "systemName" node of the standard "system" MIB.

setEnterpriseOID

public void setEnterpriseOID(java.lang.String enterpriseOIDValue)
Set the enterprise OID that will be sent in the SNMP PDU.

Parameters:
enterpriseOIDValue - -- formatted as an OID E.g. "1.3.6.1.2.1.1.2.0" -- this OID would point to the standard sysObjectID of the "systemName" node of the standard "system" MIB.

This is the default value, if none is provided.

If you want(need) to use custom OIDs (such as ones from the "private.enterprises" node -- "1.3.6.1.4.1.x.x.x..."), you always need to provide the fully qualified OID as the parameter to this method.


getLocalIPAddress

public java.lang.String getLocalIPAddress()
Get the IP address of the host that is using this appender to send SNMP traps.


setLocalIPAddress

public void setLocalIPAddress(java.lang.String localIPAddressValue)
Set the IP address of the host that is using this appender to send SNMP traps. This address will be encoded in the SNMP PDU, and used to provide things like the "agent"'s IP address.

Parameters:
localIPAddressValue - -- an IP address, as a String, in numeric, dotted decimal format. E.g. "10.255.255.2".

getGenericTrapType

public int getGenericTrapType()
Get the generic trap type set for this SNMP PDU.


setGenericTrapType

public void setGenericTrapType(int genericTrapTypeValue)
Set the generic trap type for this SNMP PDU. The allowed values for this attribute are a part of the SNMP standard.

Parameters:
genericTrapTypeValue - -- One of the following values:

0 -- cold start
1 -- warm start
2 -- link down
3 -- link up
4 -- authentification failure
5 -- EGP neighbor loss
6 -- enterprise specific


getSpecificTrapType

public int getSpecificTrapType()
Get the specific trap type set for this SNMP PDU.


setSpecificTrapType

public void setSpecificTrapType(int specificTrapTypeValue)
Set the specific trap type for this SNMP PDU. Can be used for application and/or enterprise specific values.

Parameters:
specificTrapTypeValue - -- any value within the range defined for an INTEGER in the ASN.1/BER notation; i.e. -128 to 127

getApplicationTrapOID

public java.lang.String getApplicationTrapOID()
Get the trap OID that will be sent in the SNMP PDU for this app.


setApplicationTrapOID

public void setApplicationTrapOID(java.lang.String applicationTrapOIDValue)
Set the trap OID that will be sent in the SNMP PDU for this app.

Parameters:
applicationTrapOIDValue - -- formatted as an OID E.g. "1.3.6.1.2.1.2.0.0.0.0" -- this OID would point to the standard sysObjectID of the "systemName" node of the standard "system" MIB.

This is the default value, if none is provided.

If you want(need) to use custom OIDs (such as ones from the "private.enterprises" node -- "1.3.6.1.4.1.x.x.x..."), you always need to provide the fully qualified OID as the parameter to this method.


getCommunityString

public java.lang.String getCommunityString()
Get the community string set for the SNMP session this appender will use.


setCommunityString

public void setCommunityString(java.lang.String communityStringValue)
Set the community string set for the SNMP session this appender will use. The community string is used by SNMP (prior to v.3) as a sort of plain-text password.

Parameters:
communityStringValue - -- E.g. "public". This is the default, if none is provided.

getSysUpTime

public long getSysUpTime()
Deprecated. Now using the excellent SysUpTimeResolver idea from Thomas Muller

Get the value of the system up time that will be used for the SNMP PDU.


setSysUpTime

public void setSysUpTime(long sysUpTimeValue)
Deprecated. Now using the excellent SysUpTimeResolver idea from Thomas Muller, but if you set this value in the properties file, the appender will use that value, to maintain backwards compatibility.

Set the value of the system up time that will be used for the SNMP PDU.

Parameters:
sysUpTimeValue - -- this is meant to be the amount of time, in seconds, elapsed since the last re-start or re-initialization of the calling application. Of course, to set this, your application needs to keep track of the value. The default is 0, if none is provided.

getLocalTrapSendPort

public int getLocalTrapSendPort()
Get the value of the port that will be used to send traps out from the local host.


setLocalTrapSendPort

public void setLocalTrapSendPort(int localTrapSendPortValue)
Set the value of the port that will be used to send traps out from the local host.

Parameters:
localTrapSendPortValue - -- any valid IP port number. The default is 161, if none is provided.

getImplementationClassName

public java.lang.String getImplementationClassName()
Get the value of the concrete class that implements the SnmpTrapSenderFacade interface.


setImplementationClassName

public void setImplementationClassName(java.lang.String implementationClassNameValue)
Set the value of the concrete class that implements the SnmpTrapSenderFacade interface.

Parameters:
implementationClassNameValue - -- a String containing the fully qualified class name of the concrete implementation class, e.g. "org.apache.log4j.ext.JoeSNMPTrapSender".

getSysUpTimeResolver

public SysUpTimeResolver getSysUpTimeResolver()
Gets the concrete instance of an implementation of the SysUpTimeResolver interface that is being used by the appender.

Returns:
a concrete instance of an implementation of the SysUpTimeResolver interface

setSysUpTimeResolver

public void setSysUpTimeResolver(java.lang.String value)
See SysUpTimeResolver. This method sets the resolver by passing the FQN of the class that implements the SysUpTimeResolver interface, as a String.

Parameters:
value - -- a String containing the fully qualified class name of the concrete implementation class, e.g. "org.apache.log4j.ext.MySysUpTimeResolver".

getForwardStackTraceWithTrap

public java.lang.String getForwardStackTraceWithTrap()
Gets the flag that determines if the contents of the stack trace of any Throwable in the LoggingEvent should be added as VarBinds to the trap PDU.
Default is FALSE.

Returns:
the current value of this flag.

setForwardStackTraceWithTrap

public void setForwardStackTraceWithTrap(java.lang.String forwardStackTraceWithTrap)
Sets the flag that determines if the contents of the stack trace of any Throwable in the LoggingEvent should be added as VarBinds to the trap PDU.
Default is FALSE. Allowed values are TRUE and FALSE.

Parameters:
forwardStackTraceWithTrap -