Traps

WebLogic's SNMP agent can be configured to send a number of notification traps for instance, when a log message is logged, when an attribute value has changed, or when configured thresholds for a monitor are exceeded.

Each trap notification is sent as a trap protocol data unit (PDU), which includes the following standard information:

Enterprise OID

The enterprise OID field in all trap notifications sent by WebLogic is set to WebLogic's OID, .1.3.6.1.4.140.625.

Agent address

The agent address of the PDU is set to the IP address of the WebLogic server on which the trap was generated.

Generic trap type

The generic trap type of the PDU indicates the generic type of the trap. A value of 0 is used when the trap represents the start of the Administration Server. A value of 4 indicates an authentication failure and is generated when an incorrect community string is sent to WebLogic. Finally, a value of 6 is set for all other traps. Note that the Administration Server coldstart trap (0) and the authentication failure trap (4) are sent automatically in any configured SNMP agent.

Specific trap types

Different SNMP agents are permitted to further qualify the enterprise trap types by indicating an enterprise-specific trap type. Table 22-2 lists the specific trap types used in WebLogic.

Table 22-2. WebLogic-specific trap type values and their descriptions

Value	Description
65	This trap type is sent when a Managed Server that was previously down is started.
70	This trap type is sent when a Managed Server is shut down.
80	This trap type is generated when an observed attribute's value changes.
60	This trap type is generated when a matching log message has been sent.
75	This trap type is generated when a JMX monitor fires.

The trap types for the server starting up and shutting down are set automatically in the event of these servers cycling.

Timestamp

A PDU also can include a timestamp, indicating the length of time between the last reinitialization of WebLogic's SNMP agent and the time at which the trap was issued.

One or more variable bindings

Finally, a PDU may include a number of name/value pairs that convey further information about the trap notification. For instance, the server startup and shutdown traps, type 65 and 70 in Table 22-2, have two name/value pairs that are passed with the trap PDU. The first, trapTime, indicates the time that the event occurred. The second, trapServerName, indicates the name of the server that generated the trap.

22.3.1 Trap Destinations

In order for external management agents to use WebLogic's SNMP, you have to register the management agents with WebLogic as trap destinations. Only then can WebLogic send all notification traps that occur to the registered trap destinations.

To create a trap destination, select the SNMP/Trap Destinations node in the left pane of the Administration Console and choose the "Configure a new SNMP Trap Destination" option. Then you need to enter the address and port of the management agent to which the traps should be sent, as well as the community name that should be used when sending the traps. In this case, the community name is simply the configured password that should be used for the management agent you are using.

In this way, you can create a number of trap destinations that are interested in WebLogic's SNMP notifications. Once you set up a number of trap destinations, select the SNMP node and, using the Targeted Trap Destinations option, select the trap destinations to which the trap notifications ought to be sent.

22.3.2 Attribute Change Traps

Attribute change traps behave like JMX attribute notifications. They are sent when an attribute is added, removed, or updated. For example, you can configure the SNMP agent to send a trap when the attribute indicating the capacity of a JDBC connection pool changes. The trap types can be sent only for configuration MBeans and cannot be used for runtime attributes. The MIB indicates which attributes belong to the configuration MBeans. Table 22-3 indicates the name/value pairs that are associated with this trap notification.

Table 22-3. Variable name/value pairs for attribute trap notifications

Name	Value
trapTime	This value indicates the time at which the trap was generated.
trapServerName	This value indicates the name of the server that generated the trap, which in general will be the name of the Administration Server.
trapMBeanName	This value indicates the name of the MBean that contains the attribute.
trapMBeanType	This value indicates the type of the MBean.
trapAttributeName	This value indicates the name of the configuration attribute that has changed.
trapAttributeType	This value indicates the type of the attribute.
trapAttributeChangeType	This value indicates the type of change. It will be set to either ADD, REMOVE, or UPDATE.
trapAttributeOldVal	This value indicates the value of the attribute before the change.
trapAttributeNewVal	This value indicates the value of the attribute after the change.

You can create an attribute change trap by using the Administration Console and navigating to the SNMP/Traps/Attribute Changes node from the left pane. Here, you have to fill in either the MBean's type or name and the name of the attribute that you want to monitor. Finally, make sure that you target the servers on which you want the attribute watched. WebLogic displays all of the available MBean types in a drop-down box.

As an example, you can set up the agent to send a trap when the initial capacity of a JDBC connection pool is changed. In order to do this, simply specify the MBean type as JDBCConnectionPoolMBean and the attribute name as InitialCapacity. WebLogic's SNMP agent then will fire a trap notification whenever anybody changes the initial capacity for the connection pool.

22.3.3 Log Message Traps

In Chapter 21, we looked at WebLogic's logging architecture and how the Administration Server collects log messages from all the Managed Servers in the domain and writes them to a domain log. In this context, you can also set up the Administration Server to send SNMP log notification traps. To do this, select the SNMP/Traps/Log Filters node from the left pane of the Administration Console. Here you can configure a log filter by specifying values for the minimum severity level, subsystem names, user IDs, message IDs, and a message substring. For example, if you need to set up a trap so that a trap notification is fired when a Warning log message is sent, then you simply create a new log filter whose Severity Level option is set to Warning. Table 22-4 indicates the name/value pairs that are associated with this trap notification.

Table 22-4. Variable name/value pairs for log trap notifications

Name	Value
trapTime	This indicates the time at which the trap was generated.
trapServerName	This will be set to the name of the server instance that generated the trap.
trapMachineName	This will be set to the name of the machine hosting the server instance.
trapLogThreadId	This indicates the ID of the thread that generated the log message.
trapLogTransactionId	If the log message was generated while in a transaction, this indicates the transaction ID.
trapLogUserId	If the log message was generated while in a security context, this indicates the user ID associated with the security context.
trapLogSubsystem	This indicates the subsystem that generated the log message.
trapLogMsgId	This indicates the ID of the log message.
trapLogSeverity	This indicates the severity level of the message.
trapLogMessage	This contains the text of the log message.

 

22.3.4 Monitor Traps

WebLogic's SNMP agent can take advantage of the JMX monitors described earlier in Chapter 20. Special JMX monitors can be established that poll MBeans and send notifications when specified conditions occur. These JMX monitor notifications then can be routed automatically to the SNMP agent, which in turn generates a trap notification. WebLogic's SNMP supports all three JMX monitor types:

• String monitors can monitor attributes and generate a notification when the value of an attribute differs from some predefined string.
• Counter monitors can monitor incrementing attribute values and generate a notification when a certain threshold value is reached. In addition, they can optionally add an offset or subtract a modulus to establish a new threshold value.
• Gauge monitors can generate notifications when either the high or low threshold values are exceeded.

In all cases, you need to follow the same procedure to create a monitor trap. Using the Administration Console, choose the SNMP/Traps/Monitors node from the left pane and then select the type of monitor that should generate these traps. You also need to supply the name of the attribute that is to be monitored, the polling interval at which to check if the conditions of the monitor apply, and the MBean type or name. In addition, you have to supply the information necessary for each monitor type. For string monitors, this means the string to compare against, for counter monitors, this means the threshold, offset and, modulus values, and for gauge monitors, this means the high and low threshold values.

In Chapter 20, we looked at how to create a Counter Monitor MBean that monitored the number of times the FileServlet was invoked. To achieve the same behavior using WebLogic's SNMP agent, create a new counter monitor so that the MBean type is set to ServletRuntime, the MBean attribute is set to InvocationTotalCount, and the MBean name is set to ServerB_ServerB_DefaultWebApp_weblogic.servlet.FileServlet_94. As explained, these values can be obtained easily using the weblogic.Admin tool, and will depend on your particular deployment. Finally, you need to target the monitor to the appropriate server in our case, ServerB.

Table 22-5 indicates the name/value pairs that are associated with this trap notification.

Table 22-5. Variable name/value pairs for monitor trap notifications

Name	Value
trapTime	This indicates the time at which the trap was generated.
trapServerName	This indicates the name of the server whose attribute value is being monitored.
trapMBeanName	This is the name of the MBean that contains the attribute being monitored.
trapAttributeName	This is the name of the attribute whose value is being monitored.
trapMonitorType	This will be set to either CounterMonitor, StringMonitor, or GaugeMonitor.
trapMonitorThreshold	This is an ASCII representation of the threshold that triggered the trap.
trapMonitorValue	This is an ASCII representation of the values that triggered the trap.