Trap Notifications

 

This section discusses the following topics:

• SNMP Trap Format

• Attribute Change Traps

• Log Message Traps

• Monitor Traps

 

---

Overview of WebLogic SNMP Trap Types

A report of the occurrence of an event or crossing of a threshold, sent to an SNMP manager by an SNMP agent, is called a trap notification. There are several types of trap notification that the WebLogic SNMP agent software can generate:

• Predefined WebLogic SNMP Traps

  These traps are automatically generated by the SNMP agent when certain predefined conditions occur (if the agent is enabled).

• Attribute Change Traps

  These traps are generated when WebLogic attributes you select change in value.

• Log Message Traps

  These traps are emitted when log messages satisfying criteria you specify are generated on a local WebLogic Server.

• Monitor Traps

  These traps are generated when a Java Management Extension (JMX) monitor that you have created detects the crossing of a threshold, or the occurrence of a specified condition, as defined by you.

This section describes how to set up the WebLogic SNMP agent to generate these various types of trap notification. For information on how to set up the destinations where trap notifications are to be sent, refer to Using SNMP to Manage WebLogic Server.

 

---

SNMP Trap Format

The SNMP standard defines a trap notification sent to a manager as a protocol data unit (PDU) with the fields indicated in Figure 2-1.

Figure 2-1 SNMP Trap Packet

 

The fields have the following meaning:

• PDU type identifies the packet as a trap notification.

• enterprise is the vendor identification (OID) for the systems/network management subsystem that generated the trap. All traps generated by the WebLogic SNMP agent have the WebLogic OID .1.3.6.1.4.140.625 in the enterprise field.

• agent address is the IP address of the node where the trap was generated.

• generic trap type is an integer in the range of 0 to 6. Type 6 is an enterpriseSpecific trap type, which has no standard interpretation in SNMP. The interpretation of the trap depends upon the value in the specific trap type field, which is defined by a vendor's custom MIB.

• specific trap type is a number that further specifies the nature of the event that generated the trap in the case of traps of generic type 6 (enterpriseSpecific). For enterpriseSpecific traps generated by the WebLogic SNMP agent, the values in the specific trap type field are those indicated in Table 2-1. These values are defined by the BEA WebLogic MIB.

• timestamp is the length of time between the last re-initialization of the agent that issued the trap and the time at which the trap was issued.

• variable bindings provide additional information pertaining to the trap.This field consists of name/value pairs. The significance of this field is vendor-specific. The content of the variable bindings in enterpriseSpecific traps generated by the WebLogic SNMP agent is determined by the WebLogic MIB definitions (see the WebLogic SNMP MIB Reference). The variable bindings are discussed below.

Note: The enterprise OID used by the WebLogic 6.1 SNMP agent differs from the enterprise OID used with the WebLogic 5.1 SNMP agent. The enterprise OID for WebLogic 6.1 is .1.3.6.1.4.140.625.

WebLogic Specific Trap Types

The following table describes the specific trap types for the enterpriseSpecific traps generated by the WebLogic SNMP agent.

Table 2-1 WebLogic Specific Trap Types

WebLogic Specific Trap Number	Type of Trap	Meaning
60	Log Message Trap	Generated when a message is logged at a server that matches the user-defined criteria for a sending a log notification trap.
65	serverStart Trap	Generated when the agent detects that a Managed Server is up that was formerly down.
70	serverShutDown Trap	Generated when the agent detects that a Managed Server that was up is now down.
75	Monitor Trap	Generated when a user-defined JMX monitor detects the crossing of a threshold or occurrence of an event, as defined by the user.
80	Attribute Change Trap	Generated when the agent detects that an attribute selected by the user has changed in value.

Predefined WebLogic SNMP Traps

The WebLogic SNMP agent generates the following generic traps automatically:

• coldStart trap — This trap has a generic trap number of 0 and is generated whenever the Administration Server comes up, if the SNMP Service is enabled.

• authenticationFailure trap — This trap has a generic trap number of 4 and is sent to any management station that sends an incorrect SNMP community string. The community string prefix is the actual password and must match the value that you set in the Community Prefix field when configuring the WebLogic SNMP agent in the Administration Console. (See Using SNMP to Manage WebLogic Server for the required format for community strings as sent by SNMP managers.)

All other trap notifications generated by the WebLogic SNMP agent are enterprise-specific traps (generic type 6).

The following enterpriseSpecific trap notifications are also generated automatically by the agent:

• serverStart — This trap is generated whenever the SNMP agent detects that a WebLogic Managed Server that was down is now up.

  This trap has a specific type value of 65. The first two name/value pairs in the variable bindings will be the start time and the server name.

• serverShutDown — This trap is generated whenever the SNMP agent detects that a WebLogic Managed Server that was up is now down.

  This trap has a specific type value of 70. The first two name/value pairs in the variable bindings will be the down time and the server name.

 

---

Attribute Change Traps

To set up the WebLogic SNMP agent to notify your SNMP agent when a selected WebLogic configuration attribute has changed, do the following:

1. Invoke the Administration Console (if it is not already running).

2. Select SNMP—>Traps—>SNMP Attribute Changes in the left pane. This invokes the attribute change table. This table lists the filters that you have created to send SNMP traps when the agent detects a change on a selected configuration attribute. There is one filter in the table for each configuration attribute that the agent is monitoring.

3. To create a new attribute change filter, select the Create a new Attribute Change link to invoke the Attribute Change screen. Fill out the fields on this screen as follows:

   • Name — Enter a name for this filter. You might name the filters to suggest the attribute that you are monitoring.

   • Attribute MBean Type — This is the type of the configuration MBean that includes the attribute you wish to monitor.

   • Attribute MBean Name — This is the name of the configuration MBean that has the attribute you wish to monitor.

   • Attribute Name — This is the name of the attribute you wish to monitor.

   • Select the servers on which you want to check for attribute changes.

4. Click Apply to create the new attribute change filter.

5. To activate the new attribute change filter, restart the Administration Server.

An attribute change trap notification includes the following name/value pairs in the variable bindings:

• trapTime — The time at which the trap was generated.

• trapServerName — The name of the Administration Server.

• trapMBeanName — Name of the MBean that includes the attribute.

• trapMBeanType — Type of the MBean that includes the attribute.

• trapAttributeName — Name of the configuration attribute that has changed.

• trapAttributeChangeType — The value can be either ADD, REMOVE, or UPDATE.

• trapAttriruteOldVal — Value of the attribute before the change.

• trapAttributeNewVal — Value of the attribute after the change.

Note: Creation of monitors for changes in run-time attributes is not supported. Only attributes in the configuration MIB can be monitored for change of attribute value.

 

---

Log Message Traps

The WebLogic logging subsystem logs messages into a local log at each WebLogic Server. The SNMP agent can register a log message filter on a local server which selects log messages that the agent wants to be notified about. When a log message is generated on the local WebLogic Server that satisfies the filter, a JMX log notification is sent to the agent and the agent generates an SNMP log notification trap.

You can define the log notification filter to select log messages based on the following attributes of the log message:

• Severity level

• Subsystem name

• User ID

• Message ID

• Message substring (a string to search for in the message text)

Creating a Log Notification Filter

To create a log notification filter, do the following:

1. Invoke the Administration Console (if it isn't running already)

2. Select SNMP—>Traps—>SNMP Log Filters in the left pane. This invokes the SNMP Log Filter table, which lists all the filters that you have registered with local servers.

3. To create a new log filter, select the Create a new Log Filter link to invoke the SNMP Log Filter screen. You will need to fill out the fields on this screen as follows:

   • Give the new filter a name in the Name field.

   • Select the servers that you wish to have this filter registered with.

   • Select the attributes and attribute values that you wish the local server to use to select log messages that will be used to generate log message traps.

4. Click Apply to create the new log message filter.

5. Restart the Administration Server to activate the new log message filter.

Variable Bindings in Log Message Traps

The attributes of the log message are passed to the SNMP manager in the variable bindings of the trap. Log notification traps have the following name/value pairs on the variable bindings:

• trapTime — Time when the trap is generated.

• trapServerName — Name of the local server that generated the log message.

• trapMachineName — Name of the machine that the server is running on that generated the log message.

• trapLogThreadId — Thread ID from the log message.

• trapLogTransactionId — Transaction Id, if any, from the log message. There will only be a transaction Id if the log message occurred in the context of a transaction.

• trapLogUserId — The User Id from the log message.

• trapLogSubsystem — The subsystem name from the log message.

• trapLogMsgId — The log message Id from the log message.

• trapLogSeverity — The message severity level from the log message.

• trapLogMessage — The text of the log message.

For more information on log messages and the WebLogic Server logging subsystem, see the WebLogic Server Administration Guide.

 

---

Monitor Traps

The WebLogic SNMP agent allows you to configure Java Management Extension (JMX) monitors to poll WebLogic resources at a specified interval to check for the occurrence of conditions or the crossing of thresholds, as defined by you, the user. When a user-defined monitor detects the specified condition, a trap notification is sent to the SNMP manager. This feature allows you to offload polling of WebLogic resources from the SNMP management station to the WebLogic Administration Server.

You can configure three types of JMX monitor:

• Counter Monitor

  A counter monitor defines a threshold that is an integer value. A trap is generated if the agent detects that attribute equals or exceeds the threshold value. You can also specify values to add to or subtract from the threshold for subsequent checks of the attribute value.

• Gauge Monitor

  A gauge monitor defines a high and a low threshold and generates a trap when the value is equal to or exceeds the high threshold or is equal to or less than the low threshold.

• String Monitor

  A string monitor does a compare between a string you provide and the value of the chosen attribute. You can specify that the trap is generated if there is a match between the value and the string you provide, or you can specify that the trap is generated if the value differs from the string you provide.

Configuring a Counter Monitor

To set up a JMX counter monitor, do the following:

1. Invoke the Administration Console (if it is not already running).

2. Select SNMP—>Traps—>Monitors—>SNMP Counter Monitors in the left pane. This invokes the counter monitor table. This table lists all the counter monitors that you have already configured.

3. To create a new counter monitor, select the Create a new Counter Monitor link to invoke the Counter Monitor screen.

4. On the Counter Monitor page, enter a name for the monitor instance in the Name field.

   BEA Systems recommends that you choose a name that indicates the resource that is being monitored.

5. Enter values in the Monitored MBean Type, Monitored Attribute Name, and (optionally) Monitored MBean Name fields.

   For example, if you want to monitor the ActiveConnectionsHighCount attribute of the JDBCConnectionPoolRuntime MBean for a JDBC connection pool name MyPool:

   • In the MBean Type field, enter JDBCConnectionPool Runtime.

   • In the MBean Name field, enter MyPool.

   • In the Attribute Name field, enter ActiveConnectionsHighCount.

6. In the Polling Interval field, enter the frequency in seconds at which you want WebLogic Server to check the attribute's value.

   For testing purposes, consider entering a small value, such as 10.

   A value of 0 means that the monitor never polls the attribute, effectively disabling this monitor.

7. Enter data in the remaining fields as described in the next section, Typical Configurations for Counter Monitors.

8. Click Create.

9. Click the Servers tab.

10. From the Available column, select the servers on which you want to monitor the selected attribute. Then click the right arrow to move the selected servers to the Chosen list.

    If you are configuring a monitor for a domain-wide resource, such as a JDBC Connection Pool, select the Administration Server.

11. Click Apply.

12. Restart the Administration Server.

Typical Configurations for Counter Monitors

The following list describes how to achieve typical configurations of a Counter Monitor instance by entering data on the Counter Monitor page:

• To send a trap when the observed attribute exceeds a threshold, enter a threshold values in the Threshold field.

• To send a trap when the observed attribute exceeds the threshold and then increase the threshold by an offset value, enter a threshold in the Threshold field and an offset value in the Offset field.

  Each time the observed attribute exceeds the new threshold, the threshold is increased by the offset value. For example, if you set Threshold to 1000 and Offset to 2000, when the observed attribute exceeds 1000, the Counter Monitor sends a notification and increases the threshold to 3000. When the observed attribute exceeds 3000, the Counter Monitor sends a notification and increases the threshold again to 5000.

• To specify a maximum value for the threshold, enter a value in the Modulus field. When the threshold reaches the value specified by the modulus, the threshold is returned to the value that was specified through the latest call to the monitor's setThreshold method, before any offsets were applied. For example, if the original Threshold is set to 1000 and the Modulus is set to 5000, when the Threshold exceeds 5000, the monitor sends a notification and resets the Threshold to 1000.

Configuring a Gauge Monitor

To set up a JMX gauge monitor, do the following:

1. Invoke the Administration Console (if it is not already running).

2. Select SNMP—>Traps—>Monitors—>SNMP Gauge Monitors in the left pane. This invokes the gauge monitor table. This table lists all the gauge monitors that you have already configured.

3. To create a new gauge monitor, select the Create a new Gauge Monitor link to invoke the Gauge Monitor screen. You will need to fill out the fields on this screen as follows:

   • Name — Enter a name for this monitor. You might want to choose a name that gives some idea of what it is monitoring.

   • Monitored MBean Type — This is the type of the MBean that includes the attribute that you wish to monitor.

   • Monitored MBean Name — This is the name of the MBean that includes the attribute that you want to monitor.

   • Monitored Attribute Name — The name of the attribute that you want to monitor.

   • Polling Interval — This is the frequency in seconds that the agent is to check the attribute value.

   • Threshold High — A trap will be generated if the attribute value is equal to or greater than the integer value you enter here.

   • Threshold Low — A trap will be generated if the attribute value is equal to or less than the integer value you enter here.

   • Enabled Servers — Select the servers on which you want to monitor the selected attribute.

4. Select Apply to create the new gauge monitor.

5. Restart the Administration Server to activate the new monitor.

Configuring a String Monitor

To set up a JMX string monitor, do the following:

1. Invoke the Administration Console (if it is not already running).

2. Select SNMP—>Traps—>Monitors—>SNMP String Monitors in the left pane. This invokes the string monitor table. This table lists all the string monitors that you have already configured.

3. To create a new string monitor, select the Create a new String Monitor link to invoke the String Monitor screen. Fill out the fields on this screen as follows:

   • Name — Enter a name for this monitor. You might want to choose a name that gives some idea what it is monitoring.

   • String To Compare — This is the string that the monitor will compare to the attribute value to determine whether to generate a trap.

   • Notify Differ — If checked, a trap is generated if the value of the attribute differs from the value entered in the String To Compare field.

   • Notify Match — If checked, a trap is generated if the value of the attribute matches the value you entered in the String To Compare field.

   • Monitored MBean Type — This is the type of the MBean that includes the attribute that you wish to monitor.

   • Monitored MBean Name — This is the name of the MBean that includes the attribute that you want to monitor.

   • Monitored Attribute Name — The name of the attribute that you want to monitor.

   • Polling Interval — This is the frequency in seconds that the agent is to check the attribute value.

   • Enabled Servers — Select the servers on which you want to monitor the attribute specified in the Monitored Attribute Name field.

4. Select Apply to create the new string monitor.

5. Restart the Administration Server to activate the new string monitor.

Variables Included with Monitor Trap

A JMX monitor polls for a specified threshold or condition and the agent generates a monitor trap when the specified threshold is crossed, or the specified condition occurs. The WebLogic SNMP agent includes the following name/value pairs in the variable bindings of each monitor trap:

• trapTime — The time at which the trap was generated.

• trapServerName — The local server whose attribute value generated the trap.

• trapMonitorType — Either CounterMonitor, StringMonitor, or GaugeMonitor.

• trapMonitorThreshold — An ASCII representation of the threshold that triggered the trap.

• trapMonitorValue — An ASCII representation of the value that triggered the trap.

• trapMBeanName — The name of the MBean that contained the attribute being monitored.

• trapMBeanType — The type of the MBean that contained the attribute being monitored.

• trapAttributeName — The name of the attribute whose value triggered the trap.

 

---

Disabling Trap Generation

When you create an entry for a particular type of trap such as a log filter trap or JMX monitor trap, generation of such traps is only activated once the Administration Server is restarted. However, for any trap request that you have created, you can de-activate the trap generation dynamically via the Administration Console (or the weblogic.Admin command line interface).

When you enable trap generation for a particular type of trap, you create an entry in the table for that type of trap that is displayed in the Administration Console. To de-activate that trap, simply delete the entry in the trap table. Thus, if you have created a JMX counter monitor to poll for a specified condition, you can turn off that monitor by deleting the entry for that counter monitor in the table at SNMP—>Traps—>Monitors—>SNMP Counter Monitors.