jmxreceiver

package module
v0.151.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 28, 2026 License: Apache-2.0 Imports: 27 Imported by: 10

README

JMX Receiver

Status
Stability deprecated: metrics
Deprecation of metrics Date: 2026-01-30
Migration Note: use JMX Gatherer Java program
Distributions contrib
Issues Open issues Closed issues
Code coverage codecov
Code Owners @atoulme, @rogercoll
Emeritus @rmfitzpatrick
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 (built-in otel helper-utilizing Groovy script) or the OpenTelemetry 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 of the JMX JAR and configure the receiver with its path. It is assumed that the JRE is available on your system.

Configuration

Example configuration:

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. 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:

go build -ldflags "-X github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jmxreceiver.MetricsGathererHash=<sha256hash>" ...

Custom JMX Scraper:

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 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:

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.

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.

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.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var AdditionalTargetSystems = "n/a"
View Source 
var MetricsGathererHash = "n/a"

Provided as a build time variable if a development or customer specific JMX Metrics Gatherer needs to be supported

View Source 
var ScraperHash = "n/a"

Provided as a build time variable if a development or customer specific JMX Scraper needs to be supported

Functions

func NewFactory 

func NewFactory() receiver.Factory

Types

type Config added in v0.24.0 

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`

	// The path for the JMX Metric Gatherer or JMX Scraper JAR (/opt/opentelemetry-java-contrib-jmx-metrics.jar by default).
	// Supported by: jmx-scraper and jmx-metric-gatherer
	JARPath string `mapstructure:"jar_path"`
	// The Service URL or host:port for the target coerced to one of form: service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi.
	// Supported by: jmx-scraper and jmx-metric-gatherer
	Endpoint string `mapstructure:"endpoint"`
	// Comma-separated list of systems to monitor
	// Supported by: jmx-scraper and jmx-metric-gatherer
	TargetSystem string `mapstructure:"target_system"`
	// The target source of metric definitions to use for the target system.
	// Supported values are: auto, instrumentation and legacy.
	// Supported by: jmx-scraper
	TargetSource string `mapstructure:"target_source"`
	// Comma-separated list of paths to custom YAML metrics definition,
	// mandatory when TargetSystem is not set.
	// Supported by: jmx-scraper
	JmxConfigs string `mapstructure:"jmx_configs"`
	// The OTLP exporter settings
	// Supported by: jmx-scraper and jmx-metric-gatherer
	OTLPExporterConfig otlpExporterConfig `mapstructure:"otlp"`
	// The JMX username
	// Supported by: jmx-scraper and jmx-metric-gatherer
	Username string `mapstructure:"username"`
	// The JMX password
	// Supported by: jmx-scraper and jmx-metric-gatherer
	Password configopaque.String `mapstructure:"password"`
	// The keystore path for SSL
	// Supported by: jmx-scraper and jmx-metric-gatherer
	KeystorePath string `mapstructure:"keystore_path"`
	// The keystore password for SSL
	// Supported by: jmx-scraper and jmx-metric-gatherer
	KeystorePassword configopaque.String `mapstructure:"keystore_password"`
	// The keystore type for SSL
	// Supported by: jmx-scraper and jmx-metric-gatherer
	KeystoreType string `mapstructure:"keystore_type"`
	// The truststore path for SSL
	// Supported by: jmx-scraper and jmx-metric-gatherer
	TruststorePath string `mapstructure:"truststore_path"`
	// The truststore password for SSL
	// Supported by: jmx-scraper and jmx-metric-gatherer
	TruststorePassword configopaque.String `mapstructure:"truststore_password"`
	// The truststore type for SSL
	// Supported by: jmx-scraper and jmx-metric-gatherer
	TruststoreType string `mapstructure:"truststore_type"`
	// The JMX remote profile.  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.
	// Supported by: jmx-scraper and jmx-metric-gatherer
	RemoteProfile string `mapstructure:"remote_profile"`
	// The SASL/DIGEST-MD5 realm
	// Supported by: jmx-scraper and jmx-metric-gatherer
	Realm string `mapstructure:"realm"`
	// Array of additional JARs to be added to the class path when launching the JMX Metric Gatherer JAR
	// Supported by: jmx-scraper and jmx-metric-gatherer
	AdditionalJars []string `mapstructure:"additional_jars"`
	// Map of resource attributes used by the Java SDK Autoconfigure to set resource attributes
	// Supported by: jmx-scraper and jmx-metric-gatherer
	ResourceAttributes map[string]string `mapstructure:"resource_attributes"`
	// Log level used by the JMX metric gatherer. Should be one of:
	// `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`, `"off"`
	// Supported by: jmx-metric-gatherer
	LogLevel string `mapstructure:"log_level"`
}

func (*Config) Validate added in v0.67.0 

func (c *Config) Validate() error

Source Files

View all Source files

Directories

Path Synopsis
internal
metadata
Package metadata contains the autogenerated telemetry and build information for the receiver/jmx component.
 Package metadata contains the autogenerated telemetry and build information for the receiver/jmx component.
subprocess

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.