////
  Copyright 2009-2023 Roland Huss

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
////
[#mbeans]
= 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.

[#mbean-config]
== 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.

image::debug-mbean.png[]

[#mbean-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
xref:jolokia_protocol.adoc#history[Tracking historical values].

[#mbean-serverhandler]
== 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.

[,shell]
----
$ 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
----

[#mbean-discovery]
== 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:

[,json,subs="attributes,verbatim"]
----
[
  {
    "agent_version": "{jolokia-version}",
    "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": "{jolokia-version}",
    "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"
  }
]
----

[#discovery-mbean-response]
.Response properties
[cols="15,~,30"]
|===
|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`
|===
