Agents

Various agents are available for providing Jolokia services in different environments:

  • WAR Agent for deployment as web application in a Jakarta EE Server.

  • OSGi Agent for deployment in an OSGi container. This agent is packaged as a bundle and requires an OSGi CMPN Whiteboard Specification for Jakarta™ Servlet extender.

  • JVM Agent which can be used with any Oracle/Sun based JVM, Version 11 or later.

WAR Agent

Note
 Jolokia 2.0 uses Jakarta EE 9+ (Servlet API 5+ with jakarta.servlet.* packages), while Jolokia 1.x uses JavaEE/JakartaEE up to version 8 (Servlet API up to version 4 with javax.servlet.* packages)

The WAR agent jolokia-agent-war.war deploys as a regular web archive (WAR) in a Jakarta EE server. Deployment is simple (often only a copy in a certain directory) and the agent can be tuned like a normal web application. Setting it up the agent servlet for secure communication is a well known business (but specific to every application server) and the same as for any other web archive.

jolokia-agent-war-unsecured.war is a flavor of WAR agent without <security-constraint> elements declared in its WEB-INF/web.xml.

Also, this is the agent for the proxy mode where it is deployed in a simple, dedicated application server like Tomcat or Jetty.

This is the most widely used agent. Read more about the WAR agent and its installation.

The WAR agent for Jolokia 1.x has been tested to work on:

  • JBoss 4.2.3, 5.1.0, 6.1.0, 7.0.2, 7.1.1, 8.0.0

  • Oracle WebLogic 9.2.3.0, 10.0.2.0, 10.3.6.0

  • Glassfish 2.1.1, 3.0.1, 3.1.2, 4.0.0

  • IBM Websphere 6.1.0.33, 7.0.0.11, 8.0.0.1, 8.5

  • Apache Tomcat 5.5.35, 6.0.37, 7.0.52, 8.0.3

  • Jetty 5.1.15, 6.1.26, 7.6.9, 8.1.9, 9.1.2

  • Resin 3.1.9

  • Jonas 4.10.7, 5.1.1, 5.2.1

  • Apache Geronimo 2.1.6, 2.2.1, 3.0.0

  • Spring dm Server 2.0.0.RELEASE

  • Eclipse Virgo 2.1.0

The WAR agent for Jolokia 2.0 has been (as of December 2023) tested with:

  • Apache Tomcat 10.1.16

  • Eclipse Jetty 11.0.18

  • WildFly 30.0.1.Final

  • Openliberty 23.0.0.11

Note
 One of the initial goals of docker-maven-plugin was to test Jolokia with different application servers!

OSGi Agent

For an OSGi environment an agent packaged as an OSGi bundle is provided.

In Jolokia 1.x there were two flavors of the bundle:

  • minimal bundle jolokia-osgi.jar, including only the agent itself, which requires an already installed OSGi HTTP service implementation, for example Pax-Web HTTP Service.

  • jolokia-osgi-bundle.jar is an all-in-one bundle, including the Felix HTTP Service implementation. This bundle is useful for quick installations, where no HTTP Service is available. However, for best fitting the OSGi philosophy, the usage of the minimal bundle is recommended.

In Jolokia 2, there’s only single jolokia-agent-osgi.jar and it’s no longer using OSGi CMPN HTTP Service. Instead, OSGi CMPN Whiteboard Specification for Jakarta™ Servlet is used and Jolokia registers its org.jolokia.server.core.osgi.OsgiAgentServlet as Whiteboard service. This approach requires existing OSGi CMPN Whiteboard Specification for Jakarta™ Servlet implementation.

The OSGi agent for Jolokia 1.x has been tested with the following containers:

  • Felix 2.0.5, 3.0.8, 3.2.2, 4.2.1

  • Equinox 3.5.2, 3.6.1, 3.7.1, 3.8.1

  • Karaf 2.3.0

  • Virgo 2.1.0, 3.0.1

  • Knopflerfish 3.2.0

The OSGi agent for Jolokia 2.0 has been (as of December 2023) tested with:

  • Karaf 4.5.0 with Pax Web 10 (dev)

Read more about the OSGi agent and its installation.

JVM Agent

Since Java™ 5 it is possible to start so called JVM agents in advance before starting a Java™ application. This technique is used e.g. by profiling tools for installing global classloaders in order to instrument classes. Additionally, Java™ 6 JVM (and later) comes with a simple embedded HTTP-Server which is used e.g. for exposing web services with the default JAXWS implementation coming with Java™ 6.

This Jolokia agent uses the agent API and the com.sun.net.httpserver.HttpServer to allow instrumenting any Java™ application running with a Java™ 6 VM, not only application servers.

There are two ways to install a JVM agent in Java application.

First is to use -javaagent command line option like this:

$ java -cp target/classes:... -javaagent:\
jolokia-agent-jvm-2.2.9-javaagent.jar=port=7778 \
com.example.Main

Second one is to use JVM Attach API and install an agent within running JVM process. jolokia-agent-jvm-2.2.9-javaagent.jar is a JAR with main class that uses this API, so we can invoke this JAR with start <pid> command:

$ java -jar jolokia-agent-jvm-2.2.9-javaagent.jar start --port 7778 34870
Started Jolokia for PID 34870
http://127.0.0.1:7778/jolokia/
Note
 Dynamic loading of agents will be removed at some point. See JEP 451 for details.

When dynamically loading a JVM agent using JDK 21 and newer, we’ll get this warning:

WARNING: A Java agent has been loaded dynamically (jolokia-agent-jvm-2.2.9-javaagent.jar)
WARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading
         to hide this warning
WARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage
         for more information
WARNING: Dynamic loading of agents will be disallowed by default in a future release

That’s why the preferred method is to use -javaagent JVM option.

The JVM Agent for Jolokia 1.x has been tested with:

  • Camel 2.8.1

  • ActiveMQ 5.5.0

  • Hadoop 0.20.2

  • Terracotta 3.2.1

  • HornetQ 2.2.14

The JVM Agent for Jolokia 2.x has been (as of December 2023) tested with:

  • Camel 4.1.0

  • ActiveMQ 6.0.1

  • ActiveMQ Artemis 2.31.2

Read more about the JVM agent and its installation.