Collect JMX Metrics with OpenTelemetry

This guide shows you how to collect JMX (Java Management Extensions) metrics from any Java application using the OpenTelemetry Collector's JMX receiver. This approach works with any JVM-based application including Kafka, Cassandra, Tomcat, and custom Java services.

Most steps are identical. To adapt this guide, update the endpoint and remove the ingestion key header as shown in Cloud → Self-Hosted.

Prerequisites

A Java application compatible with OpenTelemetry Java and JMX enabled
A SigNoz Cloud account or self-hosted SigNoz instance
OpenTelemetry Collector configured to send data to SigNoz

Step 1. Enable JMX on your Java application

Configure your Java application to expose JMX metrics by adding these JVM arguments:

java \
  -Dcom.sun.management.jmxremote \
  -Dcom.sun.management.jmxremote.port=<jmx-port> \
  -Dcom.sun.management.jmxremote.rmi.port=<jmx-port> \
  -Dcom.sun.management.jmxremote.ssl=false \
  -Dcom.sun.management.jmxremote.authenticate=false \
  -jar your-application.jar

Replace <jmx-port> with your chosen port (e.g., 9999).

The example above disables SSL and authentication for simplicity. For production environments, enable authentication and SSL. See the JMX security documentation for details.

For environment variable configuration:

export JAVA_OPTS="-Dcom.sun.management.jmxremote \
  -Dcom.sun.management.jmxremote.port=9999 \
  -Dcom.sun.management.jmxremote.rmi.port=9999 \
  -Dcom.sun.management.jmxremote.ssl=false \
  -Dcom.sun.management.jmxremote.authenticate=false"

Step 2. Download the JMX metrics JAR

The OTel Collector JMX receiver requires the JMX Metric Gatherer JAR file. Download it from Maven Central.

The JMX receiver validates the JAR file hash. The JAR version must be compatible with your OTel Collector version. For example, Collector v0.144.0 requires JAR version 1.52.0-alpha or earlier supported versions. If you see "jar hash does not match known versions" error, download a JAR version that matches your collector.

For example, to download version 1.52.0-alpha:

curl -sLO https://repo1.maven.org/maven2/io/opentelemetry/contrib/opentelemetry-jmx-scraper/1.52.0-alpha/opentelemetry-jmx-scraper-1.52.0-alpha.jar

Place the JAR in a location accessible to the OTel Collector (e.g., /opt/opentelemetry-jmx-scraper.jar).

Step 3. Configure the OTel Collector JMX receiver

Add the JMX receiver to your otel-collector-config.yaml. Append the following to your existing receivers section:

otel-collector-config.yaml

receivers:
  jmx:
    jar_path: /opt/opentelemetry-java-contrib-jmx-metrics.jar
    endpoint: <app-host>:<jmx-port>
    target_system: jvm

Replace:

<app-host>: Hostname or IP of your Java application
<jmx-port>: The JMX port configured in Step 1 (e.g., 9999)

Supported target systems

The target_system parameter determines which pre-built metric definitions to use. Choose based on your application:

Target System	Description
`jvm`	Generic JVM metrics (memory, threads, GC)
`activemq`	Apache ActiveMQ broker metrics
`cassandra`	Apache Cassandra database metrics
`hbase`	Apache HBase metrics
`hadoop`	Apache Hadoop metrics
`jetty`	Eclipse Jetty server metrics
`kafka`	Apache Kafka broker metrics
`kafka-consumer`	Kafka consumer metrics
`kafka-producer`	Kafka producer metrics
`solr`	Apache Solr search metrics
`tomcat`	Apache Tomcat server metrics
`wildfly`	WildFly/JBoss application server metrics

You can specify multiple systems as a comma-separated list:

target_system: jvm,tomcat,kafka

Optional authentication

If your JMX endpoint requires authentication:

otel-collector-config.yaml

receivers:
  jmx:
    jar_path: /opt/opentelemetry-java-contrib-jmx-metrics.jar
    endpoint: <app-host>:<jmx-port>
    target_system: jvm
    username: <jmx-username>
    password: <jmx-password>

Step 4. Enable the JMX receiver in your pipeline

Add the JMX receiver to your metrics pipeline:

otel-collector-config.yaml

service:
  pipelines:
    metrics/jmx:
      receivers: [jmx]
      processors: [resourcedetection, batch]
      exporters: [otlp]

Using a separate pipeline (metrics/jmx) keeps JMX metrics isolated. You can also add jmx to an existing metrics pipeline if preferred.

Restart the OTel Collector to apply changes:

# For Docker deployments
docker compose restart otel-collector

# For Kubernetes deployments
kubectl rollout restart deployment otel-collector

Validate

Check OTel Collector logs to confirm successful JMX connection:
```
docker logs otel-collector 2>&1 | grep -i jmx
```
Open SigNoz and go to Metrics → Query Builder
Search for metrics starting with jvm_ (e.g., jvm_memory_used, jvm_threads_current)
Verify metrics are being received from your application

Example: Complete configuration

Here's a complete example for monitoring a Kafka broker:

otel-collector-config.yaml

receivers:
  jmx/kafka:
    jar_path: /opt/opentelemetry-java-contrib-jmx-metrics.jar
    endpoint: kafka-broker:9999
    target_system: kafka,jvm
    collection_interval: 10s

processors:
  batch:
    timeout: 10s
  resourcedetection:
    detectors: [env, system]

exporters:
  otlp:
    endpoint: https://ingest.<region>.signoz.cloud:443
    headers:
      signoz-ingestion-key: <your-ingestion-key>

service:
  pipelines:
    metrics/kafka:
      receivers: [jmx/kafka]
      processors: [resourcedetection, batch]
      exporters: [otlp]

Replace <region> and <your-ingestion-key> with your SigNoz Cloud values.

Troubleshooting

"Connection refused" when connecting to JMX?

Verify the Java application is running with JMX enabled
Check that the JMX port is correct and accessible
Ensure no firewall is blocking the connection
For Docker: ensure the container exposes the JMX port

"Failed to load JAR" error?

Verify the jar_path points to the correct location
Check file permissions on the JAR file
Ensure the JAR file was downloaded successfully (not corrupted)

No metrics appearing in SigNoz?

Check OTel Collector logs for errors
Verify the target_system matches your application type
Ensure the JMX receiver is included in the pipeline
Confirm the pipeline exports to the correct destination

Authentication errors?

Verify username and password are correct
Check that the JMX endpoint is configured to accept the provided credentials
For SSL-enabled endpoints, additional TLS configuration may be required

Metrics delayed or missing?

Increase collection_interval if the application is under heavy load
Check network latency between Collector and Java application
Verify the Java application isn't restarting frequently

Next steps

JVM Runtime Metrics for JVM runtime metrics using the OpenTelemetry Java agent
JMX Dashboard Templates for pre-built visualizations
Creating custom dashboards to build your own metric panels
Setup alerts to get notified on resource thresholds

Collect JMX Metrics with the OpenTelemetry Collector

Prerequisites

Step 1. Enable JMX on your Java application

Step 2. Download the JMX metrics JAR

Step 3. Configure the OTel Collector JMX receiver

Supported target systems

Optional authentication

Step 4. Enable the JMX receiver in your pipeline

Validate

Example: Complete configuration

Troubleshooting

"Connection refused" when connecting to JMX?

"Failed to load JAR" error?

No metrics appearing in SigNoz?

Authentication errors?

Metrics delayed or missing?

Next steps

Was this page helpful?

Is this page helpful?