org.apache.log4j.ext
Class SNMPTrapAppender

java.lang.Object
  |
  +--org.apache.log4j.AppenderSkeleton
        |
        +--org.apache.log4j.ext.SNMPTrapAppender
All Implemented Interfaces:
org.apache.log4j.Appender, 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, SNMPTrapSenderFacade, which serves as the interface to the SNMP sub-system. This class uses the JoeSNMP library from the OpenNMS project to implement the underlying SNMP protocol. See SNMPTrapSenderFacade for details.
The JoeSNMP library requires a minimum of JDK 1.2. Thus, this appender may not function properly under JDK 1.1 implementations.

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="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="163"/> <param name="GenericTrapType" value="1"/> <param name="SpecificTrapType" value="6"/> <param name="ApplicationTrapOID" value="1.3.6.1.4.1.24.12.10.22.64"/> <param name="CommunityString" value="public"/> <param name="SysUpTime" value="1000"/> <param name="Threshold" value="DEBUG"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d,%p,[%t],[%c],%m%n"/> </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.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=163
log4j.appender.TRAP_LOG.GenericTrapType=1
log4j.appender.TRAP_LOG.SpecificTrapType=6
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.SysUpTime=1000
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

Version 1.1.1
2001-09-29
changes --- 2001-10-03: mwm : made changes needed to support v.1.1.1 of the SNMPTrapSenderFacade

Author:
Mark Masterson (m.masterson@computer.org)
http://www.m2technologies.net/

Fields inherited from class org.apache.log4j.AppenderSkeleton
closed, errorHandler, headFilter, layout, name, tailFilter, threshold, THRESHOLD_OPTION
 
Constructor Summary
SNMPTrapAppender()
          Default constructor
SNMPTrapAppender(org.apache.log4j.Layout layoutValue)
          Construct the appender with the specified Layout
 
Method Summary
protected  void append(LoggingEvent event)
          Uses an instance of SNMPTrapSenderFacade to send the String returned by Layout.format() as the message of an SNMP trap.
 void close()
          Does nothing -- not relevant to the implementation.
 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
 int getGenericTrapType()
          Get the generic trap type set for this SNMP PDU
 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
 int getSysUpTime()
          Get the value of the system up time that will be used for the SNMP PDU
 boolean isSnmpDebug()
          Deprecated. This value is no longer used
 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 setGenericTrapType(int genericTrapTypeValue)
          Set the generic trap type for this SNMP PDU.
 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 setSnmpDebug(boolean snmpDebugValue)
          Deprecated. This value is no longer used
 void setSpecificTrapType(int specificTrapTypeValue)
          Set the specific trap type for this SNMP PDU.
 void setSysUpTime(int sysUpTimeValue)
          Set the value of the system up time that will be used for the SNMP PDU.
 
Methods inherited from class org.apache.log4j.AppenderSkeleton
activateOptions, addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getOptionStrings, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setOption, 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"
Overrides:
requiresLayout in class org.apache.log4j.AppenderSkeleton

append

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

close

public void close()
Does nothing -- not relevant to the implementation.
Overrides:
close in class org.apache.log4j.AppenderSkeleton

isSnmpDebug

public boolean isSnmpDebug()
Deprecated. This value is no longer used

Get the value of the snmpDebug property

setSnmpDebug

public void setSnmpDebug(boolean snmpDebugValue)
Deprecated. This value is no longer used

Sets the value of the snmpDebug property. If set to true, and if the underlying SNMP API used by SNMPTrapSenderFacade supports it, this property will cause the SNMP library itself to output diagnostic information (to System.out).

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 (and this appender's default) is 162.

setManagementHostTrapListenPort

public void setManagementHostTrapListenPort(int managementHostTrapListenPortValue)
Set the port used on the remote host to listen for SNMP traps. The standard (and this appender's default) 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 int getSysUpTime()
Get the value of the system up time that will be used for the SNMP PDU

setSysUpTime

public void setSysUpTime(int sysUpTimeValue)
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 1000, 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.