Jolokia MBeans

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

Configuration MBean

This MBean, which is registered under the name jolokia:type=Config, allows changing debug-related configuration parameters. Changes are non-persistent and get lost after a restart of the hosting application server.

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.

History MBean

The jolokia:type=History can be used to remember attribute and return values within the agent’s memory. 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 Tracking historical values.

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.

$ curl -s -u jolokia:jolokia 'http://localhost:8080/jolokia/exec/jolokia:agent=192.168.0.221-72527-5d9f8cd3-servlet,type=ServerHandler/mBeanServersInfo()' | jq -r .value
Found 1 MBeanServers
    ++ com.sun.jmx.mbeanserver.JmxMBeanServer@75a1cd57: default domain = DefaultDomain, 108 MBeans
        Domains:
         == JMImplementation
              type=MBeanServerDelegate
         == java.util.logging
              type=Logging
         == jdk.management.jfr
              type=FlightRecorder
         == java.lang
              name=Metaspace Manager,type=MemoryManager
              name=Metaspace,type=MemoryPool
              name=CodeHeap 'profiled nmethods',type=MemoryPool
              type=ClassLoading
              type=Runtime
              name=CodeCacheManager,type=MemoryManager
              type=OperatingSystem
              name=Compressed Class Space,type=MemoryPool
              type=Threading
              name=CodeHeap 'non-nmethods',type=MemoryPool
              name=G1 Eden Space,type=MemoryPool
              name=G1 Old Gen,type=MemoryPool
              name=G1 Survivor Space,type=MemoryPool
              name=G1 Young Generation,type=GarbageCollector
              type=Memory
              type=Compilation
              name=G1 Old Generation,type=GarbageCollector
              name=CodeHeap 'non-profiled nmethods',type=MemoryPool
         == com.sun.management
              type=HotSpotDiagnostic
              type=DiagnosticCommand
         == java.nio
              name=mapped - 'non-volatile memory',type=BufferPool
              name=direct,type=BufferPool
              name=mapped,type=BufferPool
         == Users
              database=UserDatabase,type=User,username="jolokia"
              database=UserDatabase,rolename="jolokia",type=Role
              database=UserDatabase,rolename="manager-gui",type=Role
              database=UserDatabase,type=User,username="tomcat"
              database=UserDatabase,type=UserDatabase
         == Catalina
              context=/,host=localhost,type=Manager
              context=/manager,host=localhost,name=BasicAuthenticator,type=Valve
...
              type=Engine
         == jolokia
              agent=192.168.0.221-72527-5d9f8cd3-servlet,type=History
              agent=192.168.0.221-72527-5d9f8cd3-servlet,type=Config
              agent=192.168.0.221-72527-5d9f8cd3-servlet,type=Discovery
              agent=192.168.0.221-72527-5d9f8cd3-servlet,type=NotificationStore
              agent=192.168.0.221-72527-5d9f8cd3-servlet,type=ServerHandler

Platform MBeanServer: com.sun.jmx.mbeanserver.JmxMBeanServer@75a1cd57

Discovery MBean

jolokia:type=Discovery can be used to detect other Jolokia Agents 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_version": "2.1.2",
    "agent_id": "192.168.0.221-72527-6baa8838-servlet",
    "server_product": "tomcat",
    "server_vendor": "Apache",
    "server_version": "10.1.16",
    "secured": true,
    "url": "http://192.168.0.221:8080/jolokia"
  },
  {
    "agent_version": "2.1.2",
    "agent_id": "192.168.0.221-89505-1328eb8a-osgi",
    "server_product": "felix",
    "server_vendor": "Apache",
    "server_version": "7.0.5",
    "secured": false,
    "url": "http://192.168.0.221:8181/jolokia"
  }
]

Table 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.	`192.168.0.221-72527-6baa8838-servlet`
`agent_description`	An optional description which can be used as a UI label if given.	`Apache Tomcat`
`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://192.168.0.221: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)	`10.1.16`