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.
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.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.
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
.
Package | from System Bundle |
---|---|
|
X |
|
X |
|
X |
|
X |
|
X |
|
|
|
|
|
X |
|
X |
|
X |
|
X |
|
X |
|
|
|
|
|
|
|
X |
|
X |
|
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 standardHttpServlet.log()
method for its logging needs. -
org.osgi.service.cm.ConfigurationAdmin
is used to load configuration fromorg.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.
Property | Default | Description |
---|---|---|
|
User used for authentication with HTTP Basic Authentication. If not given, no authentication is used. |
|
|
Password used for authentication with HTTP Basic Authentication. |
|
|
|
Context path of the agent servlet |
|
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. |
|
|
|
Debugging state after startup. This can be changed via the
Config MBean ( |
|
|
Maximum number of entries to keep in the local debug history if switched on. This can be changed via the config MBean at runtime. |
|
|
Maximum depth when traversing bean properties. If set to 0, depth checking is disabled |
|
|
Maximum size of collections returned when serializing to JSON. When set to 0, collections are not truncated. |
|
|
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. |
|
|
How to serialize long values in the JSON response: |
|
|
A flag (defaults to |
|
Default: |
A format specifier to use for formatting dates, calendars and instances of
Added since Jolokia 2.1.0 |
|
Default: local time zone |
A time zone specifier used for date formatters, like |
|
|
Number of entries to keep in the history. This can be changed at runtime via the Jolokia config MBean. |
|
|
If |
|
|
If |
|
|
This option specifies in which order the key-value
properties within ObjectNames as returned by
|
|
|
Whether to include a stacktrace of an exception in case of
an error. By default it it set to |
|
|
When this parameter is set to |
|
An optional JSON representation for application specific
options used by detectors for post-initialization steps. See the description of
|
|
|
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 |
|
|
false |
A flag that disables usage of |
|
|
If set to |
|
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 |
|
|
The multicast port. This port can be also given as an environment variable |
|
|
Sets the security realm to use. If the |
|
|
Can be either |
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.
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.
Parameter | Description | Example |
---|---|---|
|
Context under which the agent is deployed. The full URL
will be |
|
|
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. |
|
|
Hostaddress to which the HTTP server should bind to. If "*" or "0.0.0.0" is given, the servers binds to every network interface. |
|
|
Port the HTTP server should listen to. If set to 0, then an arbitrary free port will be selected. |
|
|
User to be used for authentication (along with a |
|
|
Password used for authentication ( |
|
|
Sets the security realm to use. If the |
|
|
Can be either |
|
|
If MultiAuthenticator is used, this config item explains how to combine multiple authenticators.
Supported values: |
|
|
Fully qualified name of an authenticator class. Class must be on classpath and must extend
|
|
|
URL of a service used for checking the authentication. This configuration option is only effective if
|
|
|
Expression used for extracting a principal name from the response of a delegate authentication service. This
parameter is only in use when the
|
|
|
If given, the |
|
|
HTTP protocol to use. Should be either |
|
|
Size of request backlog before requests get discarded. |
|
|
Threading model of the HTTP server:
|
|
|
Thread name prefix that executor will use while creating new thread(s). |
|
|
Number of threads to be used when the
|
|
|
Path to the SSL keystore to use (https only) |
|
|
Keystore password (https only). If the password is given embedded in brackets |
|
|
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). ( |
|
|
Secure protocol that will be used for establishing HTTPS connection (https only) |
|
|
SSL keystore type to use (https only) |
|
|
Key manager algorithm (https only) |
|
|
Trust manager algorithm (https only) |
|
|
If HTTPs is to be used and no |
|
|
For SSL (and when no |
|
|
Path to the PEM encoded key file for signing the server cert during TLS handshake. This is only
used when no |
|
|
Encryption algorithm to use for decrypting the key given with |
|
|
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 |
|
|
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) |
|
|
If set to |
|
|
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 |
|
|
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 |
|
|
The multicast port. This port can be also given as an environment variable |
|
|
The list of SSL / TLS protocols enabled. Valid options are available in the documentation
on SunJSSEProvider for your JDK version. Using only |
|
|
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 |
|
|
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 |
|
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 optionkeystorePassword
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