JVM Agent

Another variant is Jolokia’s JVM agent which does not need any special container environment. The only dependency is on Oracle’s JDK 11 or later as runtime, since it contains a lightweight HTTP Server used for exposing the Jolokia protocol. This agent is the most generic one which can instrument any Java application using a JDK11+. It is suitable for situations where the other agents don’t fit. Also, it can be used for dynamically attaching an agent to a running Java process (this option however is going to be removed after JDK 21).

For using this agent, the following argument to the Java application to instrument has to be given:

$ java ... -javaagent:/path/to/jolokia-agent-jvm-2.4.1-javaagent.jar

By default, the agent will listen on port 8778, but this can be configured as well as other aspects like authentication:

  • Provide options on the commandline as key-value pairs:

    $ java ... -javaagent:jolokia-agent-jvm-2.4.1-javaagent.jar=port=7777,host=localhost

  • Via a properties file

    $ java ... -javaagent:jolokia-agent-jvm-2.4.1-javaagent.jar=config=/path/to/config.properties

  • Via packaging a jolokia-agent.properties top level in the agent.jar

Options are used in the given precedence, the former overwriting the later values.

Additionally if options are not specified, Jolokia uses several property sources:

  • default values stored in code

  • values stored in default-jolokia-agent.properties resource file in JVM Agent JAR

  • environment variables prefixed with JOLOKIA_. So for example agentId option can be specified using JOLOKIA_AGENT_ID environment variable

  • system properties prefixed with jolokia. So for example host option can be specified using -Djolokia.host option for java invocation.

For attaching the agent dynamically to a running Java process, the following command can be used to get a quick help

$ java -jar /path/to/jolokia-agent-jvm-2.4.1-javaagent.jar --help
Note
 Dynamic loading of agents will be removed at some point. See JEP 451 for details.

For more details and usage examples please refer to the reference manual.