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.1",
"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.1",
"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"
}
]
Property | Description | Example |
---|---|---|
|
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. |
|
|
An optional description which can be used as a UI label if given. |
|
|
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. |
|
|
Whether the agent was configured for authentication or not. |
|
|
The vendor of the container the agent is running in. This field is included if it could be automatically detected. |
|
|
The container product if detected |
|
|
The container’s version (if detected) |
|