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

12.1.4 Monitoring a counted value

The final monitor MBean we'll discuss is the CounterMonitor MBean. The Coun-
terMonitor class defines an object that observes a numeric MBean attribute,
watching for it to exceed a threshold value. The observed attribute is assumed to
be positive and to have an increasing value (because it is a counter).
The observed counter attribute is allowed to have a maximum value that,
when reached, causes the counter to roll over to its starting position. In order for
the counter to roll over, the Counter monitor must know the maximum value,
which it stores as its modulus value.
The Counter monitor will send a notification each time the observed counter
crosses its threshold value. This does not mean a notification will be sent for
every observation interval where the counter is above the threshold—the
counter must go below the threshold after each notification in order to send
another notification.
The Counter monitor also supports an offset value that is added to the
threshold value when the observed counter exceeds the threshold. This offset
allows users to monitor a counter moving through increments. After the counter
has exceeded the threshold value, if the monitor contains an offset value, the
monitor will keep adding the offset value to the threshold value until it is greater
than the counter. If the monitor also contains a modulus value (the observed
counter's maximum value before rollover), and if adding the offset value exceeds
the modulus, the threshold will reset to its original value.

Computing the derived gauge
Just like the previous monitor, the CounterMonitor MBean can compute its
derived gauge two ways. The method it uses depends on the monitor's configu-
ration by the user. If the monitor's DifferenceMode attribute is true , then the
derived gauge is calculated like the GaugeMonitor MBean's. That is, the monitor
subtracts the previous observed counter value from the current value. If the
result is negative, the monitor will then add the modulus value. Otherwise, if the
result is positive, it is the final value of the derived gauge.
If the DifferenceMode is false, the derived gauge value is simply the value of
the counter in the latest observation interval.

Using the Counter monitor
Table 12.5 lists the methods of the CounterMonitor MBean class that support the
behavior described in the previous section. Like the previous tables, this one
doesn't include the getter methods.