Chapter 7. Jolokia MBeans

7.1. Configuration MBean

This MBean, which is registered under the name jolokia:type=Config, allows changing configuration parameters. Changes are non-persistent and get lost after a restart of the hosting application server. Debugging mode and the history store can be configured with this MBean.

7.1.1. Debugging

Debugging can be switched on by setting the attribute Debug. When debugging is switched on, the Jolokia agent will store debug information in a ring buffer in memory, whose size can be tuned with the attribute MaxDebugEntries. The debug information can be fetched by the operation debugInfo. This debugging output will contain the JSON responses (which in turn contain their requests) sent to the client. Finally, the operation resetDebugInfo clears the debug history.

7.1.2. History store

The history store can be used to remember attribute and return values within the agent's memory. The Nagios check check_jmx4perl, for instance, uses this feature for its delta check, which measures changes in attribute values. In order to switch on history tracking, two operations are provided:

setHistoryLimitForOperation: JMX operation for switching on tracking of the execution of JMX operations. It takes five arguments: The MBean and operation name, an optional target URL when the agent is used in proxy mode and as limit the number of maximal entries to track and a duration in seconds. If the target URL is given, then request for this specific target are tracked, otherwise, if the URL is null, requests to this operation on the local agent are tracked. The return value of calling this operations is stored in a buffer with the specified length, where the oldest elements will be shifted out in case of an overflow.
setHistoryLimitForAttribute: JMX operation for switching on tracking of an JMX attribute's value. It takes six arguments: The MBean and attribute name, an optional path and target URL and as limit the maximal number of entries to remember and/or an maximum duration for the elements to keep in the history. As above, the target URL is only used for proxy requests. The path can be used to store only read requests with the given path.

There are two kinds of limits which can be applied: Either by a maximum number of historical values to remember or a maximum duration for the values to keep. If both limits are given in a configuration call on the MBean above, both limits are applied. In any case, there are never more values remembered than the global limit which can be set and retrieved with attribute HistoryMaxEntries.

The History store can be emptied with a call to the operation resetHistoryEntries. This also switches off all history tracking.

If for a request history tracking is switched on, the JSON response will contain an extra field history which contains a list with historical values along with the timestamp when it was recorded. This format is described in detail in Section 6.5, “Tracking historical values”.

7.2. Server Handler

The MBean jolokia:type=ServerHandler has a single operation mBeanServersInfo with no arguments. This operation can be used to dump out the name of all registered MBeans on all found MBeanServers. It is helpful to get a quick and condensed overview of the available JMX information.

7.3. Discovery MBean

The MBean jolokia:type=Discovery can be used to detect other MBeans by sending multicast discovery UDP requests. Every agent which has discovery enabled will respond with information about the agent itself and the access URL. The MBean itself ha two operations: lookupAgents and lookupAgentsWithTimeout which either use a default timeout of one second for waiting for response packet or with a user provided timeout given as argument to this operation. Both methods return an JSON array which contains JSON objects, one for each agent discovered.

A return value of these operation could look like:

[
  {
      "agent_id" : "10.9.11.25-58613-81b087d-servlet",
      "url": "http://10.9.11.25:8778/jolokia",
      "secured": false,
      "server_vendor" : "Apache",
      "server_product" : "Tomcat",
      "server_version" : "7.0.35"
  },
  {
      "agent_id" : "10.9.11.87-23455-9184ef-osgi",
      "agent_description": "My OSGi container",
      "url": "http://10.9.11.87:8080/jolokia",
      "secured": true,
      "server_vendor" : "Apache",
      "server_product" : "Felix",
      "server_version" : "4.2.1"
  }
]

Table 7.1. Response properties

Property	Description	Example
`agent_id`	Each agent has a unique id which can be either provided during startup of the agent in form of a configuration parameter or being autodetected. If autodected, the id has several parts: The IP, the process id, hashcode of the agent and its type. This field will be always provided.	10.9.11.87-23455-9184ef-osgi
`agent_description`	An optional description which can be used as a UI label if given.	ServiceMix ESB
`url`	The URL how this agent can be contacted. This URL is typically autodetected. For the JVM agent it should be highly accurate. For the servlet based agents, it depends. If configured via an initialisation parameter this URL is used. If autodetected it is taken from the first HTTP request processed by the servlet. Hence no URL is available until this first request was processed. This property might be empty.	http://10.9.11.87:8080/jolokia
`secured`	Whether the agent was configured for authentication or not.	false
`server_vendor`	The vendor of the container the agent is running in. This field is included if it could be automatically detected.	Apache
`server_product`	The container product if detected	tomcat
`server_version`	The container's version (if detected)	7.0.50