JMX Plugin

JMX Remote Monitoring

Introduction

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.

Integration Points

JMX features map quite well to HQ features, this document will discuss the following integration points:

HQ Feature	Integration Points
Server Auto-Inventory	SIGAR PTQL, File scanning
Service Auto-Inventory	MBeanServer.queryMBeans()
Monitoring	MBeanServer.getAttribute(), SIGAR
Control	MBeanServer.invoke(), MBeanServer.setAttribute(), scripts, SCM
Event Management	MBeanServer.handleNotification(), log4j files

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...

Tools

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]

...

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

Custom MBean Plugins

Plugin Components

Service Type

ObjectName

Configuration Properties

Metrics

Control

Auto Inventory

Custom Properties

Log/Config Tracking

Service Type

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

ObjectName

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"/>

Configuration Properties

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>

As with other plugins, these config options will be displayed in the Inventory tab of the service resource in the UI.

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"

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();

}

Control

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);

}

Auto Inventory

Auto Inventory is supported for custom MBean services, again driven by the OBJECT_NAME property. Not enabled by default, to enable use the following within the service tag:

<plugin type="autoinventory"/>

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 parent 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, parent 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"

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();

}

Log/Config Tracking

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:

<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"/>

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)