46/68

# 34 How to Manage Coherence Using JMX

Coherence includes facilities for managing and monitoring Coherence resources by using 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. Those that are new to JMX, should refer to following article:

`http://java.sun.com/developer/technicalArticles/J2SE/jmx.html`

For details on the various MBean types registered by Coherence clustered services, see the `com.tangosol.net.management.Registry` interface in Oracle Coherence Java API Reference or see Appendix E, "Coherence MBeans Reference."

Note:

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

The following sections are included in this chapter:

- Configuring the Coherence Management Framework

- Accessing Coherence MBeans

- Using Coherence MBeanConnector to Access MBeans

## Configuring the Coherence Management Framework

In general, the Coherence management framework is configured within the `<management-config>` element in a Coherence operational override file (`tangosol-coherence-override.xml`). For detailed information on each of the elements that can be configured for the Coherence management framework, see "management-config":

The following topics are included in this section:

- Enabling JMX Management

- Filtering MBeans

- Configuring Management Refresh

### Enabling JMX Management

JMX management is enabled by configuring one or more nodes to host an MBean server which manages the managed objects of all the other cluster nodes. The use of dedicated JMX cluster members is a common pattern because it avoids loading JMX software into every single cluster member while still providing fault-tolerance should a single JMX member fail.

JMX management in the cluster is disabled by default. To enable JMX management, add a `<managed-nodes>` element within the `<management-config>` element in an operational override file. The `<managed-nodes>` element specifies whether a cluster node's JVM has an in-process MBean server and if so, whether the node allows management of other nodes' managed objects. The following example enables an MBean server on the current cluster node and is used to manage both local and remote managed objects:

    <coherence>
       <management-config>
          <managed-nodes>all</managed-nodes>
       </management-config>
    </coherence>

The `<managed-nodes>` element supports the following values:

- `none`—No MBean server is instantiated.

- `local-only`—Manage only MBeans which are local to the cluster node (that is, within the same JVM).

- `remote-only`—Manage MBeans on other remotely manageable cluster nodes. See <`allowed-remote-management`> subelement. This option requires Coherence Enterprise Edition or higher.

- `all`—Manage both local and remotely manageable cluster nodes. This option requires Coherence Enterprise Edition or higher.

By default, all nodes in the cluster will allow a remote MBean server to manage its MBeans. To restrict remote management of a node's MBeans, the `<allow-remote-management>` element must be set to `false`. The following example restricts a node from having its MBeans managed by a remote MBean server.

    <coherence>
       <management-config>
          <allow-remote-management>false</allow-remote-management>
       </management-config>
    </coherence>

Values for the `<managed-nodes>` and `<allow-remote-management>` elements can also be set using Java system properties:

    -Dtangosol.coherence.management=all
    -Dtangosol.coherence.management.remote=true

### Filtering MBeans

The Coherence management framework provides the ability to filter MBeans before they are registered in the MBean server. An out-of-the box MBean filter is provided and custom filters can be created as required. The included MBean filter (`com.tagosol.net.management.ObjectNameExcludeFilter`) is used to exclude MBeans from being registered based on their JMX object name using standard regex patterns. As configured out-of-the box, the filter excludes some platform MBeans from being registered in the management framework. MBean filters are defined using the `<mbean-filter>` element within the `<management-config>` element in an operational override file.

The following example shows the out-of-the box configuration:

    <mbean-filter>
       <class-name>com.tangosol.net.management.ObjectNameExcludeFilter</class-name>
       <init-params>
          <init-param>
             <param-type>string</param-type>
             <param-value>
                  .*type=Service,name=Management,.*
                  .*type=Platform,Domain=java.lang,subType=ClassLoading,.*
                  .*type=Platform,Domain=java.lang,subType=Compilation,.*
                  .*type=Platform,Domain=java.lang,subType=MemoryManager,.*
                  .*type=Platform,Domain=java.lang,subType=Threading,.*
             </param-value>
          </init-param>
       </init-params>
    </mbean-filter>

To enable the management service or platform MBeans, remove the corresponding object name from the list of names in the `<param-value>` element. To exclude an MBean from being registered, add the MBean object name to the list. The exclusion list may also be entered using the `tangosol.coherence.management.exclude` Java system property.

### Configuring Management Refresh

The Coherence management framework provides the `<refresh-expiry>`, `<refresh-policy>`, and `<refresh-timeout>` elements to control the latency of management information. The elements are defined within the `<management-config>` element and should be set together.

#### Setting the Management Refresh Expiry

The `<refresh-expiry>` element specifies the minimum time interval between the remote retrieval of management information from remote nodes. The value of this element must be in the following format:

    [\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

The first non-digits (from left to right) indicate the unit of time duration:

- MS or ms (milliseconds)

- S or s (seconds)

- M or m (minutes)

- H or h (hours)

- D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is `1s`. The refresh policy can also be set using the `tangosol.coherence.management.refresh.expiry` Java system property.

#### Setting the Management Refresh Policy

The `<refresh-policy>` element is used to specify the method which is used to refresh remote management information. Each policy uses a different refresh algorithm that can improve latency based on MBean usage patterns. Table 34-1 describes each policy.

Table 34-1 Refresh Policies

Setting | Description
--- | ---
`refresh-ahead` (default) | MBeans are refreshed before they are requested based on prior usage patterns after the expiry delay has passed. This setting can reduce latency of the management information with a minor increase in network consumption. This setting is best when MBeans are accessed in a repetitive/programmatic pattern.
`refresh-behind` | Each MBean will be refreshed after the data is accessed. This method ensures optimal response time. However, the information returned will be offset by the last refresh time.
`refresh-expired` | Each MBean will be refreshed from the remote node when it is accessed and the expiry delay has passed from the last refresh. This setting is best used when MBeans are accessed in a random pattern.

The refresh policy can also be set using the `tangosol.coherence.management.refresh.policy` Java system property.

#### Setting the Management Refresh Timeout

The `<refresh-time>` element is used to specify the duration which the management node waits for a response from a remote node when refreshing MBean information. This value must be less than the `<refresh-expiry>` value. The value of this element must be in the following format:

    [\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?

The first non-digits (from left to right) indicate the unit of time duration:

- MS or ms (milliseconds)

- S or s (seconds)

- M or m (minutes)

- H or h (hours)

- D or d (days)

If the value does not contain a unit, a unit of milliseconds is assumed. The default value is `250ms`. The refresh policy can also be set using the `tangosol.coherence.management.refresh.timeout` Java system property.

## Accessing Coherence MBeans

JMX management must be enabled on at least one Coherence node before accessing Coherence MBeans. See "Configuring the Coherence Management Framework".

There are two options for viewing and manipulating Coherence MBeans: the JConsole utility and the HTML Adapter Web Application.

### Viewing MBeans Using the JConsole Utility

The JConsole utility (located in the the JDK `/bin` directory) can be used to view and manipulate Coherence MBeans. To do so, set the following system properties when starting a Coherence node:

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

When the node has started, launch the JConsole utility and open a new connection to the JVM process running the Coherence command line application:

Figure 34-1 JConsole Utility to Access Coherence MBeans

### Viewing MBeans Using the HTML Adapter Application

The HTML Adapter Web Application uses the HTTP adapter (`HtmlAdaptorServer`) that is shipped as part of the JMX reference implementation (`jmxtools.jar`). To run the Web application, start a Coherence node as follows:

On Windows:

    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

After the Coherence command line application starts, enter `jmx` `8082`. This starts an HTTP adaptor on `http://localhost:8082` in the cluster node's JVM and makes the cluster node an `MBeanServer` host:

Figure 34-2 Viewing the HttpAdapter Web Application in a Browser

## Using Coherence MBeanConnector to Access MBeans

Coherence ships with a program to launch a cluster node as a dedicated MBean server host. This program provides access to Coherence MBeans by using the JMX Remote API using RMI or the HTTP server provided by Sun's JMX RI. The RMI and HTTP ports can be configured, allowing for access through a firewall. The server is started using the following command (note that it is broken up into multiple lines here only for formatting purposes; this is a single command entered on one line):

    java -Dtangosol.coherence.management=all
         -Dcom.sun.management.jmxremote.ssl=false
         -Dcom.sun.management.jmxremote.authenticate=false
         -cp coherence.jar;jmxri.jar;jmxtools.jar
         com.tangosol.net.management.MBeanConnector [-http -rmi]

To allow access by using JMX RMI, include the `-rmi` flag. To allow access by using HTTP and a Web browser, include the `-http` flag. Both flags may be included; however at least one must be present for the node to start.

Table 34-2 describes optional properties that can be used for JMX RMI configuration:

Table 34-2 Optional Properties that can be used for JMX RMI Configuration

Property | Description
--- | ---
tangosol.coherence.management.remote.host | The host that the JMX server will bind to. Default is `localhost`. (NOTE: on Redhat Linux this may have to be changed to the host name or IP address)
tangosol.coherence.management.remote.registryport | The port used for the JMX RMI registry. Default is `9000`.
tangosol.coherence.management.remote.connectionport | The port used for the JMX RMI connection. Default is `3000`.

Table 34-3 describes optional properties that can be used for HTTP configuration.

Table 34-3 Optional Properties that can be used for Http Configuration

Property | Description
--- | ---
tangosol.coherence.management.remote.httpport | The port used for the HTTP connection. Default is `8888`.

To connect by using JConsole with default settings, use the following command:

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

To connect by using HTTP with default settings, use the following URL:

    http://localhost:8888

Note:

Refer to the JMX Agent documentation below to setup secure access using authentication and SSL:

Java 1.5:

`http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html`

Java 1.6:

`http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html`