Chapter 7. Jolokia MBeans

Besides bridging JMX to the HTTP/JSON world, the Jolokia agents also install their own MBeans which provide the extra services described in this chapter.

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.