34 How to Manage Coherence Using JMX

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.

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

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

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