Managing Coherence using JMX

Overview

Coherence includes facilities for managing and monitoring Coherence resources via the Java Management Extensions (JMX) API. JMX is a Java standard for managing and monitoring Java applications and services. It defines a management architecture, design patterns, APIs, and services for building general solutions to manage Java-enabled resources. This section assumes familiarity with JMX terminology. If you are new to JMX a good place to start is with this article.

To manage Coherence using JMX:

• Add JMX libraries to the Coherence classpath (if necessary)
• Configure the Coherence Management Framework
• View and manipulate Coherence MBeans using a JMX client of your choice

JMX support Coherence Application Edition and higher support clustered JMX, allowing access to JMX statistics for the entire cluster from any member. Coherence Caching Edition provides only local JMX information.

Adding JMX libraries to the Coherence classpath

If you would like to manage a Coherence cluster using JMX you will need to ensure that you have the necessary JMX 1.0 or later classes (javax.management.*) in the classpath of at least one Coherence cluster node, known as an MBeanServer host. The cluster nodes that are not MBeanServer hosts will be managed by the MBeanServer host(s) via the Coherence Invocation service.

All compliant J2SE 5.0 JREs and J2EE application servers supply a JMX 1.0 or later implementation; therefore, if the MBeanServer host node is running within a J2SE 5.0 JVM or J2EE application server, no additional actions are necessary. However, for standalone applications running within a pre-J2SE 5.0 JVM, you can download the necessary JMX libraries here and add them to the classpath.

Configuring the Coherence Management Framework

In the majority of cases, enabling JMX management can be done by simply setting a Java system property on all Coherence cluster nodes that are acting as MBeanServer hosts:

-Dtangosol.coherence.management=all

and the following Java system property on all cluster nodes:

-Dtangosol.coherence.management.remote=true

Note that the use of dedicated JMX cluster members is a common pattern. This approach avoids loading JMX software into every single cluster member, while still providing fault-tolerance should a single JMX member run into issues.

In general, the Coherence Management Framework is configured by the management-configuration operational configuration element in the Coherence Operational Configuration deployment descriptor (tangosol-coherence.xml). The following sub-elements control the behavior of the Management Framework:

• domain-name
  Specifies the name of the JMX domain used to register MBeans exposed by the Coherence Management Framework.
• managed-nodes
  Specifies whether or not a cluster node's JVM has an in-process MBeanServer and if so, whether or not the node allows management of other nodes' managed objects. Valid values are none, local-only, remote-only and all. For example, if a node has an in-process MBeanServer and you'd like this node to manage other nodes' MBeans, set this attribute to all.
• allow-remote-management
  Specifies whether or not this cluster node will register its MBeans in a remote MBeanServer(s).
• read-only
  Specifies whether or not the MBeans exposed by this cluster node allow operations that modify run-time attributes.

For additional information on each of these attributes, please see the Operational Configuration Elements.

Accessing Coherence MBeans

Once you have configured the Coherence Management Framework and launched one or more Coherence cluster nodes (at least one being an MBeanServer host) you will be able to view and manipulate the Coherence MBeans registered by all cluster nodes using standard JMX API calls. See the JavaDoc for the Registry class for details on the various MBean types registered by Coherence clustered services.

Coherence ships with two examples that demonstrate accessing Coherence MBeans via JMX. The first uses the HttpAdapter that is shipped as part of the JMX reference implementation (jmxtools.jar). To run the example on a pre-J2SE 5.0 JVM, start the Coherence command line application using the following command on Windows (note that it is broken up into multiple lines here only for formatting purposes; this is a single command typed on one line):

java -cp jmxri.jar;jmxtools.jar;coherence.jar 
     -Dtangosol.coherence.management=all
     -Dtangosol.coherence.management.remote=true 
      com.tangosol.net.CacheFactory

On Unix:

java -cp jmxri.jar:jmxtools.jar:coherence.jar
     -Dtangosol.coherence.management=all
     -Dtangosol.coherence.management.remote=true 
      com.tangosol.net.CacheFactory

Once the Coherence command line application has started, type "jmx 8082" and hit enter. This starts the HttpAdapter on http://localhost:8082 in the cluster node's JVM and makes the cluster node an MBeanServer host. You can now use the HttpAdapter web application to view and manipulate Coherence MBeans registered by all cluster nodes:

Alternatively, you can run this example with the Sun J2SE 5.0 JVM and use the JConsole utility included with the Sun J2SE 5.0 JDK to view and manipulate Coherence MBeans. To do so, start the Coherence command line application using the following command (note that it is broken up into multiple lines here only for formatting purposes; this is a single command typed on one line):

java -Dcom.sun.management.jmxremote
     -Dtangosol.coherence.management=all
     -Dtangosol.coherence.management.remote=true 
     -jar coherence.jar

Once the Coherence command line application has started, launch the JConsole utility (located in the bin directory of the Sun J2SE 5.0 JDK distribution) and open a new connection to the JVM running the Coherence command line application:

Remote JMX connections require two ports, one for the RMIServer and one for the RMIConnection. The RMIServer port can be configured via system property com.sun.management.jmxremote.port but this will assign a random port for the RMIConnection, making it unsuitable for use through a firewall. According to this Sun FAQ the way to get around this issue is to programmatically create the RMI Connector Server. Here is a code sample to do just that:

    /**
     * Starts the JMX server.  Use the following to connect via JConsole:
     *
     * jconsole service:jmx:rmi://[host]:[RMI Connection port]/jndi/rmi://[host]:[RMI Registry port]/server
     *
     * @throws IOException
     *
     * @see #RMI_REGISTRY_PORT
     * @see #RMI_CONNECTION_PORT
     */
    public static void startJmxServer()
            throws IOException
        {
        MBeanServer mbs = getMBeanServer();

        LocateRegistry.createRegistry(RMI_REGISTRY_PORT);

        JMXServiceURL url = new JMXServiceURL(
                "service:jmx:rmi://localhost:"+RMI_CONNECTION_PORT+
                        "/jndi/rmi://localhost:"+RMI_REGISTRY_PORT+"/server");
        JMXConnectorServer cs =
                JMXConnectorServerFactory.newJMXConnectorServer(url, null, mbs);

        cs.start();
        }

    // Both of these ports will have to be opened through the firewall

    private static final int RMI_REGISTRY_PORT = 9999;
    private static final int RMI_CONNECTION_PORT = 3000;

What is required now is the call to get the MBeanServer that has the Coherence MBeans:

    /**
     * @return MBeanServer used to manage Coherence
     * @param defaultDomainName default-domain-name as defined
     *         in tangosol-coherence.xml.
     *
     * @see #DEFAULT_DOMAIN_NAME
     */
    private static MBeanServer getMBeanServer()
        {
        MBeanServer server = null;
        for (Iterator iter =
                MBeanServerFactory.findMBeanServer(null).iterator();
             iter.hasNext();)
            {
            server = (MBeanServer) iter.next();

            if (DEFAULT_DOMAIN_NAME.length() == 0 ||
                    server.getDefaultDomain().equals(DEFAULT_DOMAIN_NAME))
                {
                break;
                }
            server = null;
            }
        if (server == null)
            {
            server = MBeanServerFactory.createMBeanServer(DEFAULT_DOMAIN_NAME);
            }

        return server;
        }


    /**
     * The default-domain-name as defined in tangosol-coherence.xml.
     * By default this value is blank.
     */
    private static final String DEFAULT_DOMAIN_NAME = "";

Be sure to set the following system properties in the Coherence application:

-Dtangosol.coherence.management=all
-Dtangosol.coherence.management.remote=true
-Dcom.sun.management.jmxremote

Once the application is up, access the JMX server with JConsole:

jconsole service:jmx:rmi://localhost:3000/jndi/rmi://localhost:9999/server

The second example is a JSP page (JmxCacheExplorer.jsp) that displays basic information on each running Coherence cache using JMX API calls. You can find this example in the examples/jsp/explore directory under the root of your Coherence installation.

Additional JMX examples may be found on the Oracle Coherence Forums.

Example-JMX-JConsole.GIF (image/gif)
Example-JMX-HttpAdapter.GIF (image/gif)