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.
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 inWEB-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 internalweb.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.
Parameter | Description | Example |
---|---|---|
|
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 |
|
|
Location of the policy file to use. This is either a URL
which can read from (like a |
|
|
Full classname of an implementation of |
|
|
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 |
Default: |
|
Debugging state after startup. Can be changed via the config MBean during runtime. |
Default: |
|
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
|
Default: |
|
A parameter which may be used to configure logger name which may be used with some |
Default: |
|
Entries to keep in the history. Can be changed at runtime via the config MBean. |
Default: |
|
Maximum number of entries to keep in the local debug history (if enabled). Can be changed via the config MBean at runtime. |
Default: |
|
Maximum depth when traversing bean properties. If set to 0, depth checking is disabled |
Default: |
|
Maximum size of collections returned when serializing to JSON. When set to 0, collections are never truncated. |
Default: |
|
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: |
|
How to serialize long values in the JSON response: |
Default: |
|
A flag (defaults to |
Default: |
|
A format specifier to use for formatting dates, calendars and instances of
Added since Jolokia 2.1.0 |
Default: |
|
A time zone specifier used for date formatters, like |
Default: local time zone |
|
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 |
|
|
MIME to use for the JSON responses. Only |
Default: |
|
This option specifies in which order the key-value
properties within ObjectNames as returned by
|
Default: |
|
Whether to include a stacktrace of an exception in case of
an error. By default it it set to |
Default: |
|
When this parameter is set to |
Default: |
|
If set to |
Default: |
|
Extra options passed to a detector after successful detection of an application server. See below for an explanation. |
|
|
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. |
|
|
A comma-separated list of fully-qualified class names. If this configuration option is specified and is not empty, all detected services (from |
|
|
A flag that disables usage of |
false |
|
If set to |
Default: |
|
Sets the URL to respond for multicast discovery requests. If
given, |
|
|
The multicast group IPv4 address. This group IP can be also given as an environment variable |
Default: |
|
The multicast port. This port can be also given as an environment variable |
Default: |
|
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 |
|
|
An optional description which can be used for clients to present a human readable label for this 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:
Product | Option | Description |
---|---|---|
glassfish |
bootAmx |
If |
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
.
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.2</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.