6.1 The JMX Monitor Service

The javax.management.monitor package provides a set of monitoring services that JMX-based management applications can use to monitor MBeans registered with the MBeanServer. Each of these services is packaged as an MBean. Management applications create and manipulate monitors via the MBeanServer just like they do other MBeans.

6.1.1 The Monitoring Package Structure

The monitoring package is composed of four interfaces and five classes. Figure 6.1 illustrates their interrelationships.

Figure 6.1. Static Structure of the javax.management.monitor Package

The abstract Monitor class is the core of the package. It extends NotificationBroadcasterSupport so that its instances can send JMX notifications when they detect conditions of interest to management applications. Because each of its concrete subclasses will be MBeans, Monitor also implements the MonitorMBean interface, which captures the common aspects of a monitor's management interface. Finally, Monitor implements MBeanRegistration , which provides a means for the concrete Monitor subclass instances to get a reference to their MBeanServer.

The javax.management.monitor package defines three concrete monitor types: StringMonitor , CounterMonitor , and GaugeMonitor . Each of these monitor types extends Monitor , reusing the common behavior it defines, and defining a distinct MBean type by implementing its own management interface. We will treat each of these concrete monitor types in detail later in this chapter.

The MonitorNotification class extends the base JMX Notification class with additional monitor- related information.

6.1.2 The Monitor MBean

The Monitor MBean defines three read/write attributes, one read-only attribute, and two operations that are shared by all of the JMX monitor MBeans. Tables 6.1 and 6.2 describe these aspects of the Monitor MBean.

The GranularityPeriod attribute defaults to 10 seconds, 10,000 milliseconds . Attempting to set it to a value less than or equal to zero results in an IllegalArgumentException .

Both ObservedAttribute and ObservedObject default to null . The monitor does not attempt to validate either of these values until its start() method is invoked. If either value is invalid ”for example, null , meaning nonexistent MBean or attribute ”the monitor sends a MonitorNotification instance whose type indicates the nature of the error. We'll say more about MonitorNotification in a moment.

Table 6.1. Common Monitor Management Interface Attributes

Attribute	Type	Description
GranularityPeriod	Read/write	A long value that indicates the number of milliseconds between observations
ObservedAttribute	Read/write	The String name of the attribute that the monitor is observing
ObservedObject	Read/write	The object name of the MBean whose attribute is being observed
Active	Read-only	A boolean value indicating whether or not the monitor is active

Table 6.2. Common Monitor Management Interface Operations

Operation	Description
start	Tells the monitor to start observing the observed attribute on the observed object.
stop	Stops further observations.

Each JMX monitor also provides a derived gauge attribute. It doesn't show up in the MonitorMBean interface because its type is not the same in each of the monitors. The concept, however, is the same in each case. A monitor's derived gauge is the value that the monitor derives from the value of ObservedAttribute . The value may be either the exact value of ObservedAttribute or the difference between two successive ObservedAttribute values.

The start() and stop() operations are idempotent. That is, invoking start() on an active monitor has no effect, and the same is true for invocations of stop() on an inactive monitor.

6.1.3 MonitorNotification

Monitors are responsible for alerting the management applications that use them to specific conditions. In JMX the obvious mechanism to use for that purpose is a notification; that is, the monitor sends a JMX notification when the derived gauge for an observed attribute satisfies the condition. Rather than sending an instance of the standard JMX Notification class, the javax.management.monitor package provides the MonitorNotification class, which extends Notification . In addition to the information provided by Notification , MonitorNotification includes four other values:

1. The value of the derived gauge, which is returned by the getDerivedGauge() method

2. The name of the observed attribute, which is returned by the getObservedAttribute() method

3. The object name of the observed MBean, which is returned by the getObservedObject() method

4. The string that triggered the notification, by a StringMonitor instance, which is returned by getTrigger()

The monitoring services also define a set of notification types that are associated with the monitor notifications they send. Figure 6.2 shows the MonitorNotification type hierarchy.

Figure 6.2. The Hierarchy of MonitorNotification Types

The "error" types are common to all monitors, so we will describe them here (see Table 6.3). The other types will be covered in our discussions of the monitors that send them.

Table 6.3. Common Monitor Error Notification Types

MonitorNotification Type	Description
jmx.monitor.error.mbean	Sent when the observed MBean is not registered in the MBeanServer. The monitor's observed object name is included in the notification.
jmx.monitor.error.attribute	Sent when the observed attribute does not exist in the monitor's observed MBean. The observed object name and observed attribute are included in the notification.
jmx.monitor.error.type	Sent when the object instance of the attribute value is null or not the appropriate type for the given monitor. The observed object name and observed attribute are included in the notification.
jmx.monitor.error.runtime	Sent when an exception (save one associated with the conditions discussed above) is thrown while the value of the observed attribute is being accessed.
jmx.monitor.error.threshold	Sent if the monitor is misconfigured ”for example, the values of the CounterMonitor attributes Threshold , Offset , or Modulus (see Section 6.2.4) are not of the same type as the observed attribute, and low- or high-threshold values are not of the same type as the observed attribute.