Agents

Jolokia is an agent based approach to JMX, which requires that clients install an extra piece of software, the so-called agent. This software either needs to be deployed on the target server which should be accessed via remote JMX (Agent mode), or it can be installed on a dedicated proxy server (Proxy Mode). For both operational modes, there are three different kinds of agents[1].

Webarchive (War) agent

This agent is packaged as a Jakarta EE Web archive (WAR). It is the standard installation artifact for Java web applications and probably one of the best known deployment formats. Jolokia ships with a WAR agent which can be deployed like any other web application. This agent has been tested on many Jakarta EE servers, from well-known market leaders to rarer species.

OSGi agent

OSGi is a middleware specification focusing on modularity and a well defined dynamic lifecycle[2]. The Jolokia 1.x OSGi agent used to come in two flavors (with and without packaged Felix HTTP Service bundles). With Jolokia 2 there’s only one bundle which requires a OSGi CMPN Whiteboard extender implementation available in target OSGi runtime.

JVM agent

Starting with Java 6 the JDK provided by Oracle contains a lightweight HTTP-Server which is used e.g. for the reference WebService stack implementation included in Java 6. Using the Java-agent API (normally used by profilers and other development tools requiring the instrumentation during the class loading phase), the JVM 11+ Jolokia agent is the most generic one. It is able to instrument any Java application running on a Oracle JDK 11+[3]. This Jolokia agent variant is fully featured, however tends to be a bit slow since the provided HTTP-Server is not optimized for performance. However it is useful for servers like Hadoop or Teracotta, which do not provide convenient hooks for an HTTP-exporting agent on their own.

Jakarta EE Agent (WAR)

Installation and Configuration

The WAR agent is the most popular variant, and can be deployed in a servlet container just like any other Jakarta EE web application.

Tomcat example

A simple example for deploying the WAR agent on Tomcat can be found in the Jolokia quickstart.

Often, installation is simply a matter of copying the agent WAR to a deployment directory (webapps/ directory on Tomcat). On other platforms an administrative Web GUI or a command line tool need to be used for deployment. Providing detailed installation instructions for every servlet container is out of scope for this document.

The servlet itself can be configured in two ways:

Servlet Init Parameters

Jolokia can be configured with init-param declarations within the servlet definition in WEB-INF/web.xml. The known parameters are described in Table 1, “Servlet init parameters”. The stock agent needs to be repackaged, though, in order to modify the internal web.xml.

Servlet Context Parameters

A more convenient possibility might be to use servlet context parameters, which can be configured outside the WAR archive. This is done differently for each servlet container but involves typically the editing of a configuration file. E.g. for Tomcat 10.1, the context for the Jolokia agent can be adapted by putting a file jolokia.xml below $TC/conf/Catalina/localhost/ with a content like:

<Context>
  <Parameter name="maxDepth" value="1"/>
</Context>

Additionally, the configuration options discoveryEnabled and discoveryAgentUrl can be provided via environment variables or system properties, too. See below for details.

Table 1. Servlet init parameters
Parameter Description Example

jsr160ProxyAllowedTargets

Path to a white list of patterns which are matched against possible JMX service URL for incoming requests. If no white list is specified, default blacklist is effective which includes service:jmx:rmi:///jndi/ldap:.*.

/opt/jolokia/jsr160-proxy-allowed-patterns.txt

policyLocation

Location of the policy file to use. This is either a URL which can read from (like a file: or http: URL) or with the special protocol classpath: which is used for looking up the policy file in the web application’s classpath. See Policy Location for details about this parameter.

file:/home/jolokia/jolokia-access.xml for a file based access to the policy file. Default is classpath:/jolokia-access.xml.

restrictorClass

Full classname of an implementation of org.jolokia.server.core.service.api.Restrictor which is used as a custom restrictor for securing access via Jolokia.

com.mycompany.jolokia.CustomRestrictor (which must be included in the war file and must implement org.jolokia.server.core.service.api.Restrictor)

allowDnsReverseLookup

Access can be restricted based on the remote host accessing Jolokia. This host can be specified as address or an hostname. However, using the hostname normally requires a reverse DNS lookup which might slow down operations. If you want to use reverse DNS lookup set this property to true.

Default: false

debug

Debugging state after startup. Can be changed via the config MBean during runtime.

Default: false

logHandlerClass

Loghandler to use for providing logging output. By default logging is written to standard out and error but you can provide here a Java class implementing org.jolokia.server.core.service.api.LogHandler for an alternative log output. Few implementations are included in WAR this agent:

  • org.jolokia.server.core.service.impl.StdoutLogHandler which logs to standard output

  • org.jolokia.server.core.service.impl.QuietLogHandler which switches off logging completely.

  • org.jolokia.server.core.service.impl.JulLogHandler which uses a java.util.logging Logger with name org.jolokia

  • org.jolokia.server.core.http.AgentServlet.ServletLogHandler is used by default and delegates to jakarta.servlet.GenericServlet.log() methods

Default: org.jolokia.server.core.http.AgentServlet.ServletLogHandler

logHandlerName

A parameter which may be used to configure logger name which may be used with some org.jolokia.server.core.service.api.LogHandler implementations.

Default: org.jolokia

historyMaxEntries

Entries to keep in the history. Can be changed at runtime via the config MBean.

Default: 10

debugMaxEntries

Maximum number of entries to keep in the local debug history (if enabled). Can be changed via the config MBean at runtime.

Default: 100

maxDepth

Maximum depth when traversing bean properties. If set to 0, depth checking is disabled

Default: 15

maxCollectionSize

Maximum size of collections returned when serializing to JSON. When set to 0, collections are never truncated.

Default: 0

maxObjects

Maximum number of objects which are traversed when serializing a single response. Use this as an airbag to avoid boosting your memory and network traffic. Nevertheless, when set to 0 no limit is imposed.

Default: 0

serializeLong

How to serialize long values in the JSON response: number or string. The default number simply serializes longs as numbers in JSON. If set to string, longs are serialized as strings. It can be useful when a JavaScript client consumes the JSON response, because numbers greater than the max safe integer don’t retain their precision in JavaScript.
Added since Jolokia 2.0.3

Default: number

includeRequest

A flag (defaults to true) which controls whether the incoming request should be included in the response (under request key).
This applies to bulk requests too, so correlation should be done by index of requests and responses (these are guaranteed to be matching).
Added since Jolokia 2.1.0

Default: true

dateFormat

A format specifier to use for formatting dates, calendars and instances of java.time.Temporal. Additionally we can use:

  • unix to serialize dates as Unix epoch time in seconds

  • time, millis, long to serialize dates as Unix epoch time in milliseconds

  • nanos to serialize dates as Unix epoch time in nanoseconds

Added since Jolokia 2.1.0

Default: yyyy-MM-dd’T’HH:mm:ssXXX (ISO 8601 format)

dateFormatTimeZone

A time zone specifier used for date formatters, like UTC
Added since Jolokia 2.1.0

Default: local time zone

mbeanQualifier

Qualifier to add to the ObjectName of Jolokia’s own MBeans. This can become necessary if more than one agent is active within a servlet container. This qualifier is added to the ObjectName of this agent with a comma. For example a mbeanQualifier with the value qualifier=own will result in Jolokia server handler MBean with the name jolokia:type=ServerHandler,qualifier=own

mimeType

MIME to use for the JSON responses. Only application/json and text/plain are allowed. If any other type is given, Jolokia falls back to text/plain.

Default: text/plain

canonicalNaming

This option specifies in which order the key-value properties within ObjectNames as returned by list or search are returned. By default this is the so called 'canonical order' in which the keys are sorted alphabetically. If this option is set to false, then the natural order is used, i.e. the object name as it was registered. This option can be overridden with a query parameter of the same name.

Default: true

includeStackTrace

Whether to include a stacktrace of an exception in case of an error. By default it it set to true in which case the stacktrace is always included. If set to false, no stacktrace is included. If the value is runtime a stacktrace is only included for RuntimeExceptions. This global option can be overridden with a query parameter.

Default: false

serializeException

When this parameter is set to true, then an exception thrown will be serialized as JSON and included in the response under the key error_value. No stacktrace information will be included, though. This global option can be overridden by a query parameter of the same name.

Default: false

allowErrorDetails

If set to false then no error details like a stack trace (when includeStackTrace is set) or a serialized exception (when serializeExceptin is set) are included. This can be user as a startup option to avoid exposure of error details regardless of other options.

Default: true

detectorOptions

Extra options passed to a detector after successful detection of an application server. See below for an explanation.

enabledServices

A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, only the services from this list will be actually used.

disabledServices

A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, all detected services (from /META-INF/jolokia/services(-default)) will be filtered to not include the disabled services.

disableDetectors

A flag that disables usage of org.jolokia.server.core.detector.ServerDetector services alltogether. Can be used when running Jolokia as an agent for standalone Java applicatin (µservices).

false

discoveryEnabled

If set to true then this servlet will listen for multicast request (multicast-group 239.192.48.84, port 24884 by default, but can be changed). By default this option is disabled in order to avoid conflicts with an Jakarta EE standards (though this should’t harm anyways). This option can also be switched on with an environment variable JOLOKIA_DISCOVERY_ENABLED or the system property jolokia.discoveryEnabled set to true.

Default: false

discoveryAgentUrl

Sets the URL to respond for multicast discovery requests. If given, discoveryEnabled is set implicitly to true. This URL can also be provided by an environment variable JOLOKIA_DISCOVERY_AGENT_URL or the system property jolokia.discoveryAgentUrl. Within the value you can use the placeholders ${host} and ${ip} which gets replaced by the autodetected local host name/address. Also with ${env:ENV_VAR} and ${sys:property} environment and system properties can be referenced, respectively.

http://10.9.11.87:8080/jolokia

multicastGroup

The multicast group IPv4 address. This group IP can be also given as an environment variable JOLOKIA_MULTICAST_GROUP or a system property jolokia.multicastGroup

Default: 239.192.48.84

multicastPort

The multicast port. This port can be also given as an environment variable JOLOKIA_MULTICAST_PORT or a system property jolokia.multicastPort

Default: 24884

agentId

A unique ID for this agent. By default a unique id is calculated. If provided it should be ensured that this id is unique among all agent reachable via multicast requests used by the discovery mechanism. It is recommended not to set this value. Within the agentId specification you can use the same placeholders as in discoveryAgentUrl.

my-unique-agent-id

agentDescription

An optional description which can be used for clients to present a human readable label for this agent.

Monitoring agent

Jolokia has various detectors which can detect the brand and version of an application server it is running in. This version is revealed with the version command. With the configuration parameter detectorOptions extra options can be passed to the detectors. These options take the form of a JSON object, where the keys are productnames and the values other JSON objects containing the specific configuration. This configuration is feed to a successful detector which can do some extra initialization on agent startup. Currently the following extra options are supported:

Table 2. Detector Options
Product Option Description

glassfish

bootAmx

If false and the agent is running on GlassFish, this will cause the AMX subsystem not to be booted during startup. By default, AMX which contains all relevant MBeans for monitoring GlassFish is booted.

Security Setup

The WAR agent comes in two flavors:

jolokia-agent-war.war

The standard agent which is secured with the role jolokia. You have to setup your servlet container to connect this role to the authentication.

jolokia-agent-war-unsecured.war

A demo agent, which is completely unsecured. Please use this agent only for evaluation purposes, but it is highly recommended that use the security enabled agent jolokia.war.

Jakarta EE security is enabled by default by adding the required information within the web.xml.

Using jmx4perl’s jolokia tool

jmx4perl comes with a nice command line utility called jolokia which allows for an easy setup of security within a given jolokia.war.

All current client libraries are able to use BASIC HTTP authentication with user and password. The <login-config> should be set accordingly. The <security-constraint> specifies the URL pattern (which is in the default setup specify all resources provided by the Jolokia servlet) and a role name jolokia which is used to find the proper authentication credentials. This role must be referenced outside the agent WAR within the servlet container, e.g. for Tomcat the role definition can be found in $TOMCAT/config/tomcat-users.xml.

Programmatic usage of the Jolokia agent servlet

The Jolokia agent servlet can be integrated into one’s own web applications as well. Simply add a servlet with the servlet class org.jolokia.server.core.http.AgentServlet to your own web.xml. The following example maps the agent to the context /jolokia:

<servlet>
  <servlet-name>jolokia-agent</servlet-name>
  <servlet-class>org.jolokia.server.core.http.AgentServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
  <servlet-name>jolokia-agent</servlet-name>
  <url-pattern>/jolokia/*</url-pattern>
</servlet-mapping>

Of course, any init parameter as described in Table 1, “Servlet init parameters” can be used here as well.

In order for this servlet definition to find the referenced Java class, the JAR jolokia-server-core.jar must be included. Maven users can declare a dependency on this jar artifact:

<project>
  <!-- ....  -->
  <dependencies>
    <dependency>
      <groupId>org.jolokia</groupId>
      <artifactId>jolokia-server-core</artifactId>
      <version>2.1.1</version>
    </dependency>
  </dependencies>
  <!-- .... -->
</project>

The org.jolokia.server.core.http.AgentServlet can be subclassed, too in order to provide a custom restrictor or a custom log handler. See Jolokia Restrictors for details.

Also, multiple Jolokia agents can be deployed in the same JVM without problem. However, since the agent deploys some Jolokia-specific MBeans on the single PlatformMBeansServer, for multi-agent deployments it is important to use the mbeanQualifier init parameter to distinguish multiple Jolokia MBeans by adding an extra property to those MBeans' names. This also needs to be done if multiple webapps containing Jolokia agents are deployed on the same Jakarta EE server.

OSGi Agents

Jolokia agent is also available as OSGi bundle. The Jolokia 1.x OSGi agent had two versions (with and without packaged Felix HTTP Service bundles). In Jolokia 2 there’s only one bundle which requires a OSGi CMPN Whiteboard extender implementation available in target OSGi runtime.

In OSGi world, transition to JakartaEE 9+ (with jakarta.servlet packages) is a bit slower. Jolokia 2 has been tested with dev version of Pax Web 10 using Undertow 2.3, running in dev version of Karaf 4.5.

jolokia-agent-osgi.jar

This bundle depends on availability of OSGi CMPN Whiteboard extender which tracks instances of jakarta.servlet.Servlet OSGi services. Jolokia 2 registers such OSGi servlet service when new registerWhiteboardServlet option is set to true (which is the default).

All package imports of this bundle are listed in Table 3, “Package Imports of jolokia-osgi.jar”. Note that the org.osgi.framework.* and javax.* packages are typically exported by the system bundle, so no extra installation effort is required here. Whether the org.osgi.service.* interfaces are available depends on your OSGi container. If they are not provided, they can be easily fetched and installed from e.g. maven central. Often the LogService interface is exported out of the box, but not the HttpService. You will notice any missing package dependency during the resolve phase while installing jolokia-osgi.jar.

Table 3. Package Imports of jolokia-osgi.jar
Package from System Bundle

javax.management

X

javax.management.openmbean

X

javax.management.relation

X

javax.management.remote

X

javax.naming

X

jakarta.servlet

jakarta.servlet.http

javax.crypto

X

javax.crypto.spec

X

javax.xml.datatype

X

javax.xml.parsers

X

org.osgi.framework

X

org.osgi.service.cm

org.osgi.service.log

org.osgi.service.servlet.context

org.osgi.util.tracker

X

org.w3c.dom

X

org.xml.sax

X

This agent bundle consumes two services by default:

  • org.osgi.service.log.LogService is used for logging, if available. If such a service is not registered, the Jolokia bundle uses the standard HttpServlet.log() method for its logging needs.

  • org.osgi.service.cm.ConfigurationAdmin is used to load configuration from org.jolokia.osgi PID in OSGi environment with Configuration Admin service available.

In Jolokia 1, OSGi CMPN HTTP Service was used to register Jolokia servlet. In Jolokia 2 a different pattern is used. Instead of using some service directly by Jolokia, a servlet is registered as OSGi service which is then processed (_extended) using OSGi CMPN Whiteboard extender

The Jolokia OSGi bundle can be configured via the OSGi Configuration Admin service using the PID org.jolokia.osgi (e.g. if using Apache Karaf, place properties in etc/org.jolokia.osgi.cfg file), or alternatively via global properties which typically can be configured in a configuration file of the OSGi container. All properties start with the prefix org.jolokia and are listed in Table 4, “Jolokia Bundle Properties”. They are mostly the same as the init-param options for a Jolokia servlet when used in a Jakarta EE WAR artifact.

Table 4. Jolokia Bundle Properties
Property Default Description

org.jolokia.user

User used for authentication with HTTP Basic Authentication. If not given, no authentication is used.

org.jolokia.password

Password used for authentication with HTTP Basic Authentication.

org.jolokia.agentContext

/jolokia

Context path of the agent servlet

org.jolokia.agentId

A unique ID for this agent. By default a unique id is calculated. If provided it should be ensured that this id is unique among all agent reachable via multicast requests used by the discovery mechanism. It is recommended not to set this value. Within the agentId specification you can use the same placeholders as in discoveryAgentUrl.

org.jolokia.agentDescription

An optional description which can be used for clients to present a human readable label for this agent.

org.jolokia.debug

false

Debugging state after startup. This can be changed via the Config MBean (jolokia:type=Config) at runtime

org.jolokia.debugMaxEntries

100

Maximum number of entries to keep in the local debug history if switched on. This can be changed via the config MBean at runtime.

org.jolokia.maxDepth

0

Maximum depth when traversing bean properties. If set to 0, depth checking is disabled

org.jolokia.maxCollectionSize

0

Maximum size of collections returned when serializing to JSON. When set to 0, collections are not truncated.

org.jolokia.maxObjects

0

Maximum number of objects which are traversed when serializing a single response. Use this as an airbag to avoid boosting your memory and network traffic. Nevertheless, when set to 0 no limit is imposed.

org.jolokia.serializeLong

number

How to serialize long values in the JSON response: number or string. The default number simply serializes longs as numbers in JSON. If set to string, longs are serialized as strings. It can be useful when a JavaScript client consumes the JSON response, because numbers greater than the max safe integer don’t retain their precision in JavaScript.
Added since Jolokia 2.0.3

org.jolokia.includeRequest

true

A flag (defaults to true) which controls whether the incoming request should be included in the response (under request key).
This applies to bulk requests too, so correlation should be done by index of requests and responses (these are guaranteed to be matching).
Added since Jolokia 2.1.0

org.jolokia.dateFormat

Default: yyyy-MM-dd’T’HH:mm:ssXXX (ISO 8601 format)

A format specifier to use for formatting dates, calendars and instances of java.time.Temporal. Additionally we can use:

  • unix to serialize dates as Unix epoch time in seconds

  • time, millis, long to serialize dates as Unix epoch time in milliseconds

  • nanos to serialize dates as Unix epoch time in nanoseconds

Added since Jolokia 2.1.0

org.jolokia.dateFormatTimeZone

Default: local time zone

A time zone specifier used for date formatters, like UTC
Added since Jolokia 2.1.0

org.jolokia.historyMaxEntries

10

Number of entries to keep in the history. This can be changed at runtime via the Jolokia config MBean.

org.jolokia.registerWhiteboardServlet

true

If true the bundle registers org.jolokia.server.core.osgi.OsgiAgentServlet OSGi service. If false, it’s your responsibility to register this servlet in some way.

org.jolokia.useRestrictorService

false

If true the Jolokia agent will use any org.jolokia.server.core.service.api.Restrictor service for applying access restrictions. If this option is false the standard method of looking up a security policy file is used, as described in Policy based security.

org.jolokia.canonicalNaming

true

This option specifies in which order the key-value properties within ObjectNames as returned by list or search are returned. By default this is the so called canonical order in which the keys are sorted alphabetically. If this option is set to false, then the natural order is used, i.e. the object name as it was registered. This option can be overridden with a query parameter of the same name.

org.jolokia.includeStackTrace

false

Whether to include a stacktrace of an exception in case of an error. By default it it set to false in which case the stacktrace is never included. If the value is runtime a stacktrace is only included for RuntimeExceptions. This global option can be overridden with a query parameter.

org.jolokia.serializeException

false

When this parameter is set to true, then an exception thrown will be serialized as JSON and included in the response under the key error_value. No stacktrace information will be included, though. This global option can be overridden by a query parameter of the same name.

org.jolokia.detectorOptions

An optional JSON representation for application specific options used by detectors for post-initialization steps. See the description of detectorOptions in Servlet init parameters for details.

org.jolokia.enabledServices

A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, only the services from this list will be actually used.

org.jolokia.disabledServices

A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, all detected services (from /META-INF/jolokia/services(-default)) will be filtered to not include the disabled services.

org.jolokia.disableDetectors

false

A flag that disables usage of org.jolokia.server.core.detector.ServerDetector services alltogether.

org.jolokia.discoveryEnabled

false

If set to true then this servlet will listen for multicast request (multicast-group 239.192.48.84, port 24884 by default, but can be configured). By default this option is disabled in order to avoid conflicts with an Jakarta EE standards (though this shouldn’t harm anyways). This option can also be switched on with an environment variable JOLOKIA_DISCOVERY_ENABLED or the system property jolokia.discoveryEnabled set to true.

org.jolokia.discoveryAgentUrl

Sets the URL to respond for multicast discovery requests. If given, discoveryEnabled is set implicitly to true. This URL can also be provided by an environment variable JOLOKIA_DISCOVERY_AGENT_URL or the system property jolokia.discoveryUrl. Within the value you can use the placeholders ${host} and ${ip} which gets replaced by the autodetected local host name/address. Also with $\{env:ENV_VAR} and $\{sys:property} environment and system properties can be referenced, respectively.

org.jolokia.multicastGroup

239.192.48.84

The multicast group IPv4 address. This group IP can be also given as an environment variable JOLOKIA_MULTICAST_GROUP or a system property jolokia.multicastGroup

org.jolokia.multicastPort

24884

The multicast port. This port can be also given as an environment variable JOLOKIA_MULTICAST_PORT or a system property jolokia.multicastPort

org.jolokia.realm

jolokia

Sets the security realm to use. If the authMode is set to jaas this is also used as value for the security domain. E.g. for Karaf 3 and later, this realm should be karaf since all JMX MBeans are guarded by this security domain.

org.jolokia.authMode

basic

Can be either basic (the default), jaas, service-all or service-any. If jaas is used, the user and password which are given in the Authorization: header are used for login in via JAAS and, if successful, the return subject is used for all Jolokia operation. When no user is set and the authMode is either service-all or service-any then a org.jolokia.osgi.security.Authenticator service is looked up in the OSGi service registry. If more then one of such service is registered, service-all requires that all authenticators succeed, for service-any it is sufficient that one authenticator successfully authenticates. In any case if no such Authenticator service can be found, the request is rejected.

This bundle also exports the service jakarta.servlet.ServletContext which can be used to obtain context information of the registered agent like the context path under which this servlet can be reached. Additionally, it exports org.osgi.service.servlet.context.ServletContextHelper, which is used for authentication. Note that this service is only available when the agent servlet is active (i.e. when an whiteboard servlet is registered).

Programmatic servlet registration

It is also possible to register the Jolokia agent servlet manually instead of relying of the OSGi bundle activator which comes with the OSGi agent. jolokia-agent-osgi.jar bundle exports the package org.jolokia.server.core.osgi which includes the servlet class org.jolokia.server.core.osgi.OsgiAgentServlet. This class has three constructors: A default constructor without arguments, one with a single BundleContext argument and finally one with an additional org.jolokia.server.core.service.api.Restrictor (see Jolokia Restrictors for details how access restrictions can be applied). The constructor with a BundleContext as its argument has the advantage that it will use an OSGi LogService if available and adds various OSGi server detectors which adds server information like product name and version to the version command. Refer to Getting the agent version for details about the server information provided.

Please note that for this use case the bundle org.jolokia.agent.osgi should not be started but left in the state resolved. Otherwise, as soon as an OSGi HttpService registers, this bundle will try to add yet another agent servlet to this service, which is probably not what you want. Alternatively, the bundle property org.jolokia.registerWhiteboardServlet can be set to false in which case there will be never an automatic servlet registration.

Restrictor service

As described in Jolokia Restrictors, the Jolokia agent can use custom restrictors implementing the interface org.jolokia.server.core.service.api.Restrictor. If the bundle property org.jolokia.useRestrictorService is set to true and no restrictor is configured by other means, the agent will use one or more OSGi service with org.jolokia.server.core.service.api.Restrictor interface. If no such service is available, access to the agent is always denied. If one such restrictor service is available, the access decision is delegated to this service. When more than one restrictor service is available, access is only granted if all of them individually grant access. A sample restrictor service as a maven project can be found in the Jolokia source at examples/osgi-restrictor.

Here’s an example where this custom restrictor is installed and configured (because by default org.jolokia.useRestrictorService is set to false):

karaf@root()> install -s mvn:org.jolokia/jolokia-example-osgi-restrictor/2.1.1
Register sample restrictor service
Bundle ID: 68

karaf@root()> config:property-set --pid org.jolokia.osgi org.jolokia.useRestrictorService true

karaf@root()> restart org.jolokia.agent.osgi

Then we can only access MBeans from java.lang domain:

$ curl -s http://localhost:8181/jolokia/read/java.lang:type=Runtime/Name | jq .
{
  "request": {
    "mbean": "java.lang:type=Runtime",
    "attribute": "Name",
    "type": "read"
  },
  "value": "[email protected]",
  "status": 200,
  "timestamp": 1702305458
}

$ curl -s http://localhost:8181/jolokia/read/java.nio:type=BufferPool,name=direct/Count | jq .
{
  "request": {
    "mbean": "java.nio:name=direct,type=BufferPool",
    "attribute": "Count",
    "type": "read"
  },
  "error_type": "java.lang.Exception",
  "error": "java.lang.Exception : Reading attribute Count is forbidden for MBean java.nio:name=direct,type=BufferPool",
  "status": 403
}

JVM Agent

The JVM agent is the right agent when it comes to instrument an arbitrary Java application which is not covered by the other agents. This agent can be started by any Java program by providing certain startup options to the JVM. Or it can be dynamically attached (and detached) to an already running Java process. This universal agent uses the JVM Attach API or Java Instrument API and is available for every JVM 1.6 and later.

Dynamic loading of agents will be removed at some point. See JEP 451 for details.

Jolokia as JVM Agent

The JVM agent uses the Java Instrument API for linking into any JVM at startup time. Under the hood it uses an HTTP-Server, which is available on every Oracle/Sun JVM from version 1.6 upwards.

The JDK embedded HTTP-Server is not the fastest one (it is used e.g. for the JAXWS reference implementation), but for our monitoring needs the performance is sufficient. There are several configuration options for tuning the HTTP server’s performance. See below for details.

Installation

This agent gets installed by providing a single startup option -javaagent when starting the Java process.

java -javaagent:/path/to/agent.jar=port=7777,host=localhost

agent.jar is the filename of the Jolokia JVM agent. The agent can be downloaded like the others from the download page. When downloading from a Maven repository you need to check for the classifier javaagent (i.e. the jar to download looks like jolokia-agent-jvm-2.1.1-javaagent.jar, not jolokia-agent-jvm-2.1.1.jar). Options can be appended as a comma separated list. The available options are the same as described in Servlet init parameters plus the one described in table Table 5, “JVM agent configuration options”. If an option contains a comma, an equal sign or a backslash, it must be escaped with a backslash.

Table 5. JVM agent configuration options
Parameter Description Example

agentContext

Context under which the agent is deployed. The full URL will be protocol://host:port/agentContext. The default context is /jolokia.

/j4p

agentId

A unique ID for this agent. By default a unique id is calculated. If provided it should be ensured that this id is unique among all agent reachable via multicast requests used by the discovery mechanism. It is recommended not to set this value. Within the agentId specification you can use the same placeholders as in discoveryAgentUrl.

my-unique-agent-id

agentDescription

An optional description which can be used for clients to present a human readable label for this agent.

Intranet Timebooking Server

host

Hostaddress to which the HTTP server should bind to. If "*" or "0.0.0.0" is given, the servers binds to every network interface.

localhost

port

Port the HTTP server should listen to. If set to 0, then an arbitrary free port will be selected.

8778

user

User to be used for authentication (along with a password)

password

Password used for authentication (user is then required, too)

realm

Sets the security realm to use. If the authMode is set to jaas this is also used as value for the security domain. E.g. for Karaf 3 and later, this realm should be karaf since all JMX MBeans are guarded by this security domain.

jolokia

authMode

Can be either basic (the default), jaas or delegate. If jaas is used, the user and password given in the Authorization: header are used for login in via JAAS and, if successful, the return subject is used for all Jolokia operation. This has only an effect, if user is set. For authentication mode delegate, the authentication decision is delegated to a service specified by authUrl (see below for details).

basic

authMatch

If MultiAuthenticator is used, this config item explains how to combine multiple authenticators. Supported values: any at least one authenticator must match, all all authenticators must match.

any

authClass

Fully qualified name of an authenticator class. Class must be on classpath and must extend com.sun.net.httpserver.Authenticator. Class can declare a constructor that takes one argument of a type org.jolokia.server.core.config.Configuration in which case Jolokia runtime configuration will be passed (useful in cases where authenticator requires additional configuration). If no such constructor is found, default (no-arg) constructor will be use to create an instance.

authUrl

URL of a service used for checking the authentication. This configuration option is only effective if authMode is set to delegate. This URL can have a HTTP or HTTPS scheme. The initially provided Authorization: header is copied over to the request against this URL.

authPrincipalSpec

Expression used for extracting a principal name from the response of a delegate authentication service. This parameter is only in use when the authMode is set to delegate. The following expressions are supported:

json:path

a path into a JSON response which points to the principal. E.g. a principal spec jason:metadata/name will select the "name" property within the JSON object specified by the "metadata" property. For navigate into arrays, numeric indexes can be used.

empty:

Always extracts an empty ("") principal. If this option is not specified, not principal is extracted.

authIgnoreCerts

If given, the authMode is set to delegate and the delegate URL is as HTTPS-URL then the server certificate as well as the server’s DNS name will not be verified. This useful in order to avoid (or introduce) complex keymanagement issues, but is of course less secure. By default certs a verified with the local keystore.

protocol

HTTP protocol to use. Should be either http or https. For the SSL stack there are various additional configuration options.

http

backlog

Size of request backlog before requests get discarded.

10

executor

Threading model of the HTTP server:

fixed

Thread pool with a fixed number of threads (see also threadNr)

cached

Cached thread pool which creates threads on demand

single

A single thread only

single

threadNamePrefix

Thread name prefix that executor will use while creating new thread(s).

jolokia-

threadNr

Number of threads to be used when the fixed execution model is chosen.

5

keystore

Path to the SSL keystore to use (https only)

keystorePassword

Keystore password (https only). If the password is given embedded in brackets [[...]], then it is treated as an encrypted password which was encrypted with java -jar jvm-agent.jar encrypt. See below for details.

useSslClientAuthentication

Whether client certificates should be used for authentication. The presented certificate is validated that it is signed by a known CA which must be in the keystore (https only). (true or false).

false

secureSocketProtocol

Secure protocol that will be used for establishing HTTPS connection (https only)

TLS

keyStoreType

SSL keystore type to use (https only)

JKS

keyManagerAlgorithm

Key manager algorithm (https only)

SunX509

trustManagerAlgorithm

Trust manager algorithm (https only)

SunX509

caCert

If HTTPs is to be used and no keystore is given, then caCert can be used to point to a PEM encoded CA certification file. This is use to verify client certificates when useSslClientAuthentication is switched on (https only)

serverCert

For SSL (and when no keyStore is used) then this path must point to server certificate which is presented to clients (https only)

serverKey

Path to the PEM encoded key file for signing the server cert during TLS handshake. This is only used when no keyStore is used. For decrypting the key the password given with keystorePassword is used (https only).

serverKeyAlgorithm

Encryption algorithm to use for decrypting the key given with serverKey (https only)

RSA

clientPrincipal

The principal which must be given in a client certificate to allow access to the agent. This can be one or or more relative distinguished names (RDN), separated by commas. The subject of a given client certificate must match on all configured RDNs. For example, when the configuration is O=jolokia.org,OU=Dev then a client certificate’s subject must contain O=jolokia.org and OU=Dev to allow the request. Multiple alternative principals can be configured by using additional options with consecutive index suffix like in clientPrincipal.1, clientPrincipal.2, …​ Please remember that a , separating RDNs must be escaped with a backslash (\,) when used on the commandline as agent arguments. (https and useSslAuthentication only)

extraClientCheck

If switched on the agent performs an extra check for client authentication that the presented client cert contains a client flag in the extended key usage section which must be present. (https and useSslAuthentication only)

bootAmx

If set to true and if the agent is attached to a GlassFish server, then during startup the AMX subsystem is booted so that GlassFish specific MBeans are available. Otherwise, if set to false the AMX system is not booted.

true

config

Path to a properties file from where the configuration options should be read. Such a property file can contain the configuration options as described here as key value pairs (except for the config property of course :)

enabledServices

A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, only the services from this list will be actually used.

disabledServices

A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, all detected services (from /META-INF/jolokia/services(-default)) will be filtered to not include the disabled services.

disableDetectors

A flag that disables usage of org.jolokia.server.core.detector.ServerDetector services alltogether. Can be used when running Jolokia as an agent for standalone Java applicatin (µservices).

false

discoveryEnabled

If set to false then this agent will not listen for multicast request (multicast-group 239.192.48.84, port 24884 by default, but can configured individually). By default this option is enabled. This option can also be switched on with an environment variable JOLOKIA_DISCOVERY_ENABLED or the system property jolokia.discoveryEnabled set to true.

Default: false

discoveryAgentUrl

Sets the URL to respond for multicast discovery requests. If given, discoveryEnabled is set implicitly to true. This URL can also be provided by an environment variable JOLOKIA_DISCOVERY_AGENT_URL or the system property jolokia.discoveryUrl. Within the value you can use the placeholders ${host} and ${ip} which gets replaced by the autodetected local host name/address. Also with $\{env:ENV_VAR} and $\{sys:property} environment and system properties can be referenced, respectively.

http://10.9.11.87:8778/jolokia

multicastGroup

The multicast group IPv4 address. This group IP can be also given as an environment variable JOLOKIA_MULTICAST_GROUP or a system property jolokia.multicastGroup

239.192.48.84

multicastPort

The multicast port. This port can be also given as an environment variable JOLOKIA_MULTICAST_PORT or a system property jolokia.multicastPort

24884

sslProtocol

The list of SSL / TLS protocols enabled. Valid options are available in the documentation on SunJSSEProvider for your JDK version. Using only TLSv1.1 and TLSv1.2 is recommended in Java 1.7 and Java 1.8. Using only TLSv1 is recommended in Java 1.6. Multiple protocols can be configured by using additional options with consecutive index suffixes like in sslProtocol.1, sslProtocol.2, …​

TLSv1.2

sslCipherSuite

The list of SSL / TLS cipher suites to enable. The table of available cipher suites is available under the "Default Enabled Cipher Suites" at the SunJSSEProvider documentation here. Multiple cipher suites can be configured by using additional options with consecutive index suffixes like in sslCipherSuite.1, sslCipherSuite.2, …​

maxDepth

Maximum depth when traversing bean properties. If set to 0, depth checking is disabled

Default: 15

maxCollectionSize

Maximum size of collections returned when serializing to JSON. When set to 0, collections are never truncated.

Default: 0

maxObjects

Maximum number of objects which are traversed when serializing a single response. Use this as an airbag to avoid boosting your memory and network traffic. Nevertheless, when set to 0 no limit is imposed.

Default: 0

serializeLong

How to serialize long values in the JSON response: number or string. The default number simply serializes longs as numbers in JSON. If set to string, longs are serialized as strings. It can be useful when a JavaScript client consumes the JSON response, because numbers greater than the max safe integer don’t retain their precision in JavaScript.
Added since Jolokia 2.0.3

Default: number

includeRequest

A flag (defaults to true) which controls whether the incoming request should be included in the response (under request key).
This applies to bulk requests too, so correlation should be done by index of requests and responses (these are guaranteed to be matching).
Added since Jolokia 2.1.0

Default: true

dateFormat

A format specifier to use for formatting dates, calendars and instances of java.time.Temporal. Additionally we can use:

  • unix to serialize dates as Unix epoch time in seconds

  • time, millis, long to serialize dates as Unix epoch time in milliseconds

  • nanos to serialize dates as Unix epoch time in nanoseconds

Added since Jolokia 2.1.0

Default: yyyy-MM-dd’T’HH:mm:ssXXX (ISO 8601 format)

dateFormatTimeZone

A time zone specifier used for date formatters, like UTC
Added since Jolokia 2.1.0

Default: local time zone

policyLocation

Path to the XML policy file

Upon successful startup the agent will print out a success message with the full URL which can be used by clients for contacting the agent.

Attaching a Jolokia agent on the fly

Dynamic loading of agents will be removed at some point. See JEP 451 for details.

A Jolokia agent can be attached to any running Java process as long as the user has sufficient access privileges for accessing the process. This agent uses the JVM Attach API for dynamically attaching and detaching to and from the process. It works similar to JConsole or jcmd command connecting to a local process. The Jolokia advantage is, that after the start of the agent, it can be reached over the network.

The JAR containing the JVM agent also contains a client application which can be reached via the -jar option. Call it with --help to get a short usage information:

$ java -jar jolokia-agent-jvm-2.1.1-javaagent.jar --help

Jolokia Agent Launcher
======================

Usage: java -jar jolokia-agent-jvm-2.1.1-javaagent.jar [options] <command> <pid/regexp>

where <command> is one of
    start     -- Start a Jolokia agent for the process specified
    stop      -- Stop a Jolokia agent for the process specified
    status    -- Show status of an (potentially) attached agent
    toggle    -- Toggle between start/stop (default when no command is given)
    list      -- List all attachable Java processes (default when no argument is given at all)
    encrypt   -- Encrypt a password which is given as argument or read from standard input

[options] are used for providing runtime information for attaching the agent:

    --host <host>                   Hostname or IP address to which to bind on
                                    (default: InetAddress.getLocalHost())
    --port <port>                   Port to listen on (default: 8778)
    --agentContext <context>        HTTP Context under which the agent is reachable (default: /jolokia)
    --agentId <agent-id>            VM unique identifier used by this agent (default: autogenerated)
    --agentDescription <desc>       Agent description
    --authMode <mode>               Authentication mode: 'basic' (default), 'jaas' or 'delegate'
    --authMatch <match>             If MultiAuthenticator is used, this config item explains how to combine multiple authenticators
                                     "any" -- at least one authenticator must match (default)
                                     "all" -- all authenticators must match
    --authClass <class>             Classname of an custom Authenticator which must be loadable from the classpath
    --authUrl <url>                 URL used for a dispatcher authentication (authMode == delegate)
    --authPrincipalSpec <spec>      Extractor specification for getting the principal (authMode == delegate)
    --authIgnoreCerts               Whether to ignore CERTS when doing a dispatching authentication (authMode == delegate)
    --user <user>                   User used for Basic-Authentication
    --password <password>           Password used for Basic-Authentication
    --quiet                         No output. "status" will exit with code 0 if the agent is running, 1 otherwise
    --verbose                       Verbose output
    --executor <executor>           Executor policy for HTTP Threads to use (default: single)
                                     "fixed"  -- Thread pool with a fixed number of threads (default: 5)
                                     "cached" -- Cached Thread Pool, creates threads on demand
                                     "single" -- Single Thread
    --threadNamePrefix <prefix>     Thread name prefix that executor will use while creating new thread(s)
                                    (default: jolokia-)
    --threadNr <nr threads>         Number of fixed threads if "fixed" is used as executor
    --backlog <backlog>             How many request to keep in the backlog (default: 10)
    --protocol <http|https>         Protocol which must be either "http" or "https" (default: http)
    --keystore <keystore>           Path to keystore (https only)
    --keystorePassword <pwd>        Password to the keystore (https only)
    --useSslClientAuthentication    Use client certificate authentication (https only)
    --secureSocketProtocol <name>   Secure protocol (https only, default: TLS)
    --keyStoreType <name>           Keystore type (https only, default: JKS)
    --keyManagerAlgorithm <name>    Key manager algorithm (https only, default: SunX509)
    --trustManagerAlgorithm <name>  Trust manager algorithm (https only, default: SunX509)
    --caCert <path>                 Path to a PEM encoded CA cert file (https & sslClientAuth only)
    --serverCert <path>             Path to a PEM encoded server cert file (https only)
    --serverKey <path>              Path to a PEM encoded server key file (https only)
    --serverKeyAlgorithm <algo>     Algorithm to use for decrypting the server key (https only, default: RSA)
    --clientPrincipal <principal>   Allow only this principal in the client cert (https & sslClientAuth only)
                                    If supplied multiple times, any one of the clientPrincipals must match
    --extendedClientCheck <t|f>     Additional validation of client certs for the proper key usage (https & sslClientAuth only)
    --disableDetectors              Whether to run detectors that locate environment-specific MBeanServer instances
    --enabledServices               A comma-separated list of fully-qualified class names.
                                    If this configuration option is specified and is not empty, only the
                                    services from this list will be actually used.
    --disabledServices              A comma-separated list of fully-qualified class names.
                                    If this configuration option is specified and is not empty, all detected
                                    services (from `/META-INF/jolokia/services(-default)`) will be filtered
                                    to not include the disabled services.
    --discoveryEnabled <t|f>        Enable/Disable discovery multicast responses (default: false)
    --discoveryAgentUrl <url>       The URL to use for answering discovery requests. Will be autodetected if not given.
    --sslProtocol <protocol>        SSL / TLS protocol to enable, can be provided multiple times
    --sslCipherSuite <suite>        SSL / TLS cipher suite to enable, can be provided multiple times
    --debug                         Switch on agent debugging
    --logHandlerClass <class>       Implementation of org.jolokia.server.core.service.api.LogHandler for logging
                                    Available classes: org.jolokia.server.core.service.impl.QuietLogHandler
                                                       org.jolokia.server.core.service.impl.JulLogHandler
    --logHandlerName <logger name>  A logger name to be used with custom logger implementation
    --debugMaxEntries <nr>          Number of debug entries to keep in memory which can be fetched from the Jolokia MBean
    --maxDepth <depth>              Maximum number of levels for serialization of beans
    --maxCollectionSize <size>      Maximum number of element in collections to keep when serializing the response
    --maxObjects <nr>               Maximum number of objects to consider for serialization
    --restrictorClass <class>       Classname of an custom restrictor which must be loadable from the classpath
    --policyLocation <url>          Location of a Jolokia policy file
    --mbeanQualifier <qualifier>    Qualifier to use when registering Jolokia internal MBeans
    --canonicalNaming <t|f>         whether to use canonicalName for ObjectNames in 'list' or 'search' (default: true)
    --includeStackTrace <t|f>       whether to include StackTraces for error messages (default: false)
    --serializeException <t|f>      whether to add a serialized version of the exception in the Jolokia response (default: false)
    --includeRequest <t|f>          whether to include entire request in the response (default: true)
    --dateFormat <format>           DateFormat to use for serializing dates/times/calendars/temporals (default: yyyy-MM-dd'T'HH:mm:ssXXX)
    --dateFormatTimeZone <tz>       TimeZone to use for formatting dates/times/calendars/temporals (default: local time zone)
    --config <configfile>           Path to a property file from where to read the configuration
    --help                          This help documentation
    --version                       Version of this agent (it's 2.1.1 btw :)

<pid/regexp> can be either a numeric process id or a regular expression. A regular expression is matched
against the processes' names (ignoring case) and must be specific enough to select exactly one process.

If no <command> is given but only a <pid> the state of the Agent will be toggled
between "start" and "stop"

If neither <command> nor <pid> is given, a list of Java processes along with their IDs
is printed

There are several possible reasons, why attaching to a process can fail:
   * The UID of this launcher must be the very *same* as the process to attach to. It's not sufficient to be root.
   * The JVM must have HotSpot enabled and be a JVM 1.6 or later.
   * It must be a Java process ;-)

For more documentation please visit www.jolokia.org

Every option described in Table 5, “JVM agent configuration options” is reflected by a command line option for the launcher. Additionally, the option --quiet can be used to keep the launcher silent and --verbose for adding some extra logging.

The launcher knows various operational modes, which needs to be provided as a non-option argument and possibly require an extra argument.

start

Use this to attach an agent to an already running, local Java process. The additional argument is either the process id of the Java process to attach to or a regular expression which is matched against the Java processes names. In the later case, exactly one process must match, otherwise an exception is raised. The command will return with an return code of 0 if an agent has been started. If the agent is already running, nothing happens and the launcher returns with 1. The URL of the Agent will be printed to standard out on an extra line except when the --quiet option is used.

stop

Command for stopping an running and dynamically attached agent. The required argument is the Java process id or an regular expression as described for the start command. If the agent could be stopped, the launcher exits with 0, it exits with 1 if there was no agent running.

toggle

Starts or stops an dynamically attached agent, depending on its current state. The Java process ID is required as an additional argument. If an agent is running, toggle will stop it (and vice versa). The launcher returns with an exit code of 0 except when the operation fails. When the agent is started, the full agent’s URL is printed to standard out. toggle is the default command when only a numeric process id is given as argument or a regular expression which not the same as a known command.

status

Command for showing the current agent status for a given process. The process id or a regular expression is required. The launcher will return with 0 when the agent is running, otherwise with 1.

list

List all local Java processes in a table with the process id and the description as columns. This is the default command if no non-option argument is given at all. list returns with 0 upon normal operation and with 1 otherwise.

encrypt

Encrypt the keystore password. You can add the password to encrypt as an additional argument or, if not given, it is read from standard input. The output of this command is the encrypted password in the format [[....]], which should be used literally (excluding the final newline) for the keystore password when using the option keystorePassword in the agent configuration.

The launcher is especially suited for one-shot, local queries. For example, a simple shell script for printing out the memory usage of a local Java process, including (temporarily) attaching an Jolokia agent looks simply like in the following example. With a complete client library like jmx4perl even more one shot scripts are possible [4].

#!/bin/sh

url=`java -jar jolokia-agent-jvm-2.1.1-javaagent.jar start $1 | tail -1`

memory_url="${url}read/java.lang:type=Memory/HeapMemoryUsage"
used=`curl -s "${memory_url}/used" | jq .value`
max=`curl -s "${memory_url}/max" | jq .value`
usage=$((${used}*100/${max}))
echo "Memory Usage: $usage %"

java -jar jolokia-agent-jvm-2.1.1-javaagent.jar --quiet stop $1

1. Although the proxy mode is available for all three agents, you are normally free to setup the proxy environment. The recommendation here is the WAR agent for which very lightweight servlet container exists. Tomcat, Jetty or Undertow are all a perfect choice for a Jolokia proxy server.
2. Of course, there is much more to OSGi, a platform and programing model which I really like. This is my personal pet agent, so to speak ;-).
3. You could even instrument a Jakarta EE application server this way, however this is not recommended because WAR agent is much more suitable.
4. And in fact, some support for launching this dynamic agent is planned for a forthcoming release of jmx4perl.
This page was built using the Antora default UI. The source code for this UI is licensed under the terms of the MPL-2.0 license. | Copyright © 2010 - 2023 Roland Huß