2 Using JMX to Manage Oracle Coherence

This chapter provides instructions for enabling and configuring JMX management on cluster members and describes how to access Oracle Coherence MBeans using tools such as Java VisualVM and JConsole.

This chapter includes the following sections:

Configuring JMX Management
Accessing Oracle Coherence MBeans

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 Developing Applications with Oracle Coherence for further description of the <management-config> element.

This section includes the following topics:

Enabling Remote JMX Management on a Cluster Member
Enabling Local JMX Management on a Cluster Member
Enabling JMX Management When Using the Startup Scripts
Stopping a Cluster Member from Being Managed Remotely
Disabling JMX Management
Filtering MBeans
Configuring Management Refresh
Using an Existing MBean Server

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 practice because it avoids loading JMX software into every single cluster member while still providing fault tolerance if a single JMX member fails.

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 manages only remote MBeans. The all setting starts an MBean server that manages remote MBeans and local (within the same JVM) MBeans.

The tangosol.coherence.management system property also enables remote JMX management. 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 manage only the MBeans that are local (within the same JVM) to the cluster member. Accessing the MBean server on the cluster member shows only local management information. However, the member's MBeans can still be managed by a cluster 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 also enables local JMX management. 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. For example:

cache-server -jmx

The argument automatically sets the management system properties, which can be changed as required within the script. The default settings are the following:

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

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, set the <allow-remote-management> element 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 also disables remote management. 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. You must also set the <allow-remote-management> to false. 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 Oracle 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) excludes 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.

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 also filters MBeans. 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. The following example configures each of these settings, which are described in detail after the 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">300ms
      </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)

A unit of milliseconds is assumed if the value does not contain a unit. The default value is 1s.

The tangosol.coherence.management.refresh.expiry system property also sets the expiry. For example:

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

2.1.7.2 Setting the Management Refresh Policy

The <refresh-policy> element specifies how to refresh remote management information. Each policy uses a different refresh algorithm that improves latency based on MBean usage patterns. Table 2-1 describes each policy.

Table 2-1 Refresh Policies

Setting	Description
`refresh-ahead` (default)	Refreshes MBeans 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 or programmatic pattern.
`refresh-behind`	Refreshes each MBean after the data is accessed. This method ensures optimal response time. However, the information returned is offset by the last refresh time.
`refresh-expired`	Refreshes each MBean from the remote member when the MBean 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 also sets the policy. For example:

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

2.1.7.3 Setting the Management Refresh Timeout

The <refresh-timeout> element specifies 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)

A unit of milliseconds is assumed if the value does not contain a unit. The default value is 250ms.

The tangosol.coherence.management.refresh.timeout system property also sets the timeout. For example:

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

2.1.8 Using an Existing MBean Server

The Oracle Coherence management framework allows the use of an existing MBean server to expose Oracle Coherence MBeans. The MBean server must be located in the same JVM process as the cluster member, and the cluster member must have JMX management enabled.

To use an existing MBean server, enter the MBean server's domain name using the <default-domain-name> element. MBean registration fails if an MBean server with the provided domain name is not found. The following example specifies an existing MBean server with the MyDomainName domain name:

<?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>
      <default-domain-name>MyDomainName</default-domain-name>
   </management-config>
</coherence>

Implement the com.tangosol.net.management.MBeanServerFinder interface to customize how the Oracle Coherence management framework locates an MBean server. Add the fully qualified name of the implementation class within the <server-factory> element using the <class-name> element and include any initialization parameters using the <init-params> element. Use the <default-domain-name> element to specify an existing MBean server domain name to use when instantiating the class.

The following example specifies the MyMBeanServerFinder implementation class and passes the MyDomainName domain name to the implementation class.

<?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>
      <default-domain-name>MyDomainName</default-domain-name>
      <server-factory>
         <class-name
            system-property="tangosol.coherence.management.serverfactory">
               package.MyMBeanServerFinder</class-name>
         <init-params>
            <init-param>
               <param-type>int</param-type>
               <param-value>0</param-value>
            </init-param>
         </init-params>
     </server-factory>
   </management-config>
</coherence>

The tangosol.coherence.management.serverfactory system property also specifies the implementation class. For example:

-Dtangosol.coherence.management.serverfactory=package.MyMBeanServerFinder

2.2 Accessing Oracle Coherence MBeans

JMX management must be enabled on a cluster member before you can access Oracle Coherence MBeans; see "Configuring JMX Management". The examples in this section use the -jmx argument of the Oracle Coherence startup script to enable JMX management.

This section includes the following topics:

Accessing MBeans Locally Using Java VisualVM
Accessing MBeans Locally Using the JConsole Utility
Allowing Remote Access to Oracle Coherence MBeans
Accessing MBeans Using the HTML Adapter Application
Setting Up the Oracle Coherence MBean Connector

2.2.1 Accessing MBeans Locally Using Java VisualVM

Java VisualVM is a management utility that is included with the JDK (JDK_HOME\bin\jvisualvm) and provides the ability to view and interact with MBeans. MBean functionality is provided as a plug-in to Java VisualVM. The plug-in must be installed from the Java VisualVM Plugins Center. From the tool, use the Tools -> Plugins option to install the VisualVM-MBeans plug-in.

To locally access MBeans using the Java VisualVM utility:

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
```
Start JDK_HOME\bin\jvisualvm. The Java VisualVM window appears.
From the Applications tree, click to expand Local and double-click the cluster member's process. The process information appears in a process tab on the right side of the window.
From the selected process tab, click the MBeans tab and expand the Coherence node to access the MBeans.

Description of the illustration jvisualvm.gif

2.2.2 Accessing MBeans Locally Using the JConsole Utility

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

To locally access MBeans using the JConsole utility:

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
```
Start JDK_HOME\bin\jconsole. The Java Monitoring & Management Console window appears and the JConsole: New Connection dialog box is displayed.
From the JConsole: New Connection dialog box, select the Local Process: option and then select the cluster member's process. For example:

Description of the illustration new_connection.gif
Click Connect.
From the Java Monitoring & Management Console window, select the MBeans tab and expand the Coherence node to access the MBeans.

Description of the illustration example-jmx-jconsole.gif

2.2.3 Allowing Remote Access to Oracle Coherence MBeans

Remote JMX management allows JMX clients that are located on remote computers to access Oracle Coherence MBeans. System properties configure remote access and are often set when starting a JVM that hosts an MBean server: that is, the system properties are set when starting cluster members that host an MBean server for the cluster. The following instructions provide only the minimum configuration that is required. See the JMX documentation for complete details on configuring JMX management:

http://download.oracle.com/javase/7/docs/technotes/guides/management/agent.html

To allow remote access to Oracle Coherence MBeans without security enabled, set the following system properties when you start a cluster member. For ease of use, set the system properties in the Oracle Coherence startup scripts so that they are automatically set when you use the -jmx argument.

-Dcom.sun.management.jmxremote.port=port
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false

Set the com.sun.management.jmxremote.port value to any available port on the cluster member. Specify the host and port in the JMX client (for example, JConsole) when you connect to the remote MBean server.

In some cases (such as virtualized environments or when using network address translation), the host name of the computer is incorrectly identified or the default value (127.0.0.1) is returned in the RMI stubs that are sent to the JMX client. As a result, the JMX client fails to connect to the MBean server. To ensure that the correct IP address is included in the RMI stubs, explicitly set the IP address of the host by using the java.rmi.server.hostname system property. For example:

-Djava.rmi.server.hostname=IP_Address

See the RMI documentation for complete details on RMI properties:

http://download.oracle.com/javase/7/docs/technotes/guides/rmi/javarmiproperties.html

2.2.4 Accessing MBeans Using the HTML Adapter Application

The HTML Adapter Web Application allows remote access to Oracle Coherence MBeans on cache clients and uses the HTML 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 is available from the following page:

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

To access MBeans using the HTML adapter:

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"
```
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
```
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.
Using a Web browser, access the adapter by using the host name and port 8082 for the address as shown in the following screen:

Description of the illustration example-jmx-httpadapter.gif

2.2.5 Setting Up the Oracle Coherence MBean Connector

Oracle Coherence ships with a program to start a cluster member as a dedicated MBean server host. This program provides remote access to Oracle Coherence MBeans by using the JMX Remote API using RMI or the HTTP server provided by the JMX reference implementation. Configure the RMI and HTTP ports setting, if required, to allow access through a firewall. The server is started using the following command:

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 argument. To allow access by using HTTP and a Web browser, include the -http argument. Both arguments may be included; however, at least one must be present for the member to start.

Table 2-2 describes optional properties 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 to which the JMX server binds. The default value is `localhost`. On Linux, the value 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. The default value is `9000`.
`tangosol.coherence.management.remote.connectionport`	The port used for the JMX RMI connection. The default value is `3000`.

Table 2-3 describes optional properties available 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. The default value is `8888`.

To connect to the MBean server using JConsole with the default settings, use the following command:

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

To connect to the MBean server using HTTP with the default settings, use the following URL:

http://localhost:8888

Note:

See the JMX Agent documentation to set up secure access using authentication and Secure Socket Layer (SSL):

http://download.oracle.com/javase/7/docs/technotes/guides/management/agent.html