> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Jmx

> OpenTelemetry receiver for Jmx

# Jmx Receiver

![Status](https://img.shields.io/badge/status-deprecated-lightgrey)

**Available in:** `contrib`

**Maintainers:** [@atoulme](https://github.com/atoulme), [@rogercoll](https://github.com/rogercoll)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/jmxreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-deprecated-green)

## Overview

### Deprecation notice

The `jmxreceiver` component is deprecated. Running Java as part of the Collector introduces significant operational complexity, especially since the Collector is commonly deployed as a container and official images do not include a Java runtime. This results in a broken user experience.

More generally, the Collector should not run subprocesses. While the `jmxreceiver` carved out a limited exception, this sets a precedent we do not want to maintain. Managing JMX scraping via a standalone Java process (JMX Gatherer) is recommended.

### Overview

The JMX Receiver will work in conjunction with the [OpenTelemetry JMX Metric Gatherer](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/jmx-metrics/README.md) (built-in `otel` helper-utilizing Groovy script) or the [OpenTelemetry JMX Scraper](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper) (YAML metrics mapping) to report metrics from a target MBean server.

### Details

This receiver will launch a child JRE process running the corresponding JAR (JMX Metric Gatherer or JMX Scraper) configured with your specified JMX
connection information. It then reports metrics to an implicitly created OTLP receiver.
In order to use you will need to download the most [recent release](https://github.com/open-telemetry/opentelemetry-java-contrib/releases)
of the JMX JAR and configure the receiver with its path. It is assumed that the JRE is
available on your system.

Example configuration:

```yaml theme={null}
receivers:
  jmx:
    jar_path: /opt/opentelemetry-java-contrib-jmx-metrics.jar
    endpoint: my_jmx_host:12345
    target_system: jvm
    collection_interval: 10s
    initial_delay: 1s
    # optional: the same as specifying OTLP receiver endpoint.
    otlp:
      endpoint: mycollectorotlpreceiver:4317
    username: my_jmx_username
    # determined by the environment variable value
    password: ${env:MY_JMX_PASSWORD}
    resource_attributes:
      my.attr: my.value
      my.other.attr: my.other.value
    log_level: info
    additional_jars:
      - /path/to/other.jar
```

### jar\_path (default: `/opt/opentelemetry-java-contrib-jmx-metrics.jar`)

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The path for the JMX JAR (JMX Metric Gatherer or JMX Scraper) to run. This must represent a released version 1.9+ of the jar,
which can be downloaded from [github](https://github.com/open-telemetry/opentelemetry-java-contrib/releases).
If a non-released version is required, you can specify a custom version by providing the sha256 hash of your
custom version of the jar during collector build time using the `ldflags` option.

For the JMX Metric Gatherer:

```bash theme={null}
go build -ldflags "-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.MetricsGathererHash=<sha256hash>" ...
```

Custom JMX Scraper:

```bash theme={null}
go build -ldflags "-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.ScraperHash=<sha256hash>" ...
```

### endpoint

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The [JMX Service URL](https://docs.oracle.com/javase/8/docs/api/javax/management/remote/JMXServiceURL.html) or host
and port used to construct the Service URL the JMX client should use. Value must be in the form of
`service:jmx:<protocol>:<sap>` or `host:port`. Values in `host:port` form will be used to create a Service URL of
`service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi`.

When in or coerced to `service:jmx:<protocol>:<sap>` form, corresponds to the `otel.jmx.service.url` property.

*Required.*

### target\_system

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The built-in target system (or systems) metric gatherer to run. Supported
targets include:

* [JMX Scraper documentation](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#configuration-reference)
* [JMX Gatherer documentation](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-metrics#target-systems)

If additional target systems must be supported (because of a custom jar configured using the
`MetricsGathererHash` build time config), they can be added with another build time flag.

```bash theme={null}
go build -ldflags "-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.MetricsGathererHash=<sha256hash>
       -X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.AdditionalTargetSystems=newtarget,othernewtarget" ...
```

Corresponds to the `otel.jmx.target.system` property.

### target\_source

**Supported by:** `jmx-scraper`

Source of metrics definitions to use for `target_system`, supported values are `auto` (default), `instrumentation` and `legacy`. Find more details in the [JMX Scraper documentation](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/jmx-scraper#configuration-reference).

### jmx\_configs

**Supported by:** `jmx-scraper`

Comma-separated list of paths to custom YAML metrics definition, mandatory when `target_system` is not set.

### collection\_interval (default: `10s`)

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The interval time for collecting the metrics to be exported by the JMX JAR within the persistent JRE process.

Corresponds to the `otel.jmx.interval.milliseconds` property.

### initial\_delay (default: `1s`)

**Supported by:** `jmx-scraper`, `jmx-gatherer`

Defines how long this receiver waits before starting.

### username

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The username to use for JMX authentication.

Corresponds to the `otel.jmx.username` property.

### password

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The password to use for JMX authentication.

Corresponds to the `otel.jmx.password` property.

### otlp.endpoint (default: `0.0.0.0:<random open port>`)

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The otlp exporter endpoint to which to listen and submit metrics.

Corresponds to the `otel.exporter.otlp.endpoint` property.

### otlp.timeout (default: `5s`)

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The otlp exporter request timeout.

Corresponds to the `otel.exporter.otlp.metric.timeout` property.

### otlp.headers

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The headers to include in otlp metric submission requests.

Corresponds to the `otel.exporter.otlp.metadata` property.

### keystore\_path

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The keystore path is required if SSL is enabled on the target JVM.

Corresponds to the `javax.net.ssl.keyStore` property.

### keystore\_password

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The keystore file password if required by SSL.

Corresponds to the `javax.net.ssl.keyStorePassword` property.

### keystore\_type

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The keystore type if required by SSL.

Corresponds to the `javax.net.ssl.keyStoreType` property.

### truststore\_path

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The truststore path if the SSL profile is required.

Corresponds to the `javax.net.ssl.trustStore` property.

### truststore\_password

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The truststore file password if required by SSL.

Corresponds to the `javax.net.ssl.trustStorePassword` property.

### truststore\_type

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The truststore type if required by SSL.

Corresponds to the `javax.net.ssl.trustStoreType` property.

### remote\_profile

**Supported by:** `jmx-scraper`, `jmx-gatherer`

Supported JMX remote profiles are TLS in combination with SASL profiles: SASL/PLAIN, SASL/DIGEST-MD5 and SASL/CRAM-MD5.
Should be one of: `"SASL/PLAIN"`, `"SASL/DIGEST-MD5"`, `"SASL/CRAM-MD5"`, `"TLS SASL/PLAIN"`, `"TLS SASL/DIGEST-MD5"`,
or `"TLS SASL/CRAM-MD5"`, though no enforcement is applied.

Corresponds to the `otel.jmx.remote.profile` property.

### realm

**Supported by:** `jmx-scraper`, `jmx-gatherer`

The realm, as required by remote profile SASL/DIGEST-MD5.

Corresponds to the `otel.jmx.realm` property.

### additional\_jars

**Supported by:** `jmx-scraper`, `jmx-gatherer`

Additional JARs to be included in the java command classpath. This is currently only used for support for `wildfly`, where the Additional Jar should be a version of the jboss-client jar found on your wildfly installation.

### resource\_attributes

**Supported by:** `jmx-scraper`, `jmx-gatherer`

Map of resource attributes that will be applied to any metrics emitted from the metrics gatherer.

Corresponds to the `otel.resource.attributes` property.

### log\_level

**Supported by:** `jmx-gatherer`

SLF4J log level for the JMX metrics gatherer. Must be one of: `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`, `"off"`. If not provided, will attempt to match to the current log level of the collector.

Corresponds to the `org.slf4j.simpleLogger.defaultLogLevel` property.

## Configuration

### Example Configuration

```yaml theme={null}
jmx:
jmx/all:
  jar_path: testdata/fake_jmx.jar
  endpoint: myendpoint:12345
  target_system: jvm
  collection_interval: 15s
  username: myusername
  password: mypassword
  otlp:
    endpoint: myotlpendpoint
    headers:
      x-header-1: value1
      x-header-2: value2
    timeout: 5s
  keystore_path: mykeystorepath
  keystore_password: mykeystorepassword
  keystore_type: mykeystoretype
  truststore_path: mytruststorepath
  truststore_password: mytruststorepassword
  remote_profile: myremoteprofile
  realm: myrealm
  log_level: trace
  resource_attributes:
    one: two
  additional_jars:
    - testdata/fake_additional.jar
jmx/validscraperjmxconfigs:
  jar_path: testdata/fake_jmx_scraper.jar
  endpoint: myendpoint:55555
  otlp:
    endpoint: 0.0.0.0:0
    timeout: 5s
  jmx_configs: testdata/rules.yaml
jmx/missingendpoint:
  jar_path: testdata/fake_jmx.jar
  target_system: jvm
jmx/missingtarget:
  jar_path: testdata/fake_jmx.jar
  endpoint: service:jmx:rmi:///jndi/rmi://host:12345/jmxrmi
jmx/missingtargetandjmxconfig:
  jar_path: testdata/fake_jmx_scraper.jar
  endpoint: service:jmx:rmi:///jndi/rmi://host:12345/jmxrmi
jmx/invalidinterval:
  jar_path: testdata/fake_jmx.jar
  endpoint: myendpoint:23456
  target_system: jvm
  collection_interval: -100ms
jmx/invalidotlptimeout:
  jar_path: testdata/fake_jmx.jar
  endpoint: myendpoint:34567
  target_system: jvm
  otlp:
    timeout: -100ms
jmx/nonexistentjar:
  jar_path: testdata/file_does_not_exist.jar
  endpoint: myendpoint:23456
  target_system: jvm
jmx/invalidjar:
  jar_path: testdata/fake_jmx_wrong.jar
  endpoint: myendpoint:23456
  target_system: jvm
jmx/invalidloglevel:
  jar_path: testdata/fake_jmx.jar
  endpoint: myendpoint:55555
  target_system: jvm
  log_level: truth
jmx/invalidloglevelscraper:
  jar_path: testdata/fake_jmx_scraper.jar
  endpoint: myendpoint:55555
  target_system: jvm
  log_level: truth
jmx/invalidtargetsystem:
  jar_path: testdata/fake_jmx.jar
  endpoint: myendpoint:55555
  target_system: jvm,fakejvmtechnology
```

***

*Last generated: 2026-07-06*