PRODUCTS AND SERVICES INDUSTRIES SUPPORT PARTNERS COMMUNITIES ABOUT
  Coherence 3.4 User Guide
  How to Manage Coherence Using JMX
 Browse Space
Version 99 by Andy Nguyen
on May 20, 2009 13:06.

<< Changes from 98 to 99
compared with
Current by Gene Gleyzer
on Jul 10, 2009 15:05.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 1 changes. View first change.

  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. If you are new to JMX, you should start is with [this article|http://java.sun.com/developer/technicalArticles/J2SE/jmx.html].
  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. If you are new to JMX, you should start with [this article|http://java.sun.com/developer/technicalArticles/J2SE/jmx.html].
  
 To manage Coherence using JMX:
  
 * [Add JMX libraries to the Coherence classpath|#addingjmx] (if necessary)
 * [Configure the Coherence Management Framework|#configurejmx]
 * [View and manipulate Coherence MBeans using a JMX client of your choice|#accessmbeans]
  
 {info:title=JMX support}
 [Coherence Enterprise Edition and higher|Coherence Features by Edition] support clustered JMX, allowing access to JMX statistics for the entire cluster from any member. Coherence Standard Edition provides only local JMX information.
 {info}
  
 h2.Adding JMX libraries to the Coherence classpath {anchor:addingjmx}
  
 To manage a Coherence cluster using JMX, ensure that you have the necessary JMX 1.0 or later classes ({{javax.management.*}}) in the classpath of at least one Coherence cluster node, known as an MBeanServer host. The cluster nodes that are not MBeanServer hosts will be managed by the MBeanServer host(s) by using the Coherence Invocation service.
  
 All compliant Java SE 5.0 JREs and Java EE application servers supply a JMX 1.0 or later implementation; therefore, if the {{MBeanServer}} host node is running within a Java SE 5.0 JVM or Java EE application server, no additional actions are necessary. For standalone applications running within a pre-Java SE 5.0 JVM, you can download the necessary JMX libraries [here|http://java.sun.com/products/JavaManagement/download.html] and add them to the classpath.
  
 h2.Configuring the Coherence Management Framework {anchor:configurejmx}
  
 In most cases, you can enable JMX management simply by setting the {{tangosol.coherence.management}} Java system property on all Coherence cluster nodes that are acting as MBeanServer hosts:
 {noformat}
 -Dtangosol.coherence.management=all
 {noformat}
  
 and the {{tangosol.coherence.management.remote}} Java system property on all cluster nodes:
 {noformat}
 -Dtangosol.coherence.management.remote=true
 {noformat}
  
 The use of dedicated JMX cluster members is a common pattern. This approach avoids loading JMX software into every single cluster member, while still providing fault-tolerance should a single JMX member run into issues. Setting tangosol.coherence.management to "all" on nodes that are not acting as MBeanServer hosts, will consume capacity (~3-5%) when the node starts and increase the time required for the node to join the cluster. Therefore, it is recommended to set the value to "none" or "local-only" for remotely managed nodes.
  
 In general, the Coherence Management Framework is configured by the {{management-configuration}} operational configuration element in the Coherence Operational Configuration deployment descriptor ({{tangosol-coherence.xml}}). The following sub-elements control the behavior of the Management Framework:
  
 | *Element* | *Description*|
 | {{default-domain-name}} | Specifies the name of the JMX domain used to register MBeans exposed by the Coherence Management Framework.
 | {{managed-nodes}} | Specifies whether a cluster node's JVM has an in-process MBeanServer and if so, whether the node allows management of other nodes' managed objects. Valid values are {{none}}, {{local-only}}, {{remote-only}} and {{all}}. For example, if a node has an in-process MBeanServer and you would like this node to manage other nodes' MBeans, then set this attribute to {{all}}.
 |{{allow-remote-management}}|Specifies whether this cluster node will register its MBeans in a remote MBeanServer(s).
 |{{read-only}}|Specifies whether the MBeans exposed by this cluster node allow operations that modify run-time attributes. |
  
 For additional information on each of these attributes, please see the [Operational Configuration Elements].
  
 {info:title=A note about Java 1.4}
 Starting with [Coherence 3.4|http://coherence.oracle.com/display/COH34UG/Coherence+3.4+Release+Notes], Coherence monitors the [Java Platform MBeans|http://java.sun.com/j2se/1.5.0/docs/guide/management/mxbeans.html] which makes it possible to see JVM statistics from across the cluster alongside the other statistics tracked by Coherence. This feature is on by default, as most customer deployments are on Java 1.5 and above. However the following exception may be thrown on Java 1.4 and Coherence 3.4:
 {noformat}
 The MBean query feature requires a local MBeanServer
  java.lang.NoClassDefFoundError: javax/management/MalformedObjectNameException
 {noformat}
 This feature can be disabled for 1.4 JVMs that don't have Platform MBeans available. Set the following system property:
 {noformat}
  -Dtangosol.coherence.management.jvm.all=false
 {noformat}
 {info}
  
 h2.Accessing Coherence MBeans {anchor:accessmbeans}
  
 After configuring the Coherence Management Framework and launching one or more Coherence cluster nodes (at least one being an MBeanServer host) you can view and manipulate the Coherence MBeans registered by all cluster nodes using standard JMX API calls. See the Javadoc for the {javadoc:com.tangosol.net.management.Registry} class for details on the various MBean types registered by Coherence clustered services.
  
 Coherence ships with two examples that demonstrate accessing Coherence MBeans by using JMX. The first uses the {{HttpAdapter}}, shipped as part of the [JMX reference implementation|http://java.sun.com/products/JavaManagement/download.html] ({{jmxtools.jar}}). To run the example on a pre-Java SE 5.0 JVM, start the Coherence command line application using the following command on Windows (note that it is broken up into multiple lines here only for formatting purposes; this is a single command entered on one line):
  
 {term}
 java -cp jmxri.jar;jmxtools.jar;coherence.jar
  -Dtangosol.coherence.management=all
  -Dtangosol.coherence.management.remote=true
  com.tangosol.net.CacheFactory
 {term}
  
 On Unix:
  
 {term}
 java -cp jmxri.jar:jmxtools.jar:coherence.jar
  -Dtangosol.coherence.management=all
  -Dtangosol.coherence.management.remote=true
  com.tangosol.net.CacheFactory
 {term}
  
 Once the Coherence command line application has started, type {{jmx 8082}} and press *Enter*. This starts the {{HttpAdapter}} on {{http://localhost:8082}} in the cluster node's JVM and makes the cluster node an MBeanServer host. You can now use the {{HttpAdapter}} web application to view and manipulate Coherence MBeans registered by all cluster nodes:
  
  
 !Example-JMX-HttpAdapter.gif|width=675, height=564!
  
  
 Alternatively, you can run this example with the Sun Java SE 5.0 JVM and use the JConsole utility included with the Sun Java SE 5.0 JDK to view and manipulate Coherence MBeans. To do so, start the Coherence command line application 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):
  
 {term}
 java -Dcom.sun.management.jmxremote
  -Dtangosol.coherence.management=all
  -Dtangosol.coherence.management.remote=true
  -jar coherence.jar
 {term}
  
 Once the Coherence command line application has started, launch the JConsole utility (located in the {{bin}} directory of the Sun Java SE 5.0 JDK distribution) and open a new connection to the JVM running the Coherence command line application:
  
 !Example-JMX-JConsole.gif|width=675,height=564!!
  
 The second example is a JSP page ({{JmxCacheExplorer.jsp}}) that displays basic information on each running Coherence cache using JMX API calls. You can find this example in the {{examples/jsp/explore}} directory under the root of your Coherence installation.
  
 Additional JMX examples may be found on the [Coherence Forums|http://forums.oracle.com/forums/forum.jspa?forumID=480].
  
 h2.Using Coherence MBeanConnector to Access MBeans
  
 Coherence ships with a program to launch a cluster node as a dedicated MBeanServer 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 are user-configurable, 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):
  
 {term}
 java -Dtangosol.coherence.management=all
  -cp coherence.jar com.tangosol.net.management.MBeanConnector [-http -rmi]
 {term}
  
 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 present for the node to start.
  
 The following table describes 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. |
  
 The following table describes optional properties that can be used for HTTP configuration. (NOTE: This flag requires [Sun's JMX RI|http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/download.jsp] in the classpath):
  
 |*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:
  
 {term}
 jconsole service:jmx:rmi://localhost:3000/jndi/rmi://localhost:9000/server
 {term}
  
 To connect by using HTTP with default settings use the following URL:
  
 {term}
 http://localhost:8888
 {term}
  
 h2. Configuring Management Refresh Methodology
  
 The current release of Coherence offers several ways to reduce the latency of management information. Refresh policy was introduced in Coherence 3.3 to allow for optimization of the retrieval of information from remotely managed nodes. Two new settings were added to help integrators and administrators configure the refresh policy.
  
 The {{tangosol.coherence.management.refresh.expiry}} property specifies the minimum time interval between the remote retrieval of management information from remote nodes.
  
 {term}
 -Dtangosol.coherence.management.refresh.expiry
 {term}
  
 The value of this element must be in the following format:\\
 {noformat}
 [\d]+[[.][\d]+]?[MS|ms|S|s|M|m|H|h|D|d]?
 {noformat}
 where the first non-digits (from left to right) indicate the unit of time duration: \\
 {panel}
 * {{MS}} or {{ms}} (milliseconds)
 * {{S}} or {{s}} (seconds)
 * {{M}} or {{m}} (minutes)
 * {{H}} or {{h}} (hours)
 * {{D}} or {{d}} (days)
 {panel}
 If the value does not contain a unit, a unit of milliseconds is assumed.
  
 The {{tangosol.coherence.management.refresh.policy}} property defines the refresh policy for the MBean. \\
 {term}
 -Dtangosol.coherence.management.refresh.policy
 {term}
  
 Valid values for this property are:
 |*Setting*|*Description*|
 |refresh-expired |This setting has the same functionality as in pre-3.4 Coherence releases. 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.|
 |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.