Skip Headers
Oracle® Coherence Management Guide
Release 3.7.1

Part Number E22842-01
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

2 Using JMX to Manage Coherence

This chapter provides instructions for enabling and configuring JMX management within a cluster and describes how to access Coherence MBeans.

The following sections are included in this chapter:

2.1 Configuring JMX Management

JMX management is configured within the <management-config> element in a tangosol-coherence-override.xml file or by setting management system properties at startup. See Oracle Coherence Developer's Guide for detailed information on each of the elements that can be used within the <management-config> element.

The following topics are included in this section:

2.1.1 Enabling Remote JMX Management on a Cluster Member

Remote JMX management allows one or more cluster members to each host an MBean server that is responsible for the managed objects of all cluster members. Accessing the MBean servers on these cluster members shows management information for all cluster members. 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.

To enable remote JMX management on a cluster member, set the <managed-nodes> element to all or remote-only. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <managed-nodes system-property="tangosol.coherence.management">all
      </managed-nodes>
   </management-config>
</coherence>

The remote-only setting starts an MBean server that only manages remote MBeans. The all setting starts an MBean server that manges remote MBeans and local (within the same JVM) MBeans.

The tangosol.coherence.management system property is used to enable remote JMX management instead of using the operational override file. For example:

-Dtangosol.coherence.management=all

2.1.2 Enabling Local JMX Management on a Cluster Member

Local JMX management constrains an MBean server to only manage the MBeans that are local (within the same JVM) to the cluster member. Accessing the MBean server on the cluster member only shows local management information. However, the member's MBeans can still be managed by a member that has been enabled for remote JMX management. Local JMX Management is typically used for extend clients or transient cluster clients.

To enable local JMX management on a cluster member, set the <managed-nodes> element to local-only. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <managed-nodes system-property="tangosol.coherence.management">local-only
      </managed-nodes>
   </management-config>
</coherence>

The tangosol.coherence.management system property is used to enable local JMX management instead of using the operational override file. For example:

-Dtangosol.coherence.management=local-only

2.1.3 Enabling JMX Management When Using the Startup Scripts

As a convenience, the COHERENCE_HOME/bin/cache-server and COHERENCE_HOME/bin/coherence startup scripts include a -jmx argument that enables JMX management on a cluster member and also enables access to the MBean server. For example:

cache-server -jmx

The argument automatically sets the following system properties, which can be changed as required within the script. The properties are, by default, set to enable remote JMX management on the member and also allow the member to be managed remotely.

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

The com.sun.management.jmxremote system property is required to allow remote access to an MBean server.

2.1.4 Stopping a Cluster Member from being Managed Remotely

By default, all cluster members allow their MBeans to be managed by a remote MBean server. To restrict remote management of a member's MBeans, the <allow-remote-management> element must be set to false. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <allow-remote-management
         system-property="tangosol.coherence.management.remote">false
      </allow-remote-management>
   </management-config>
</coherence>

The tangosol.coherence.management.remote system property is used to disable remote management instead of using the operational override file. For example:

-Dtangosol.coherence.management.remote=false

2.1.5 Disabling JMX Management

To disable JMX management on a cluster member, set the <managed-nodes> element to none. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <managed-nodes system-property="tangosol.coherence.management">none
      </managed-nodes>
   </management-config>
</coherence>

Disabling JMX management on a member does not stop the member from being remotely managed. The following example disables JMX Management and stops the member from being remotely managed:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <managed-nodes system-property="tangosol.coherence.management">none
      </managed-nodes>
      <allow-remote-management
         system-property="tangosol.coherence.management.remote">false
      </allow-remote-management>
   </management-config>
</coherence>

2.1.6 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-box, the filter excludes some platform MBeans from being registered in the management framework. MBean filters are defined using the <mbean-filter> element.

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 system-property="tangosol.coherence.management.exclude">
              .*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 names 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 tangosol.coherence.management.exclude system property is used to filter MBeans instead of using the operational override file. For example:

-Dtangosol.coherence.management.exclude=.*type=Service,name=Management,.*

2.1.7 Configuring Management Refresh

The <refresh-expiry>, <refresh-policy>, and <refresh-timeout> elements control the latency of management information. For example:

<?xml version='1.0'?>

<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/
   coherence-operational-config coherence-operational-config.xsd">
   <management-config>
      <refresh-policy
         system-property="tangosol.coherence.management.refresh.policy">
         refresh-ahead</refresh-policy>
      <refresh-expiry
         system-property="tangosol.coherence.management.refresh.expiry">1s
      </refresh-expiry>
      <refresh-timeout
         system-property="tangosol.coherence.management.refresh.timeout">250ms
      </refresh-timeout>
   </management-config>
</coherence>

2.1.7.1 Setting the Management Refresh Expiry

The <refresh-expiry> element specifies the minimum time interval between the remote retrieval of management information from remote members. 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 tangosol.coherence.management.refresh.expiry system property is used to set the expiry instead of using the operational override file. For example:

-Dtangosol.coherence.management.refresh.expiry=2s

2.1.7.2 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 2-1 describes each policy.

Table 2-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 is refreshed after the data is accessed. This method ensures optimal response time. However, the information returned is offset by the last refresh time.

refresh-expired

Each MBean is refreshed from the remote member 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 tangosol.coherence.management.refresh.policy system property is used to set the policy instead of using the operational override file. For example:

-Dtangosol.coherence.management.refresh.policy=refresh-expired

2.1.7.3 Setting the Management Refresh Timeout

The <refresh-time> element is used to specify the duration which the management member waits for a response from a remote member 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 tangosol.coherence.management.refresh.timeout system property is used to set the timeout instead of using the operational override file. For example:

-Dtangosol.coherence.management.refresh.timeout=500ms

2.2 Accessing Coherence MBeans

JMX management must be enabled on a cluster member before accessing Coherence MBeans. See "Configuring JMX Management". The procedures in this section use the Coherence startup scripts and the -jmx argument to enable JMX management.

The following topics are included in this section:

2.2.1 Accessing MBeans Using Java VisualVM

Java Visual VM is a management utility included with the JDK (JDK_HOME\bin\jvisualvm) and is used to view and interact with Coherence MBeans.

To acceess Coherence MBeans using the Java VisualVM utility:

  1. Start a cache server using the COHERENCE_HOME\bin\cache-server script and specify the -jmx argument to enable management on the member. For example:

    COHERENCE_HOME\bin\cache-server -jmx
    
  2. Start JDK_HOME\bin\jvisualvm. The Java VisualVM window displays.

  3. From the Applications tree, click to expand Local if it is not already expanded and double-click the cluster member's process. The process information is displayed in a process tab on the right side of the window.

  4. From the selected process tab, click the MBeans tab and expand the Coherence node to access the Coherence MBeans.

    Java VisualVM Window

2.2.2 Accessing MBeans Using the JConsole Utility

JConsole is a management utility that is included with the JDK (JDK_HOME\bin\jconsole) and is used to view and interact with Coherence MBeans.

To access Coherence MBeans using the JConsole utility:

  1. Start a cache server using the COHERENCE_HOME\bin\cache-server script and specify the -jmx argument to enable management on the member. For example:

    COHERENCE_HOME\bin\cache-server -jmx
    
  2. Start JDK_HOME\bin\jconsole. The Java Monitoring & Management Console window displays and the JConsole: New Connection dialog box displays.

  3. From the JConsole: New Connection dialog box, click Local Process: and select the cluster member's process. For example:

    view of the New connection window
  4. Click Connect.

  5. From the Java Monitoring & Management Console window, select the MBeans tab and expand the Coherence node to access the Coherence MBeans.

    shows MBeans In JConsole application

2.2.3 Accessing 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. The adapter requires both the jmxri.jar and jmxtools.jar libraries to be in the classpath. The JMX reference implementation can be downloaded from the following page:

http://www.oracle.com/technetwork/java/javase/tech/download-jsp-141676.html

To access Coherence MBeans using the HTML adapter:

  1. Edit the COHERENCE_HOME\bin\coherence script to include the jmxri.jar and jmxtools.jar in the classpath. For example, on Windows:

    -cp "jmxri-1.2.1.jar;jmxtools-1.2.1.jar;%coherence_home%\lib\coherence.jar"
    
  2. Start a cache factory instance using the script and specify the -jmx argument to enable management on the member. For example:

    COHERENCE_HOME\bin\coherence -jmx
    
  3. After the cache factory instance starts, enter jmx 8082 at the command prompt. This starts an HTTP adapter at port 8082 on the cluster member:

  4. Using a Web browser, access the adapter using the host name and port 8082 for the address.

    shows MBeans in HTML Adapter application

2.2.4 Setting Up the Coherence MBeanConnector

Coherence ships with a program to launch a cluster member 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 member to start.

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

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

Property Description

tangosol.coherence.management.remote.host

The host that the JMX server binds 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 2-3 describes optional properties that can be used for HTTP configuration.

Table 2-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:

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