JMX Remote Monitoring with Plugins

Available in HQ Open Source unless marked by * for HQ Enterprise only

JMX 1.2 provides a standard remote API to manage remote JMX-enabled applications. Prior to JMX 1.2/JSR-160 it was up to the server vendor to implement a remote MBeanServer connector. Several Open Source projects use the MX4J implementation, others such as WebSphere, WebLogic and JBoss rolled their own. Because of this HQ plugins had required connector code specific to each product and still do for those products which do not support JSR-160. With the adoption of JMX 1.2 in newer versions of products (ActiveMQ 4.0, Geronimo 1.0, WebLogic 9.1, Resin 3.0, etc) and the built-in support with J2SE 1.5, HQ is able to provide JMX plugin support classes without having to use a vendor specific connector.

This page explains everything at your disposal when crafting your own custom JMX plugin. Please also consult the JMX Plugin Tutorial to be guided through writing a relatively simple custom JMX measurement plugin.

How JMX plugins implement HQ features
Configuring JMX-enabled applications for remote connections
Finding the right MBeans
Getting started with JMX in HQ
Creating custom JMX plugins

If you have any comments or suggestions for this help page, please submit them at the bottom of the page by clicking Add Comment.

How JMX Plugins Implement HQ Features

JMX features map well to HQ features. For the most part, this implementation has been templatized so all you will need to do is invoke the appropriate bundled (HQ-provided) plugin (for example, the autoinventory the measurement plugins):

HQ Feature	How a JMX Plugin Implements It	Learn More
Server auto-discovery	SIGAR PTQL, File scanning	Auto-discovery
Service auto-discovery	`MBeanServer.queryMBeans()`	Auto-discovery
Monitoring	`MBeanServer.getAttribute()`, SIGAR	Gathering metrics
Control	`MBeanServer.invoke()`, `MBeanServer.setAttribute()`, scripts, SCM	Control
Event Management	`MBeanServer.handleNotification()`, log4j files	Log and config tracking

back to top

Configuring JMX-Enabled Applications for Remote Connections

In order to manage a JMX-enabled application from HQ it must be configured to accept remote connections. Many such applications have the remote connector enabled by default, those which do not often require changing a line or two of config. Here are some examples:

J2SE 1.5

MX4J

ActiveMQ

Mule

JOnAS

ServiceMix

Many more...

back to top

Finding the Right MBeans

There are several tools available for browsing MBeans in a remote application which can be useful for HQ plugin development:

JConsole

MC4J

The HQ JMX support classes also provide a command line tool to dump MBeans in text format:

java -Duser=system -Dpass=manager -Dplugins.include=jmx -jar pdk/lib/hq-product.jar \
jmx MBeanDumper service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi

Example output snippet:

...

MBean: org.apache.commons.modeler.BaseModelMBean
Name:  Catalina:type=StringCache
        0. Attribute: modelerType = org.apache.tomcat.util.buf.StringCache (rw)
        1. Attribute: trainThreshold = 20000 (rw)
        2. Attribute: byteEnabled = true (rw)
        3. Attribute: hitCount = 0 (r)
        4. Attribute: accessCount = 0 (r)
        5. Attribute: charEnabled = false (rw)
        6. Attribute: cacheSize = 200 (rw)
         Operation: void reset []

MBean: org.apache.commons.modeler.BaseModelMBean
Name:  Catalina:type=Cache,host=localhost,path=/jsp-examples
        0. Attribute: modelerType = org.apache.naming.resources.ResourceCache (rw)
        1. Attribute: accessCount = 20 (r)
        2. Attribute: cacheMaxSize = 10240 (rw)
        3. Attribute: hitsCount = 8 (r)
        4. Attribute: maxAllocateIterations = 20 (rw)
        5. Attribute: spareNotFoundEntries = 500 (rw)
        6. Attribute: cacheSize = 36 (r)
        7. Attribute: desiredEntryAccessRatio = 3 (rw)
         Operation: boolean unload [java.lang.String]
         Operation: void load [org.apache.naming.resources.CacheEntry]
         Operation: org.apache.naming.resources.CacheEntry lookup [java.lang.String]

...

Each of the attribute names given above (for example, modelerType or accessCount) can be used as the metric alias in the plugin when defining the metrics to be collected.

back to top

Getting Started with JMX in HQ

The following server types are implemented using HQ's JSR-160 based support classes:

Sun JVM 1.5

ActiveMQ 4.0

Geronimo 1.0

Resin 3.0

JOnAS 4.7

Other server types continue to use vendor specific connectors for backward compatibility. The Sun JVM 1.5 type applies to any of the above and any other JMX-enable server running under a Sun 1.5 JVM but has its own set of metrics and control actions. Unlike the other server types, Sun JVM 1.5 instances are not currently auto-discovered. All of the server types have the following configuration properties:

jmx.url - The JMX Service URL

jmx.username - Username if authentication is required

jmx.password - Password if authentication is required

For example:

<config>
<option name="jmx.url" description="JMX URL to MBeanServer" default="service:jmx:rmi:///jndi/rmi://localhost:6969/jmxrmi"/>
<option name="jmx.username" description="JMX username" optional="true" default=""/>
<option name="jmx.password" description="JMX password" optional="true" default="" type="secret"/>

Instead of specifying all three properties, you can use a shortcut:

<config include="jmx"/>

This includes login configuration properties from the JMX plugin.

back to top

Creating Custom JMX Plugins

A JMX plugin consists solely of an XML descriptor. That's about it. This section explains the major components that can be included in that descriptor.

JMX Plugin Components

Service Type
ObjectName
Configuration Properties
Metrics
Control
Auto-Discovery
Custom Properties
Log and Config Tracking

back to top

Defining Service Types to Provide Management via Custom MBeans

Each server type defines several service types such as EJBs, Connection Pools and JMS Queues. Custom plugins define additional service types to provide management via custom MBeans. The service tag is used to create new types like so:

<service name="String Cache"
         server="Sun JVM"
         version="1.5">
</service>

The server attribute must be that of Sun JVM and version attribute 1.5, or any of the other supported server+version combinations. The name attribute is the choice of the plugin implementor. These services will become part of the HQ inventory model, displayed along with the builtin server service types throughout the UI and shell. Service extensions will also inherit the server's configuration properties used to connect to the MBeanServer:

jmx.url

jmx.username

jmx.password

Defining an `ObjectName` to Access Custom MBeans

In order to access custom MBeans, the plugin must define its JMX ObjectName to be used with various MBeanServer interface methods. Only one ObjectName is defined per-service type using the property tag within the service tag:

<property name="OBJECT_NAME"
          value="Catalina:type=StringCache"/>

back to list of plugin components

Defining Configuration Properties to Be Displayed in the UI

All the configuration properties for a JMX plugin, as for all other plugins, are displayed in the "Resource Configuration" screen for the resource. The default values for each of these options can be specified in the plugin, but users can change the values on that screen.

In the example above, the OBJECT_NAME is hard-coded since there is only one instance of the String Cache. Configuration Properties are used to support multiple instances that follow the same ObjectName pattern. For example, the WebApp Cache plugin uses an ObjectName with the following pattern:

<property name="OBJECT_NAME"
          value="Catalina:type=Cache,host=*,path=*"/>

Where the ObjectName Domain is always Catalina and type attribute value is always Cache, but the host and path attributes will be different for each instance of the MBean. The WebApp Cache plugin defines config options for each of the instance properties:

<config>
  <option name="host"
          description="Host name"
          default="localhost"/>
  
  <option name="path"
          description="Path"
          default="/jsp-examples"/>
</config>

The values of the instance attributes within the OBJECT_NAME is replaced with the value of the configuration property when used by the plugin, for example:

"Catalina:type=Cache,host=localhost,path=/jsp-examples"

back to list of plugin components

Defining and Gathering Metrics

Metrics are defined just as they are with other plugins, but in the case of custom MBean services the OBJECT_NAME property is used to compose the metric template attribute:

<metric name="Access Count"
        template="${OBJECT_NAME}:accessCount"
        category="THROUGHPUT"
        indicator="true"
        collectionType="trendsup"/>

This results in the template being expanded, for example, to:

template="Catalina:type=Cache,host=localhost,path=/jsp-examples:accessCount"

Where accessCount is an attribute of the MBean and can be collected internally using the MBeanServer interface like so:

ObjectName name = new ObjectName("Catalina:type=Cache,host=localhost,path=/jsp-examples");

return MBeanServer.getAttribute(name, "accessCount");

The MBean interface attributes collected by tomcat-webapp-cache-plugin.xml as metrics are as follows:

public interface WebAppCacheMBean {

    public int getAccessCount();
    
    public int getHitCount();
    
    public int getCacheSize();

}

Learn more about measurement plugins.

back to list of plugin components

Implementing Control Actions

With the OBJECT_NAME property defined, MBean operations can be exposed as HQ control actions simply by adding the list of method names:

<actions include="reset"/>

The plugin must also define the control implementation class (resides in hq-jmx.jar):

<plugin type="control"
        class="org.hyperic.hq.product.jmx.MxControlPlugin"/>

The control actions will then be invoked as MBean operations by the plugin like so:

ObjectName name = new ObjectName("Catalina:type=StringCache");

return MbeanServer.invoke(name, "reset", new Object[0], new String[0]);

Which maps to the following MBean operation:

public interface StringCacheMBean {

    public void reset();

}

If an MBean operation requires arguments, they can be passed in using the HQ control UI.
The WebApp Cache example provides the following control actions:

<actions include="unload,lookup,allocate"/>

Which map to the following MBean operations:

public interface WebAppCacheMBean {

    public boolean unload(String name);

    public CacheEntry lookup(String name);
    
    public boolean allocate(int value);

}

Learn more about control plugins.

back to list of plugin components

Implementing Auto-Discovery

Auto-discovery (called "auto inventory" within plugins) is easily implemented by taking advantage of an HQ-provided autoinventory plugin.

To implement auto-discovery at the server level, you must invoke an autoinventory plugin with a specific class — MxServerDetector — within the server tag:

<server name="Java Server Name" version ="version #">
...
<plugin type="autoinventory" class="org.hyperic.hq.product.jmx.MxServerDetector"/>
...
</server>

In the case of service, auto-discovery is supported for custom MBean services, again driven by the OBJECT_NAME property. To implement auto-discovery at the service level, invoke the autoinventory plugin, leaving out the class attribute, within a service tag:

<service name="Java Service Name">
...
<plugin type="autoinventory"/>
...
</service>

The JMX plugin uses the MBeanServer.queryNames method to discover a service for each MBean instance. In the case where the OBJECT_NAME contains configuration properties, the properties will be auto-configured.

By default, auto-discovered service names will be composed using the hosting-server name, configuration properties, and service type name. For example:

"myhost Sun JVM 1.5 localhost /jsp-examples WebApp String Cache"

The naming can be overridden using the AUTOINVENTORY_NAME property:

<property name="AUTOINVENTORY_NAME"
             value="%platform.name% %path% Tomcat WebApp String Cache"/>

Configuration properties from the platform, hosting server, and the service itself can be used in the %replacement% strings, resulting in a name like so:

"myhost /jsp-examples Tomcat WebApp String Cache"

Learn more about auto-inventory plugins.

back to list of plugin components

Discovering Custom Properties

Discovery of Custom Properties is supported, again using the OBJECT_NAME and MBeanServer.getAttribute. Simply define a properties tag with any number of property tags where the name attribute value is that of an MBean attribute:

<properties>
  <property name="cacheMaxSize"
            description="Maximum Cache Size"/>
</properties>

Which maps to the following MBean interface method:

public interface WebAppCacheMBean {

    public int getCacheMaxSize();

}

back to list of plugin components

Implementing Log and Config Tracking

All log and config tracking data is displayed in the HQ UI on the "Current Health" screen.

Should your plugin wish to track log and/or config files, simply use the generic classes which are included in pdk/lib/hq-product.jar and available for use by all plugins. As you can see in the following code, these classes require that files be in Log4J format (which most will be).

<property name="DEFAULT_LOG_FILE"
          value="log/mybean.log"/>

<plugin type="log_track"
        class="org.hyperic.hq.product.Log4JLogTrackPlugin"/>

<property name="DEFAULT_CONFIG_FILE"
          value="conf/mybean-service.xml,conf/mybean.policy"/>

<plugin type="config_track"
        class="org.hyperic.hq.product.ConfigFileTrackPlugin"/>

Tracking an MBeanLog

You can also easily implement log tracking for a specific MBean. Invoke the log_track plugin with the class MxNotificationPlugin before declaring the metric for the desired MBean (in this example, Threading MBeans, which we'll just pretend were enumerated earlier).

<plugin type="log_track" class="org.hyperic.hq.product.jmx.MxNotificationPlugin"/>

<property name="OBJECT_NAME" value="java.lang:type=Threading"/>
<metrics include="Threading"/>

Example Custom MBean Plugins

tomcat-string-cache-plugin.xml - Management via the Tomcat String Cache MBean (Download)

tomcat-webapp-cache-plugin.xml - Management via the Tomcat WebApp Cache MBean (Download)

JMX Plugin

JMX Remote Monitoring with Plugins

How JMX Plugins Implement HQ Features

Configuring JMX-Enabled Applications for Remote Connections

Finding the Right MBeans

Getting Started with JMX in HQ

Creating Custom JMX Plugins

Defining Service Types to Provide Management via Custom MBeans

Defining an `ObjectName` to Access Custom MBeans

Defining Configuration Properties to Be Displayed in the UI

Defining and Gathering Metrics

Implementing Control Actions

Implementing Auto-Discovery

Discovering Custom Properties

Implementing Log and Config Tracking

Example Custom MBean Plugins

Browse Space

Explore Confluence

Your Account

Other Features

Add Content

JMX Plugin

JMX Remote Monitoring with Plugins

How JMX Plugins Implement HQ Features

Configuring JMX-Enabled Applications for Remote Connections

Finding the Right MBeans

Getting Started with JMX in HQ

Creating Custom JMX Plugins

Defining Service Types to Provide Management via Custom MBeans

Defining an ObjectName to Access Custom MBeans

Defining Configuration Properties to Be Displayed in the UI

Defining and Gathering Metrics

Implementing Control Actions

Implementing Auto-Discovery

Discovering Custom Properties

Implementing Log and Config Tracking

Example Custom MBean Plugins

Browse Space

Explore Confluence

Your Account

Other Features

Add Content

Defining an `ObjectName` to Access Custom MBeans