Reference Documentation

h1. JMX Guide

TODO: http://jira.terracotta.org/jira/browse/DOC-178

The Terracotta server publishes a number of MBeans to provide information on the operation of the cluster.  The [Terracotta Developer Console] and the [Terracotta Operations Center] use the JMX interface to provide real-time information, but the same interface can be used by any JMX client.  As of Terracotta 3.0, there is also a new [API to report platform cluster events|Cluster Events] such as client nodes joining or leaving the cluster.

h2. JMX Authentication

It is possible to configure the Terracotta Server to require authentication credentials before JMX communications take place. This will secure server shutdown, the [Terracotta Developer Console], the [Terracotta Operations Center], JConsole, and any other processes attempting to connect via JMX. Server authentication will not provide secure message transmission once valid credentials are provided by a listening client. The JMX messages will not be encrypted. For this reason, we recommend that the Terracotta server be placed in a secure location on a private network and only be queried remotely via an encrypted tunnel such as those provided by stunnel or SSH.


Once configured properly, the [Terracotta Developer Console] (or the [Terracotta Operations Center]) connection dialog will prompt you for credentials before completing a server connection. The stop-tc-server script located in the bin directory will also prompt for a username and password.

h3. Configuration
See the [Configuration Guide and Reference|Configuration Guide and Reference#server-authentication] for information on configuring the Terracotta server to use JMX authentication.

h3. Permissions

# chmod 500 jmxremote.password 


NOTE: Setting these permissions on Windows is possible but requires a special DOS command. This permission is only available on Windows drives with NTFS formatting. See http://java.sun.com/j2se/1.5.0/docs/guide/management/security-windows.html for more information.

h3. Users/Groups


# echo "myusername mypassword" >> jmxremote.password
# echo "myusername readwrite" >> jmxremote.access


{panel:title=Sample excerpt from jmxremote.password}
# monitorRole QED
# controlRole R&D
myusername mypassword

{panel:title=Sample excerpt from jmxremote.access}
# Default access control entries:
# o The "monitorRole" role has readonly access.
# o The "controlRole" role has readwrite access.

monitorRole readonly
controlRole readwrite
myusername readwrite

h2. Platform Cluster Events and Cluster Node Data

[*A platform cluster-events API*|Cluster Events] that allows events to be communicated using a standard Java programming approach is available as part of the Terracotta API introduced with Terracotta 3.0.0. This Java-based events API can be more easily integrated into a Java applications environment.



h2. Distributed Garbage Collection
*TODO:* Write me.

h2. Rogue/Slow/Unhealthy Client Detection and monitoring 

Here is some sample code for getting client MBeans
MBeanServerConnection mbsc = null;
try {
  mbsc = jmxc.getMBeanServerConnection();
} catch (IOException e) {
  throw new AssertionError(e);
DSOMBean dsoMBean = (DSOMBean) MBeanServerInvocationHandler
          .newProxyInstance(mbsc, L2MBeanNames.DSO, DSOMBean.class, false);

ObjectName[] clientObjectNames = dsoMBean.getClients();
DSOClientMBean[] clients = new DSOClientMBean[clientObjectNames.length];

This is a partial list of MBeans exposed to monitor these clients: 

* *com.tc.stats.isTunneledBeansRegistered*&mdash;Is the bean registered
* *com.tc.stats.getL1InfoBeanName*&mdash;Get the name(class ObjectName) of this bean
* *com.tc.stats.getL1InfoBean*&mdash;Get the MBean
* *com.tc.stats.getInstrumentationLoggingBeanName*&mdash;Get the name(class ObjectName) of the instrumentation logging MBean)
* *com.tc.stats.getInstrumentationLoggingBean*&mdash;Get the Instrumentation logging MBean
* *com.tc.stats.getRuntimeLoggingBeanName*&mdash;Get the name(Class ObjectName) of te runtime logging MBean
* *com.tc.stats.getRuntimeLoggingBean*&mdash;Get the run time logging MBean
* *com.tc.stats.getRuntimeOutputOptionsBeanName*&mdash;Get the name(class ObjectName) of the runtime output options MBean
* *com.tc.stats.getRuntimeOutputOptionsBean*&mdash;Get the runtime output options MBean
* *com.tc.stats.getChannelID*&mdash;Get the channel ID
* *com.tc.stats.getRemoteAddress*&mdash;Get the remote address of the channel
* *com.tc.stats.getTransactionRate*&mdash;Get the transaction rate for the client
* *com.tc.stats.getObjectFaultRate*&mdash;Get the object fault rate for the client
* *com.tc.stats.getObjectFlushRate*&mdash;Get the object flush rate for the client
* *com.tc.stats.getPendingTransactionsCount*&mdash;Get the pending transactions count for the client
* *com.tc.stats.getStatistics*&mdash;Get the statistics for the given properties
* *com.tc.stats.killClient*&mdash;Kill this client
* *com.tc.stats.