Monitor MBeans

To further enhance your control over the management of an application, JMX provides Monitor MBeans that allow you to observe attribute values as they vary over time and to fire notifications when these values exceed specific thresholds.

Monitor MBeans monitor attributes in other MBeans at specified intervals and derive a value from this observation called the derived gauge. The derived gauge is either the exact value of the attribute, or optionally the difference between two consecutive observed values of a numeric attribute. Depending on the Monitor MBean and its setup, it then can emit an MBean Notification. Monitors can also send notifications when error cases are encountered during monitoring.

Monitors are MBeans as well, and so can be created or destroyed dynamically. Typically, Monitor MBeans are used in combination with the statistics captured by the Runtime MBeans. For example, you could write an MBean to monitor the connection delay time of connections in a JDBC connection pool, or the number of messages dropped in a JMS destination. The Monitor MBean could then send a notification when certain thresholds are crossed. This gives you the opportunity to listen for those notifications and take some appropriate action.

20.6.1 Types of Monitors

There are three types of Monitor MBeans, each explained in depth in the JMX specification:

CounterMonitor

This can observe Integer attributes that behave like a counter. That is, the attribute value is always greater than or equal to zero, they can only be incremented, and they may roll over. This monitor sends a notification when the derived gauge exceeds a threshold, after which you can have the monitor automatically increase the threshold by some offset.

GaugeMonitor

This can observe Integer, Float, or Double attributes that behave like gauges, arbitrarily increasing or decreasing. Notifications are sent when values exceed a high or low threshold. A hysteresis mechanism ensures that repeated triggering of notifications doesn't occur.

StringMonitor

This can observe String attributes. The derived gauge is always the value of the attribute, and the monitor fires events when the observed attribute differs from some initialized String value.

Notifications sent by these monitors are all instances of the MonitorNotification class. This subclass of the usual Notification event class includes information such as the observed MBean's object name, attribute name, derived gauge, and threshold value or string that triggered the notification. Note that the type property of the Notification class is a string that represents the type of monitor notification. This notification type is a string of the form jmx.monitor.*. For example, the Gauge monitor will send notifications of two possible types: jmx.monitor.gauge.low or jmx.monitor.gauge.high.

20.6.2 An Example Monitor

As mentioned earlier, the JMX specification provides an in-depth description of these standard JMX monitors. Here, we'll look at how to create a Monitor MBean for WebLogic. This example creates a Counter Monitor MBean that observes the invocation count on the FileServlet, which is responsible for serving requests for static files within a particular web application.

The first thing we want to do is create a new NotificationListener specialized to handle Monitor notifications so that we can access the additional information available:

public class MyMonitorListener implements RemoteNotificationListener {
 public void handleNotification(Notification notification, Object obj) {
 System.err.println("Received Notification");
 System.err.println("Message: " + notification.getMessage( ));
 System.err.println("Type: " + notification.getType( ));
 if (notification instanceof MonitorNotification) {
 MonitorNotification monitorNotification =
 (MonitorNotification) notification;
 System.out.println("This is a MonitorNotification");
 System.out.println("Observed Attribute: "
 + monitorNotification.getObservedAttribute( ));
 System.out.println("Observed Object: " 
 + monitorNotification.getObservedObject( ));
 System.out.println("Trigger value: " + monitorNotification.getTrigger( ));
 }
 }
}

When you monitor something, you need to construct ObjectNames for both the Monitor MBean and the target MBean that needs to be monitored. Here, we've created names for both the Counter Monitor MBean and FileServlet MBean:

WebLogicObjectName monitorObjectName = new
 WebLogicObjectName("myClusterDomain:Type=CounterMonitor,Name=OurCounter");

WebLogicObjectName myServlet = new
 WebLogicObjectName("myClusterDomain:Location=ServerB,Name=ServerB_ServerB_" +
 "DefaultWebApp_weblogic.servlet.FileServlet_94," +
 "ServerRuntime=ServerB,Type=ServletRuntime");

In this case, the FileServlet MBean is deployed under the DefaultWebApp on ServerB. Its exact name may differ depending on your deployment.

Our Counter Monitor needs to observe the InvocationTotalCount property, whose value gets incremented every time the DefaultWebApp serves up a static file. We now can create a CounterMonitor and configure it to send a notification only if more than 15 requests have been made, and subsequently with an offset value of 10:

CounterMonitor monitor = new CounterMonitor( );
monitor.setObservedAttribute("InvocationTotalCount");
monitor.setThreshold(new Integer(15));
monitor.setOffset(new Integer(10));
monitor.setNotify(true);
monitor.setObservedObject(myServlet);

Finally, we need to instantiate our listener object, bind it to the monitor, register our monitor with the register, and start the monitor:

MyMonitorListener listener = new MyMonitorListener( );
monitor.addNotificationListener(listener, null, null);
monitor.preRegister(mb.getMBeanServer( ), monitorObjectName);
monitor.start( );

After requesting a static file (say, index.html within the web application) a number of times, the code produces the following output:

Received Notification
Message: 
Type: jmx.monitor.counter.threshold
This is a MonitorNotification
Observed Attribute: InvocationTotalCount
Observed Object: myClusterDomain:Location=ServerB,
Name=ServerB_ServerB_DefaultWebApp_weblogic.
 servlet.FileServlet_94,ServerRuntime=ServerB,Type=ServletRuntime
Trigger value: 15

In fact, we observe that further notifications are fired when the same static file receives 25 hits, again when it receives 35 hits, and so on.