Coherence is configured by default to start in dynamic management mode. Dynamic management mode is a high availability feature that automatically selects the senior cluster member as the JMX cluster member. The JMX cluster member hosts an MBean server that is responsible for aggregating management information from all cluster members. If the JMX cluster member is not operational, then the next most senior cluster member is automatically selected as the JMX cluster member.

You can find the JMX service URL by querying the NameService service on any cluster member using the com.tangosol.discovery.NSLookup class. The class has a command line interface or you can call the lookupJMXServiceURL method. For example:

java -cp %COHERENCE_HOME%\lib\coherence.jar com.tangosol.discovery.NSLookup -name management/JMXServiceURL

Cluster JRCluster:      service:jmx:rmi://127.0.0.1:62427/stub/rO0ABXNyAC5qYXZheC5tYW5hZ2VtZW50LnJlbW90ZS5ybWkuUk1...

All cluster members can potentially be selected as the JMX cluster member. To specify that a cluster member should be excluded from being selected as the JMX 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="coherence.management">none
      </managed-nodes>
   </management-config>
</coherence>

The default value if no value is specified is dynamic and indicates that a cluster member can become the JMX cluster member.

The coherence.management system property also excludes a cluster member from being selected as the JMX cluster member. For example:

-Dcoherence.management=none

One or more cluster members can be explicitly configured to 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.

In smaller clusters, a common practice is to have dedicated JMX JVMs on two existing cluster members to ensure fault tolerance. In very large clusters, it is often practical to have two computers that are dedicate solely for JMX; however, this is not always necessary.

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="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 coherence.management system property also enables remote JMX management. For example:

-Dcoherence.management=all

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="coherence.management">local-only
      </managed-nodes>
   </management-config>
</coherence>

The coherence.management system property also enables local JMX management. For example:

-Dcoherence.management=local-only

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. The argument is not required when using dynamic management, which is the default management configuration.

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:

-Dcoherence.management=all
-Dcoherence.management.remote=true

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="coherence.management.remote">false
      </allow-remote-management>
   </management-config>
</coherence>

The coherence.management.remote system property also disables remote management. For example:

-Dcoherence.management.remote=false

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="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="coherence.management">none</managed-nodes>
      <allow-remote-management
         system-property="coherence.management.remote">false
      </allow-remote-management>
   </management-config>
</coherence>

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. For example, the pattern .*type=Service,name=Management,.* excludes MBeans with type=Service and name=Management. 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="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 coherence.management.exclude system property also filters MBeans. For example:

-Dcoherence.management.exclude=.*type=Service,name=Management,.*

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="coherence.management.refresh.policy">
         refresh-ahead</refresh-policy>
      <refresh-expiry
         system-property="coherence.management.refresh.expiry">1s
      </refresh-expiry>
      <refresh-timeout
         system-property="coherence.management.refresh.timeout">300ms
      </refresh-timeout>
   </management-config>
</coherence>

This section includes the following topics:

• Setting the Management Refresh Expiry
  
• Setting the Management Refresh Policy
  
• Setting the Management Refresh Timeout
  

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="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="coherence.management">all
      </managed-nodes>
      <default-domain-name>MyDomainName</default-domain-name>
      <server-factory>
         <class-name
            system-property="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 coherence.management.serverfactory system property also specifies the implementation class. For example:

-Dcoherence.management.serverfactory=package.MyMBeanServerFinder

1. Start a cache server using the COHERENCE_HOME\bin\cache-server script. For example:

   COHERENCE_HOME\bin\cache-server

2. Start VISUALVM_HOME\bin\visualvm. The VisualVM window displays.
3. 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.
4. From the selected process tab, click the MBeans tab and expand the Coherence node to access the MBeans.
   
   Description of the illustration jvisualvm.png

1. Start a cache server using the COHERENCE_HOME\bin\cache-server script. For example:

   COHERENCE_HOME\bin\cache-server
   

2. Start JDK_HOME\bin\jconsole. The Java Monitoring & Management Console window appears and the JConsole: New Connection dialog box is displayed.
3. 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
4. Click Connect.
5. 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

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. See Monitoring and Management Using JMX Technology in Java SE Monitoring and Management Guide. The following instructions provide only the minimum configuration that is required.

To allow remote access to Oracle Coherence MBeans without security enabled, set the following system properties when you start a cluster member:

-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

For more information, see the Java Platform Standard Edition 11 or Java Platform Standard Edition 17 documentation.

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. For example:

   COHERENCE_HOME\bin\coherence
   

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 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

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 -Dcoherence.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-3 describes optional properties available for HTTP configuration.

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

1. Launch VisualVM from the bin directory under the VisualVM install directory by using the following commands:

   cd install_directory/bin

   ./visualvm

2. From the VisualVM main menu, select Tools and click Plugins.
3. If the VisualVM-Coherence plug-in is not displayed in the Available Plugins tab, click Check for Newest.
4. Select the Install checkbox for the VisualVM-Coherence plug-in. The details of the plug-in are displayed in the right pane.
5. Click Install.
6. On the Plugin Installer Welcome screen, click Next.
7. In the Plugin Installer License Agreement screen, check I accept and click Install.
8. The plug-in begins to install. When the installation completes, click Finish.