jmxreceiver

README

JMX Receiver

Status
Stability	unmaintained: metrics
Distributions	contrib
Issues
Code Owners
Emeritus	@rmfitzpatrick

Overview

The JMX Receiver will work in conjunction with the OpenTelemetry JMX Metric Gatherer to report metrics from a target MBean server using a built-in otel helper-utilizing Groovy script.

Details

This receiver will launch a child JRE process running the JMX Metric Gatherer configured with your specified JMX connection information and target Groovy script. 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 Metric Gatherer JAR and configure the receiver with its path. It is assumed that the JRE is available on your system.

Configuration

Note: this receiver is in alpha and functionality and configuration fields are subject to change.

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)

The path for the JMX Metric Gatherer uber JAR 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.

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

endpoint

The JMX Service URL or host and port used to construct the Service URL the Metric Gatherer's 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

The built-in target system (or systems) metric gatherer script to run. Must be a subset of: "activemq", "cassandra", "hbase", "hadoop", "jetty", "jvm", "kafka", "kafka-consumer", "kafka-producer", "solr", "tomcat", "wildfly".

If additional target systems must be supported (because of a custom JMX metrics gatherer 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.

collection_interval (default: 10s)

The interval time for the Groovy script to be run and metrics to be exported by the JMX Metric Gatherer within the persistent JRE process.

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

initial_delay (default: 1s)

Defines how long this receiver waits before starting.

username

The username to use for JMX authentication.

Corresponds to the otel.jmx.username property.

password

The password to use for JMX authentication.

Corresponds to the otel.jmx.password property.

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

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

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

otlp.timeout (default: 5s)

The otlp exporter request timeout.

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

otlp.headers

The headers to include in otlp metric submission requests.

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

keystore_path

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

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

keystore_password

The keystore file password if required by SSL.

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

keystore_type

The keystore type if required by SSL.

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

truststore_path

The truststore path if the SSL profile is required.

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

truststore_password

The truststore file password if required by SSL.

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

truststore_type

The truststore type if required by SSL.

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

remote_profile

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

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

Corresponds to the otel.jmx.realm property.

additional_jars

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

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

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

• Variables
• func NewFactory() receiver.Factory
• type Config
  • func (c *Config) Validate() error

Variables

var AdditionalTargetSystems = "n/a"

var MetricsGathererHash = "n/a"

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

Functions

func NewFactory

func NewFactory() receiver.Factory

Types

type Config

type Config struct {
	// The path for the JMX Metric Gatherer uber JAR (/opt/opentelemetry-java-contrib-jmx-metrics.jar by default).
	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.
	Endpoint string `mapstructure:"endpoint"`
	// The target system for the metric gatherer whose built in groovy script to run.
	TargetSystem string `mapstructure:"target_system"`
	// The duration in between groovy script invocations and metric exports (10 seconds by default).
	// Will be converted to milliseconds.
	CollectionInterval time.Duration `mapstructure:"collection_interval"`
	// The exporter settings for
	OTLPExporterConfig otlpExporterConfig `mapstructure:"otlp"`
	// The JMX username
	Username string `mapstructure:"username"`
	// The JMX password
	Password configopaque.String `mapstructure:"password"`
	// The keystore path for SSL
	KeystorePath string `mapstructure:"keystore_path"`
	// The keystore password for SSL
	KeystorePassword configopaque.String `mapstructure:"keystore_password"`
	// The keystore type for SSL
	KeystoreType string `mapstructure:"keystore_type"`
	// The truststore path for SSL
	TruststorePath string `mapstructure:"truststore_path"`
	// The truststore password for SSL
	TruststorePassword configopaque.String `mapstructure:"truststore_password"`
	// The truststore type for SSL
	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.
	RemoteProfile string `mapstructure:"remote_profile"`
	// The SASL/DIGEST-MD5 realm
	Realm string `mapstructure:"realm"`
	// Array of additional JARs to be added to the the class path when launching the JMX Metric Gatherer JAR
	AdditionalJars []string `mapstructure:"additional_jars"`
	// Map of resource attributes used by the Java SDK Autoconfigure to set resource attributes
	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"`
	LogLevel string `mapstructure:"log_level"`
}

func (*Config) Validate

func (c *Config) Validate() error