Skip to main content
Next

Java Agent

The Java agent runs inside the target JVM. It is the recommended deployment mode for most users.

Artifact​

Download jmx_prometheus_javaagent-1.7.0.jar from the 1.7.0 release.

Argument formats​

The Java agent parses one agent argument string:

FormatBehavior
<PORT>:<EXPORTER_YAML>Enable HTTP on 0.0.0.0:<PORT>.
<HOST>:<PORT>:<EXPORTER_YAML>Enable HTTP on the specified host and port.
<EXPORTER_YAML>Do not start HTTP; useful for OpenTelemetry-only configuration.

Ports must be from 1 through 65535. IPv6 hosts must be enclosed in brackets, for example [::1]:9404:exporter.yaml.

HTTP mode example​

java -javaagent:jmx_prometheus_javaagent-1.7.0.jar=9404:exporter.yaml -jar your-application.jar
rules:
- pattern: ".*"

Metrics are available at http://localhost:9404/metrics.

OpenTelemetry-only example​

java -javaagent:jmx_prometheus_javaagent-1.7.0.jar=exporter.yaml -jar your-application.jar
openTelemetry:
  endpoint: http://localhost:4317
rules:
- pattern: ".*"

Combined mode example​

java -javaagent:jmx_prometheus_javaagent-1.7.0.jar=9404:exporter.yaml -jar your-application.jar
openTelemetry:
  endpoint: http://localhost:4317
rules:
- pattern: ".*"

Lifecycle and errors​

The agent starts through premain at JVM startup or agentmain when attached. Startup registers the JMX collector and starts the enabled exporters. Malformed arguments, invalid ports, unreadable YAML, or invalid configuration fail startup.

Logging backend​

The Java agent uses Java Util Logging (JUL) by default to preserve existing logging behavior. To avoid initializing or configuring the application's JUL system during startup, use the JUL-independent native logging backend. Native logging writes INFO, WARN, and ERROR messages to standard error.

To use native logging, set either:

-Djmx.prometheus.exporter.logging.backend=native

or JMX_PROMETHEUS_EXPORTER_LOGGING_BACKEND=native.

Supported values are native and jul. The system property takes precedence over the environment variable. The selected backend is fixed when each logger is first created. JUL is process-wide, so selecting it may initialize the application's configured LogManager during Java agent startup.