Skip Headers
Oracle® Coherence Developer's Guide
Release 3.6.1

Part Number E15723-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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

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

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

shows MBeans in JConsole application

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

shows MBeans in HTML Adapter application

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