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.
Prerequisites
- A Java application with 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:
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:
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:
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 jmxOpen 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:
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_pathpoints 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_systemmatches 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_intervalif 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
