More agent services: monitors and timers - JMX in Action - page 290

12.1.3 Monitoring a value range

The GaugeMonitor class is said to cover a range of values because it is observing
an MBean attribute that could possibly cross a predefined threshold in the mon-
itor. In order to prevent a possible flood of notifications, the Gauge monitor
uses a range of values to cover the threshold. In this way, notifications won't be
sent out when the observed attribute makes many small changes repeatedly over
the threshold.
You accomplish such monitoring by configuring a GaugeMonitor MBean with
a low threshold value and a high threshold value. The monitor sends notifica-
tions the first time the derived gauge (computed from the observed attribute
value) crosses the low or high threshold after crossing the opposite threshold
(unless it is the first occurrence of either).
For example, if the observed derived gauge crosses the high threshold, a noti-
fication is sent. If it then goes below the high threshold, and then rises above it
again, no notification is sent. The observed attribute must first decrease below
the low threshold (a notification could be sent for this event) and then cross the
high threshold again in order for another high-threshold notification to be sent.

Computing the derived gauge
The Gauge monitor can compute its derived gauge value two ways. First, the
derived gauge can be the value of the observed attribute at the current observa-
tion interval. Second, you can configure the GaugeMonitor MBean to compute its
derived gauge by comparing the last two values of the observed attribute. The
two values are stored from the last two observation intervals. Therefore, the
derived gauge value is equal to the observed attribute's last observed value
minus the observed value from the previous interval:

Derived Gauge = value now - value before
If the GaugeMonitor MBean is in its first observation interval, the derived gauge
for the monitor is zero.

Using the Gauge monitor
Just like the String monitor, the Gauge monitor must be configured properly in
order to operate. Table 12.4 lists the methods that implement the features
described in the previous discussion of the Gauge monitor's behavior.
Note that table 12.4 shows only setter methods for the GaugeMonitor MBean's
exposed attributes. However, the class also defines getter methods for the same
attributes. For more information, look at the API reference for the GaugeMonitor class.