Java Dynamic Management Kit 3.2 Programming Guide
[ Previous ][ Fast Back ]Chapter 15. Event Handling, Alarm Clock, and Monitoring Services[ Fast Forward ][ Next ]

Monitoring Service

The monitoring service enables the variation with time of a property in an m-bean to be monitored. The observed property is monitored at intervals specified by the granularity period. An event notification is sent when the value of the property satisfies one of a set of conditions. You specify the conditions when you initialize a monitor.

Types of Monitor

Information on the value of a property within an m-bean is provided by two different monitors:

Both monitors are defined as Java classes that extend one of the following generic monitor classes:

Each of these classes defines attributes and methods common to both types of monitor.

Counter Monitor

A counter monitor sends an event notification when the value of the counter reaches or exceeds a threshold known as the comparison level. In addition, an offset mechanism enables particular counting intervals to be detected.

If the counter can wrap around its maximum value, then the modulus of the counter needs to be specified. The modulus is the value at which the counter is reset to zero. The operation of the counter monitor is illustrated in Figure 15-3.


Note - The counter monitor can only be used with properties of type integer. The property must be increased in increments of one unit only.


Gauge Monitor

A gauge monitor observes a property that is continuously variable with time. A high threshold value and a low threshold value are specified. Events are sent as follows:

This provides a hysteresis mechanism to avoid repeated triggering of event notifications when the value of the property makes small oscillations around the high or low threshold value.


Note - The gauge monitor can only be used with properties of type integer or float.


The operation of the gauge monitor is illustrated in Figure 15-4.

Adding a Monitor

You can add a monitor to an agent or a manager, depending on where you want the events the monitor sends to be processed. To add a monitor, create an instance of the Java class that implements the monitor you want to add.

Monitor

Java Class

Counter:

 

  • Agent

com.sun.jaw.impl.agent.services.monitor.CounterMonitor

  • Manager

com.sun.jaw.impl.agent.services.monitor.CounterMonitorMO

Gauge:

 

  • Agent

com.sun.jaw.impl.agent.services.monitor.GaugeMonitor

  • Manager

com.sun.jaw.impl.agent.services.monitor.GaugeMonitorMO

Example 15-17 shows code for creating and initializing a counter monitor in an agent.

Example 15-17. Creating and Initializing a Counter Monitor
// Counter Monitor
//
try {
      CounterMonitor cm = (CounterMonitor)
        cmf.newObject
            ("com.sun.jaw.impl.agent.services.monitor.CounterMonitor",
            cmf.getDomain()+":"+"com.sun.jaw.impl.agent.services.monitor.
                                                  CounterMonitorMO.id=1");

// The object to be added as listener implements the MonitorListener interface
      cm.addMonitorListener((MonitorListener) this); // this - current instance
      cm.setObservedObject(object_name);
      cm.setObservedProperty(property_name);
      cm.setGranularityPeriod(new Integer(30000));   //* 30 secs */
      cm.setComparisonLevel(new Integer(3));
      cm.setNotifyOnOff(new Boolean(true));
      cm.setOffsetValue(new Integer(2));
      cm.setCounterDifferenceOnOff(new Boolean(false)); // True if diff counter
      cm.performStart();
      } catch (Exception e) {
      System.out.println("Exception occurs: " + e.getMessage());
      e.printStackTrace();
      System.exit(0);
      }

Example 15-18 shows code for creating and initializing a gauge monitor in an agent.

Example 15-18. Creating and Initializing a Gauge Monitor
// Gauge Monitor
//
try {
      GaugeMonitor gm = (GaugeMonitor)
        cmf.newObject
            ("com.sun.jaw.impl.agent.services.monitor.GaugeMonitor",
            cmf.getDomain()+":"+"com.sun.jaw.impl.agent.services.monitor.
                                                 GaugeMonitorMO.id=1");
// The object to be added as listener implements the MonitorListener interface
      gm.addMonitorListener((MonitorListener) this); //this - current instance
      gm.setObservedObject(object_name);
      gm.setObservedProperty(property_name);
      gm.setGranularityPeriod(new Integer(20000));     // 20 secs
      gm.setThresholdLowValue(new Integer(20));
      gm.setThresholdHighValue(new Integer(80));
      gm.setNotifyLowOnOff(new Boolean(true));
      gm.setNotifyHighOnOff(new Boolean(true));
      gm.setGaugeDifferenceOnOff(new Boolean(false));  // True if diff gauge
      gm.performStart();
      } catch (Exception e) {
      System.out.println("Exception occurs: " + e.getMessage());
      e.printStackTrace();
      System.exit(0);
      }

Listening for Monitor Events

All events sent by a monitor are instances of the class com.sun.jaw.impl.agent.services.monitor.MonitorEvent, regardless of the type of monitor. The constructor for this class requires that the monitor that sent the event, the event type, and information about the cause of the event are specified.

To enable an application to receive monitor events, you have to make sure that the application implements a monitor listener interface. The interface your application must implement is independent of the type of monitor, although it depends whether the application is an agent or a manager:

Application

Java Interface

Agent

com.sun.jaw.impl.agent.services.monitor.MonitorListener

Manager

com.sun.jaw.impl.agent.services.monitor.MonitorListenerMO

Both of these interfaces contain a single method for handling monitor events. The prototype of this method on the agent side is defined in Example 15-19.

Example 15-19. Prototype of the handleMonitorEvent() Method
public abstract void handleMonitor(MonitorEvent event);

An application that receives monitor events must also include code for registering itself as a monitor listener. To add a monitor listener, invoke the addMonitorListener() method of the monitor as shown in Example 15-20. In this example, gm is an instance of the GaugeMonitor class instantiated as shown in Example 15-18.

Example 15-20. Adding a Monitor Listener
gm.addMonitorListener((MonitorListener) this);
// this - current instance

Specifying the Property to be Monitored

A monitor observes a particular property in a particular m-bean instance. To specify the property to be monitored, invoke both of these methods of the monitor:

Code for specifying the object name of an m-bean instance and the property in it to be monitored is shown in Example 15-21. In this example, gm is an instance of the GaugeMonitor class instantiated as shown in Example 15-18. The monitor monitors the property NbChanges in the only instance of the SimpleBean class present in the default domain of the agent.

Example 15-21. Specifying a Property to be Monitored
// ObjectName of object to be monitored
ObjectName object_name = new
ObjectName("defaultDomain:SimpleBean");
...
// String representing the name of the property to be monitored
String property_name = new String("NbChanges");
...
gm.setObservedObject(object_name);
gm.setObservedProperty(property_name);

Setting the Granularity Period

The observed property is monitored at intervals specified by the granularity period. It is specified in milliseconds. To set the granularity period, invoke the setGranularityPeriod() method of the monitor, as shown in Example 15-22. In this example, cm is an instance of the CounterMonitor class instantiated as shown in Example 15-17. The granularity period is set to 30,000 milliseconds (30 seconds).

Example 15-22. Setting the Granularity Period of a Monitor
cm.setGranularityPeriodAsLong(new Long(30000)); // 30 seconds

Specify a granularity period that is consistent with the rate at which the property changes.

Setting Parameters for Counter Monitors

Figure 15-3 shows the operation of a counter monitor. The monitor monitors a counter C(t) which varies with time t. The granularity period is G and the comparison level is T.

Figure 15-3. Operation of the Counter Monitor

fig838.epsi

A counter monitor sends an event notification when the value of the counter reaches or exceeds the comparison (threshold) level. After the event has been sent, the comparison level is incremented by the offset value until the comparison level is greater than the current value of the counter.

Setting the Comparison Level for a Counter Monitor

When a monitored counter reaches or exceeds its comparison level, an event is sent if specified. To set the comparison level, invoke the setComparisonLevel() method of the counter monitor. To specify whether an event is sent, invoke the setNotifyOnOff() method of the counter monitor. This is shown in Example 15-23. In this example, cm is an instance of the CounterMonitor class instantiated as shown in Example 15-17. The comparison level is three and an event will be sent when the counter reaches or exceeds this value.

Example 15-23. Setting the Threshold Value of a Counter Monitor
cm.setComparisonLevel(new Integer(3));
cm.setNotifyOnOff(new Boolean(true));

As shown in Figure 15-3, an event is sent as soon as the counter is monitored after its value has reached the initial comparison level of three.

Setting the Offset for a Counter Monitor

The counter monitor provides an offset mechanism to enable a counting interval to be detected. If you specify an offset value, the comparison level is increased by the offset value each time the current comparison level is reached. This takes place before the counter is increased to avoid duplicate events being sent. To set the offset value, invoke the setOffsetValue() method of the counter monitor, as shown in Example 15-24. In this example, cm is an instance of the CounterMonitor class instantiated as shown in Example 15-17. The offset value is two.

Example 15-24. Setting the Offset Value
cm.setOffsetValue(new Integer(2));

As shown in Figure 15-3, an event is sent as soon as the counter is monitored after its value reaches the comparison level (after the first addition of the offset) at five, and (after the second addition of the offset) at seven.

Setting the Modulus Value for a Counter Monitor

If the counter you are monitoring is able to wrap around when it reaches its maximum value, you must set its modulus value. The modulus is the value at which a counter is reset to zero. To set the modulus, invoke the setModulusValue() method of the counter monitor. This is shown in Example 15-25. The modulus value is 500.

Example 15-25. Setting the Modulus Value
cm.setModulusValue(new Integer(500));

Using a Counter Monitor to Track Differences

Using a counter monitor to track differences enables you to observe the rate at which a counter changes. If you specify the counter difference option, an event is sent when the derived gauge reaches or exceeds the comparison level. The derived gauge is calculated as the difference between the observed counter values for two successive observations. If this difference is negative, that is, the counter has wrapped around, then the value of the derived gauge is increased by the value of the modulus. This can be expressed algebraically as follows:

where:

To specify the counter difference option, invoke the setCounterDifferenceOnOff() method of the counter monitor. This is shown in Example 15-26. In this example, cdm is an instance of the CounterMonitor class.

Example 15-26. Monitoring Counter Differences
cdm.setCounterDifferenceOnOff(new Boolean (true));

Setting Parameters for a Gauge Monitor

Figure 15-4 shows the operation of a gauge monitor. The monitor monitors a property P(t) that varies with time t. The granularity period is G, the lower threshold is TL, and the higher threshold is TH.

Figure 15-4. Operation of the Gauge Monitor

fig836.epsi

Setting the Threshold Values for a Gauge Monitor

To set the threshold values invoke these methods of the gauge monitor:

You have to set threshold values in pairs. This restriction enables the gauge monitor to provide a hysteresis mechanism. The difference between the high and low threshold values is the hysteresis interval.

The high threshold value and the low threshold value must be of the same type as the observed property. The high threshold value must be greater than or equal to the low threshold value.

To specify whether an event is sent, invoke these methods of the gauge monitor:

This is shown in Example 15-27. In this example, gm is an instance of the GaugeMonitor class instantiated as shown in Example 15-18. The low threshold value is 20 and the high threshold value is 80. Threshold high and threshold low events will be sent when the event conditions are satisfied.

Example 15-27. Setting the Threshold Values for a Gauge Monitor
gm.setThresholdLowValue(new Integer(20));
gm.setThresholdHighValue(new Integer(80));
gm.setNotifyLowOnOff(new Boolean(true));
gm.setNotifyHighOnOff(new Boolean(true));

Using a Gauge Monitor to Track Differences

Using a gauge monitor to track differences enables you to observe the rate at which a gauge property changes. If you specify the gauge difference option, an event is sent when the derived gauge exceeds its specified upper or lower threshold according to the hysteresis mechanism. The derived gauge is calculated as the difference between the observed property values for two successive observations. This can be expressed algebraically as follows:

V(t) = P(t) - P(t-G)

where:

To specify the gauge difference option, invoke the setGaugeDifferenceOnOff() method of the gauge monitor as shown in Example 15-28. In this example, gdm is an instance of the GaugeMonitor class.

Example 15-28. Monitoring Gauge Differences
gdm.setGaugeDifferenceOnOff(new Boolean(true));

Setting Multiple Thresholds for a Property

For a single monitor you are allowed to specify only one pair of threshold values. To specify more than one pair of threshold values, create one monitor for each pair of threshold values you want to specify. Make sure that each monitor you create monitors the same property in the same m-bean instance.

Starting and Stopping a Monitor

To start or stop a monitor, invoke the performStart() or performStop() method of the monitor. Example 15-29 shows how to start and stop a monitor. In this example, gm is an instance of the GaugeMonitor class instantiated as shown in Example 15-18.

Example 15-29. Starting and Stopping a Monitor
gm.performStart();         // Starts the monitor
...
gm.performStop();          // Stops the monitor

When a monitor is stopped, it is reset. For a counter monitor, this means that when the monitor is restarted, the comparison level is reset to the value specified in the last invocation of the setComparisonLevel method. For a gauge monitor, this means that when the monitor is restarted, there is no record of the type (TH or TL) of the last event sent. An event is sent as soon as one of the thresholds is reached or exceeded.


[ Previous ][ Home ][ Next ]
Scheduler Service[ Up ]Discovery Service