Skip to content

Commit b51a1db

Browse files
pratik-mahalleotelbot[bot]svrnm
authored
docs: add the new JMX page for the java documentation (#8617)
Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com> Co-authored-by: otelbot <197425009+otelbot@users.noreply.github.com> Co-authored-by: Severin Neumann <severin.neumann@altmuehlnet.de> Co-authored-by: Severin Neumann <sneumann@causely.ai>
1 parent 1b2e54f commit b51a1db

3 files changed

Lines changed: 300 additions & 1 deletion

File tree

‎content/en/docs/languages/java/instrumentation.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ instrumentation topics:
2727
for standard operations.
2828
- [Log instrumentation](#log-instrumentation), which is used to get logs from an
2929
existing Java logging framework into OpenTelemetry.
30+
- [JMX metrics](../jmx/) for monitoring JVM and application metrics via JMX
31+
MBeans.
3032

3133
> [!NOTE]
3234
>
@@ -148,7 +150,7 @@ Shims maintained in the OpenTelemetry Java ecosystem:
148150
| Bridge [OpenTracing](https://opentracing.io/) into OpenTelemetry | [README](https://github.com/open-telemetry/opentelemetry-java/tree/main/opentracing-shim) | Traces | `io.opentelemetry:opentelemetry-opentracing-shim:{{% param vers.otel %}}` |
149151
| Bridge [Opencensus](https://opencensus.io/) into OpenTelemetry | [README](https://github.com/open-telemetry/opentelemetry-java/tree/main/opencensus-shim) | Traces, Metrics | `io.opentelemetry:opentelemetry-opencensus-shim:{{% param vers.otel %}}-alpha` |
150152
| Bridge [Micrometer](https://micrometer.io/) into OpenTelemetry | [README](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/micrometer/micrometer-1.5/library) | Metrics | `io.opentelemetry.instrumentation:opentelemetry-micrometer-1.5:{{% param vers.instrumentation %}}-alpha` |
151-
| Bridge [JMX](https://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html) into OpenTelemetry | [README](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/README.md) | Metrics | `io.opentelemetry.instrumentation:opentelemetry-jmx-metrics:{{% param vers.instrumentation %}}-alpha` |
153+
| Bridge [JMX](https://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html) into OpenTelemetry | [README](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/README.md), [JMX metrics guide](../jmx/) | Metrics | `io.opentelemetry.instrumentation:opentelemetry-jmx-metrics:{{% param vers.instrumentation %}}-alpha` |
152154
| Bridge OpenTelemetry into [Prometheus Java SimpleClient](https://github.com/prometheus/client_java/tree/simpleclient) | [README](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/prometheus-client-bridge) | Metrics | `io.opentelemetry.contrib:opentelemetry-prometheus-client-bridge:{{% param vers.contrib %}}-alpha` |
153155
| Bridge OpenTelemetry into [Prometheus Java PrometheusRegistry](https://github.com/prometheus/client_java) | [PrometheusMetricReader Javadoc](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-exporter-prometheus/latest/io/opentelemetry/exporter/prometheus/PrometheusMetricReader.html) | Metrics | `io.opentelemetry:opentelemetry-exporter-prometheus:{{% param vers.otel %}}-alpha` |
154156
| Bridge OpenTelemetry into [Micrometer](https://micrometer.io/) | [README](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/micrometer-meter-provider) | Metrics | `io.opentelemetry.contrib:opentelemetry-micrometer-meter-provider:{{% param vers.contrib %}}-alpha` |

‎content/en/docs/languages/java/jmx.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
---
2+
title: JMX Metrics
3+
weight: 14
4+
description: Collect metrics from JMX MBeans using OpenTelemetry
5+
cSpell:ignore: jconsole jmxremote mbean mbeans visualvm wildfly
6+
---
7+
8+
This page describes how to collect metrics from
9+
[JMX](https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html)
10+
(Java Management Extensions) MBeans and export them to OpenTelemetry.
11+
12+
## Overview
13+
14+
JMX (Java Management Extensions) is a Java technology that provides tools for
15+
managing and monitoring applications via JMX MBeans (Managed Beans). These
16+
MBeans expose management attributes and operations that can be externally
17+
observed.
18+
19+
The OpenTelemetry JMX Metric Insight module allows you to bridge JMX metrics
20+
into OpenTelemetry, enabling you to:
21+
22+
- Monitor JVM metrics (memory, garbage collection, threads, etc.)
23+
- Collect metrics from application-specific MBeans
24+
- Export JMX data alongside other OpenTelemetry telemetry signals
25+
- Use predefined metric mappings for popular target systems (Tomcat, Jetty,
26+
Wildfly, ...)
27+
28+
## Installation
29+
30+
### Using the Java agent
31+
32+
The easiest way to collect JMX metrics is using the OpenTelemetry Java agent
33+
with the JMX metrics extension:
34+
35+
1. Download the OpenTelemetry Java agent (if not already installed):
36+
37+
```sh
38+
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
39+
```
40+
41+
2. Run your application with the agent and enable JMX metrics:
42+
43+
```sh
44+
java -javaagent:opentelemetry-javaagent.jar \
45+
-Dotel.jmx.target.system=tomcat \
46+
-Dotel.jmx.config=/path/to/custom-metrics.yaml \
47+
-jar myapp.jar
48+
```
49+
50+
JMX metrics collection is enabled by setting either (or both) of the following
51+
configuration options:
52+
53+
- `otel.jmx.target.system` to select predefined metric sets to enable
54+
- `otel.jmx.config` to provide path to custom JMX rules
55+
56+
When using the Java agent, the JVM runtime metrics (cpu, memory, ...) are
57+
captured through the `runtime-telemetry` module and are enabled by default
58+
without further configuration needed.
59+
60+
## Configuration
61+
62+
JMX metrics can be collected in two ways:
63+
64+
- **From within the JVM** using the internal JMX interface with the Java agent
65+
- **From outside the JVM** using the remote JMX interface with the JMX Scraper
66+
67+
### Java agent Configuration
68+
69+
When using the OpenTelemetry Java agent, configure JMX metrics using these
70+
properties:
71+
72+
| System Property | Environment Variable | Description | Default |
73+
| ------------------------ | ------------------------ | ----------------------------------------------------- | ------- |
74+
| `otel.jmx.enabled` | `OTEL_JMX_ENABLED` | Enable JMX metric collection | `true` |
75+
| `otel.jmx.target.system` | `OTEL_JMX_TARGET_SYSTEM` | Comma-separated list of predefined metric sets to use | none |
76+
| `otel.jmx.config` | `OTEL_JMX_CONFIG` | Path to custom YAML for metric mapping | none |
77+
78+
### JMX Scraper Configuration
79+
80+
When using the standalone JMX Scraper to collect metrics from a remote JVM,
81+
configure using these properties (note: `otel.jmx.enabled` is not needed).
82+
83+
| System Property | Environment Variable | Description | Default |
84+
| ------------------------ | ------------------------ | ----------------------------------------------------- | ---------- |
85+
| `otel.jmx.service.url` | `OTEL_JMX_SERVICE_URL` | JMX service URL for remote JVM connection | (required) |
86+
| `otel.jmx.target.system` | `OTEL_JMX_TARGET_SYSTEM` | Comma-separated list of predefined metric sets to use | none |
87+
| `otel.jmx.config` | `OTEL_JMX_CONFIG` | Path to custom YAML for metric mapping | none |
88+
89+
For complete configuration reference, see the
90+
[JMX Scraper documentation](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#configuration-reference).
91+
92+
Please note that the remote JVM must be configured to accept remote JMX
93+
connections, being able to connect using `jconsole` or `visualvm` tools is a
94+
recommended first step to ensure configuration and optional authentication is
95+
working as expected.
96+
97+
### Predefined Target Systems
98+
99+
OpenTelemetry provides predefined metric mappings for popular Java frameworks
100+
and application servers. Use the `otel.jmx.target.system` property to enable
101+
them (available with both Java agent and JMX Scraper):
102+
103+
**Example - Monitoring Tomcat (Java agent):**
104+
105+
```sh
106+
java -javaagent:opentelemetry-javaagent.jar \
107+
-Dotel.jmx.target.system=tomcat \
108+
-jar myapp.jar
109+
```
110+
111+
For a complete list of available target systems, see:
112+
113+
- [Java agent predefined target systems](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/README.md#predefined-metric-sets)
114+
- [JMX Scraper predefined target systems](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#predefined-metric-sets)
115+
116+
You can specify multiple target systems by separating them with commas.
117+
118+
### Remote JMX Connections
119+
120+
To collect metrics from a remote JVM, you need to use the JMX Scraper. This
121+
involves two separate JVMs:
122+
123+
1. **Target JVM** - The application being monitored
124+
2. **Scraper JVM** - The JMX metric scraper
125+
126+
#### Step 1: Configure the Target JVM
127+
128+
First, start your target application with JMX remote enabled:
129+
130+
```sh
131+
java -Dcom.sun.management.jmxremote \
132+
-Dcom.sun.management.jmxremote.port=9999 \
133+
-Dcom.sun.management.jmxremote.authenticate=false \
134+
-Dcom.sun.management.jmxremote.ssl=false \
135+
-jar myapp.jar
136+
```
137+
138+
> [!WARNING] The example above disables authentication and SSL for simplicity.
139+
> In production environments, always enable authentication and SSL for JMX
140+
> connections.
141+
142+
#### Step 2: Run the JMX Scraper
143+
144+
Download the JMX Scraper from the
145+
[OpenTelemetry Java Contrib releases](https://github.com/open-telemetry/opentelemetry-java-contrib/releases)
146+
page (look for `opentelemetry-jmx-scraper-<version>-all.jar`).
147+
148+
Then run the scraper, pointing it to your target JVM:
149+
150+
```sh
151+
java -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://tomcat.example.com:9999/jmxrmi \
152+
-Dotel.jmx.target.system=tomcat \
153+
-jar opentelemetry-jmx-scraper.jar
154+
```
155+
156+
You can configure the scraper using the same properties as the Java agent
157+
(target system, collection interval, etc.).
158+
159+
For more details, see the
160+
[JMX Scraper documentation](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper).
161+
162+
> [!NOTE] If you're migrating from the deprecated JMX Metric Gatherer, see the
163+
> [migration guide](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#migrating-from-jmx-metric-gatherer).
164+
165+
## Custom Metric Mappings
166+
167+
For application-specific MBeans or custom monitoring requirements, you can
168+
create custom metric mappings using a YAML configuration file.
169+
170+
### Creating a Custom YAML Configuration
171+
172+
Create a YAML file that defines how to map JMX attributes to OpenTelemetry
173+
metrics:
174+
175+
**Example - `custom-jmx-metrics.yaml`:**
176+
177+
```yaml
178+
rules:
179+
- bean: com.myapp:type=CustomMetrics
180+
mapping:
181+
RequestCount:
182+
metric: myapp.requests.count
183+
type: counter
184+
description: Total request count
185+
unit: '1'
186+
ResponseTime:
187+
metric: myapp.response.time
188+
type: gauge
189+
description: Average response time
190+
unit: ms
191+
ActiveSessions:
192+
metric: myapp.sessions.active
193+
type: updowncounter
194+
description: Active sessions
195+
unit: '1'
196+
```
197+
198+
Use the file with your application:
199+
200+
```sh
201+
java -javaagent:opentelemetry-javaagent.jar \
202+
-Dotel.jmx.config=/path/to/custom-jmx-metrics.yaml \
203+
-jar myapp.jar
204+
```
205+
206+
For a complete reference of the YAML syntax, see the
207+
[JMX Metrics configuration documentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/jmx-metrics).
208+
209+
## Verification
210+
211+
To verify that JMX metrics are being collected:
212+
213+
1. **Check the logs** - Look for messages indicating JMX metric collection has
214+
started
215+
2. **Use the logging exporter** - Configure the logging exporter to see metrics
216+
in the console without needing a backend
217+
3. **Use a metrics backend** - Configure an OTLP exporter and view the metrics
218+
in your observability platform
219+
4. **Use JConsole** - Connect to your application with JConsole to verify MBeans
220+
are accessible
221+
222+
**Example with logging exporter (Java agent):**
223+
224+
```sh
225+
java -javaagent:opentelemetry-javaagent.jar \
226+
-Dotel.metrics.exporter=logging \
227+
-jar myapp.jar
228+
```
229+
230+
**Example with OTLP exporter (Java agent):**
231+
232+
```sh
233+
java -javaagent:opentelemetry-javaagent.jar \
234+
-Dotel.metrics.exporter=otlp \
235+
-Dotel.exporter.otlp.endpoint=http://localhost:4318 \
236+
-jar myapp.jar
237+
```
238+
239+
**Example with OTLP exporter (JMX Scraper):**
240+
241+
```sh
242+
java -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://myapp.example.com:9999/jmxrmi \
243+
-Dotel.jmx.target.system=tomcat \
244+
-Dotel.metrics.exporter=otlp \
245+
-Dotel.exporter.otlp.endpoint=http://localhost:4318 \
246+
-jar opentelemetry-jmx-scraper.jar
247+
```
248+
249+
## Additional Resources
250+
251+
- [JMX Scraper Documentation](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper) -
252+
Complete configuration reference and examples
253+
- [JMX Scraper Migration Guide](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#migrating-from-jmx-metric-gatherer) -
254+
Migrating from the deprecated JMX Metric Gatherer
255+
- [JMX Metrics (Java agent)](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/README.md) -
256+
Java agent JMX metrics documentation
257+
- [Predefined Target Systems](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#predefined-metric-sets) -
258+
Built-in metric sets for popular frameworks
259+
- [Java agent Documentation](/docs/zero-code/java/agent/) - General Java agent
260+
configuration
261+
- [Configuration Guide](../configuration/) - OpenTelemetry SDK configuration
262+
options
263+
264+
## Related Topics
265+
266+
- [Instrumentation ecosystem](../instrumentation/) - Other instrumentation
267+
options
268+
- [Shims](../instrumentation/#shims) - Bridging other observability libraries
269+
- [Metrics API](../api/#meterprovider) - Creating custom metrics

‎static/refcache.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2571,6 +2571,10 @@
25712571
"StatusCode": 200,
25722572
"LastSeen": "2026-05-02T09:56:41.44790968Z"
25732573
},
2574+
"https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html": {
2575+
"StatusCode": 200,
2576+
"LastSeen": "2026-01-05T15:50:14.87247516Z"
2577+
},
25742578
"https://docs.oracle.com/javase/specs/jls/se7/html/jls-10.html": {
25752579
"StatusCode": 200,
25762580
"LastSeen": "2026-05-02T09:56:58.000968776Z"
@@ -11975,6 +11979,10 @@
1197511979
"StatusCode": 206,
1197611980
"LastSeen": "2026-05-01T10:08:22.239534387Z"
1197711981
},
11982+
"https://github.com/open-telemetry/opentelemetry-java-contrib/releases": {
11983+
"StatusCode": 206,
11984+
"LastSeen": "2026-01-05T15:50:20.980800941Z"
11985+
},
1197811986
"https://github.com/open-telemetry/opentelemetry-java-contrib/tree/b7a327218c8cf0928c8cb2198e5fa764d530afda/samplers?from_branch=main": {
1197911987
"StatusCode": 206,
1198011988
"LastSeen": "2026-04-29T10:25:38.265930543Z"
@@ -12003,6 +12011,22 @@
1200312011
"StatusCode": 206,
1200412012
"LastSeen": "2026-05-03T09:59:28.385718442Z"
1200512013
},
12014+
"https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper": {
12015+
"StatusCode": 206,
12016+
"LastSeen": "2026-01-05T15:50:23.580862059Z"
12017+
},
12018+
"https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#configuration-reference": {
12019+
"StatusCode": 206,
12020+
"LastSeen": "2026-01-05T15:50:17.024513191Z"
12021+
},
12022+
"https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#migrating-from-jmx-metric-gatherer": {
12023+
"StatusCode": 206,
12024+
"LastSeen": "2026-01-05T15:50:28.371643052Z"
12025+
},
12026+
"https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#predefined-metric-sets": {
12027+
"StatusCode": 206,
12028+
"LastSeen": "2026-01-05T15:50:30.588620347Z"
12029+
},
1200612030
"https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/micrometer-meter-provider": {
1200712031
"StatusCode": 206,
1200812032
"LastSeen": "2026-05-02T09:55:09.80032361Z"
@@ -12091,6 +12115,10 @@
1209112115
"StatusCode": 206,
1209212116
"LastSeen": "2026-05-01T10:08:18.741245669Z"
1209312117
},
12118+
"https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/README.md#predefined-metric-sets": {
12119+
"StatusCode": 206,
12120+
"LastSeen": "2026-02-12T06:56:30.112929035Z"
12121+
},
1209412122
"https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/javaagent/kafka-broker.md": {
1209512123
"StatusCode": 206,
1209612124
"LastSeen": "2026-05-03T09:58:43.609437716Z"

0 commit comments

Comments
 (0)