Connecting via JMX
This section describes how to:
Setting up to Connect via JMX
You can access the statistics through JMX in either of the following ways:
Via RMI on the Orchestrator process.
To set up JMX to listen through RMI on the Orchestrator process, add the following arguments to the JAVA_OPTS environment variable before executing start-wan.sh :
JAVA_OPTS="-Dcom.sun.management.jmxremote.port=<number>
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false"
Note:
Any additional Orchestrator process started on the same machine will fail with an "Address is in use" error if the JAVA_ OPTS environment variable is still visible. Thus JAVA_ OPTS should be set inside the script that starts the process, or else the port number should be changed.
By communicating with the Orchestrator process directly. Simply start your WAN Region and connect your monitoring application to the Orchestrator process.
Using JMX Beans to Display Statistics
The Orchestrators expose one MBean for each cache and one MBean for each replica. Once connected to an Orchestrator process via JMX, you can use the Terracotta WAN-specific MBeans within the org.terracotta.wan domain to display statistics about:
The overall state of the master cache and its replicas.
A particular replica cache.
Displaying the Overall Statistics for a Cache and its Replicas
Use the following ObjectName form to display the overall statistics for a master cache and its replicas:
org.terracotta.wan:type=WAN,cacheManager="<name>",cache="<name>"
where:
cacheManager specifies the name of the cache's cache manager, enclosed in quotation marks.
cache specifies the name of the cache, enclosed in quotation marks.
For example:
The following ObjectName displays the overall cache-wide statistics for the cache "test-cache-1" in the cacheManager "test".
org.terracotta.wan:type=WAN,cacheManager="test",cache="test-cache-1"
Displaying Statistics for a Particular Replica
To display only the statistics for a particular replica of the cache, append replica=<host_port> to the ObjectName, as follows:
org.terracotta.wan:type=WAN,cacheManager="<name>",cache="<name>",replica=<host_port>
where <host_port> specifies the host name and port of the replica. For example, myhost_1234. Do not enclose the value in quotation marks.
For example:
The following ObjectName displays statistics only for the cache's replica which has the hostname myhost and listens on port 1234 (as configured in the wan.xml for the replica).
org.terracotta.wan:type=WAN,cacheManager="test",cache="test-cache-1",
replica=myhost_1234
Programmatic Access through JMX via RMI
As a convenience, some classes have been added for programmatic access to the remote statistics. If you have configured your Orchestrator process to listen for JMX via RMI, you may use the RMIStatisticConnection class. In this example the Orchestrator is running on "localhost", with an RMI port of 9999. The cache to connect to is "test-cache-1" in the "test" cache manager, as in previous examples.
// Create the connection
StatisticConnection rmiStatisticConnection = new RMIStatisticConnection(
"localhost", 9999, "test", "test-cache-1");
// Get a statistic
Gauge<String> g = rmiStatisticConnection.getStatistic(
StatisticName.CONFIG_REPLICATION_MODE);
// Do something with the statistic
System.out.println(g.getValue());
// Close the connection
rmiStatisticsConnection.close();
For gauges whose values are non-numeric, calling the getValue() method again will fetch the latest value (i.e., you can call it in a loop and expect the value to change). The statistics client classes are inside wan-core.jar. In order to use it, pull in wan-core.jar as a Terracotta Maven Plugin dependency.
For gauges whose values are numeric, you can expect getValue() to eventually return the most recent value, but with a certain delay, depending on your cluster's configuration. For example, your implementation might throttle value updates; by default, the value is cached for 10 seconds, no matter how many actual updates take place during that interval.