jmx-exporter-1.0.1.tar.gz

<picture> <img src="https://circleci.com/gh/prometheus/jmx_exporter.svg?style=shield"/> </picture> JMX Exporter ===== JMX to Prometheus exporter: a collector that can configurable scrape and expose mBeans of a JMX target. This exporter is intended to be run as a Java Agent, exposing a HTTP server and serving metrics of the local JVM. It can be also run as a standalone HTTP server and scrape remote JMX targets, but this has various disadvantages, such as being harder to configure and being unable to expose process metrics (e.g., memory and CPU usage). In particular all the `jvm_*` metrics like `jvm_classes_loaded_total`, `jvm_threads_current`, `jvm_threads_daemon` and `jvm_memory_bytes_used` won't be availabe if using the standalone http server. ### **NOTES** **- Metrics are no longer served on the root (`/`) path - use the `/metrics` path ** **- Some JVM metric names have changed to conform with the [OpenMetrics](https://openmetrics.io/) specification.** **- Dashboards will need to be changed if referencing the changed JVM metrics.** https://prometheus.github.io/client_java/migration/simpleclient/#jvm-metrics ## Running the Java Agent **Running the exporter as a Java agent is strongly encouraged.** - [jmx_prometheus_javaagent-1.0.1.jar](https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/1.0.1/jmx_prometheus_javaagent-1.0.1.jar) To run as a Java agent, download one of the JARs and run: ``` java -javaagent:./jmx_prometheus_javaagent-1.0.1.jar=12345:config.yaml -jar yourJar.jar ``` Metrics will now be accessible at [http://localhost:12345/metrics](http://localhost:12345/metrics). To bind the java agent to a specific IP change the port number to `host:port`. A minimal `config.yaml` looks like this: ```yaml rules: - pattern: ".*" ``` Example configurations can be found in the `example_configs/` directory. ## Running the Standalone HTTP Server - [jmx_prometheus_httpserver-1.0.1.jar](https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_httpserver/1.0.1/jmx_prometheus_httpserver-1.0.1.jar) To run the standalone HTTP server, download one of the JARs and run: ``` java -jar jmx_prometheus_httpserver-1.0.1.jar 12345 config.yaml ``` Metrics will now be accessible at [http://localhost:12345/metrics](http://localhost:12345/metrics). To bind the java agent to a specific IP change the port number to `host:port`. The standalone HTTP server will read JMX remotely over the network. Therefore, you need to specify either `hostPort` or `jmxUrl` in `config.yaml` to tell the HTTP server where the JMX beans can be accessed. A minimal `config.yaml` looks like this: ```yaml hostPort: localhost:9999 rules: - pattern: ".*" ``` As stated above, it is recommended to run JMX exporter as a Java agent and not as a standalone HTTP server. **NOTES** **- `jvm_*` metrics will not be available if running in standalone mode** **- standard Java MBeans that provide JVM metrics will be available using the standard Java MBean ObjectNames** ## Building `./mvnw clean package` to build. ## Configuration The configuration is in YAML. An example with all possible options: ```yaml --- startDelaySeconds: 0 hostPort: 127.0.0.1:1234 username: password: jmxUrl: service:jmx:rmi:///jndi/rmi://127.0.0.1:1234/jmxrmi ssl: false lowercaseOutputName: false lowercaseOutputLabelNames: false includeObjectNames: ["org.apache.cassandra.metrics:*"] excludeObjectNames: ["org.apache.cassandra.metrics:type=ColumnFamily,*"] autoExcludeObjectNameAttributes: true excludeObjectNameAttributes: "java.lang:type=OperatingSystem": - "ObjectName" "java.lang:type=Runtime": - "ClassPath" - "SystemProperties" rules: - pattern: 'org.apache.cassandra.metrics<type=(\w+), name=(\w+)><>Value: (\d+)' name: cassandra_$1_$2 value: $3 valueFactor: 0.001 labels: {} help: "Cassandra metric $1 $2" cache: false type: GAUGE attrNameSnakeCase: false ``` Name | Description ---------|------------ startDelaySeconds | start delay before serving requests. Any requests within the delay period will result in an empty metrics set. hostPort | The host and port to connect to via remote JMX. If neither this nor jmxUrl is specified, will talk to the local JVM. username | The username to be used in remote JMX password authentication. password | The password to be used in remote JMX password authentication. jmxUrl | A full JMX URL to connect to. Should not be specified if hostPort is. ssl | Whether JMX connection should be done over SSL. To configure certificates you have to set following system properties:<br/>`-Djavax.net.ssl.keyStore=/home/user/.keystore`<br/>`-Djavax.net.ssl.keyStorePassword=changeit`<br/>`-Djavax.net.ssl.trustStore=/home/user/.truststore`<br/>`-Djavax.net.ssl.trustStorePassword=changeit` lowercaseOutputName | Lowercase the output metric name. Applies to default format and `name`. Defaults to false. lowercaseOutputLabelNames | Lowercase the output metric label names. Applies to default format and `labels`. Defaults to false. includeObjectNames | A list of [ObjectNames](http://docs.oracle.com/javase/6/docs/api/javax/management/ObjectName.html) to query. Defaults to all mBeans. excludeObjectNames | A list of [ObjectNames](http://docs.oracle.com/javase/6/docs/api/javax/management/ObjectName.html) to not query. Takes precedence over `includeObjectNames`. Defaults to none. autoExcludeObjectNameAttributes | Whether to auto exclude [ObjectName](http://docs.oracle.com/javase/6/docs/api/javax/management/ObjectName.html) attributes that can't be converted to standard metrics types. Defaults to `true`. excludeObjectNameAttributes | A Map of [ObjectNames](http://docs.oracle.com/javase/6/docs/api/javax/management/ObjectName.html) with a list of attribute names to exclude. ObjectNames must be in canonical form. Both ObjectNames and attribute names are matched as a Strings (no regex.) Optional. rules | A list of rules to apply in order, processing stops at the first matching rule. Attributes that aren't matched aren't collected. If not specified, defaults to collecting everything in the default format. pattern | Regex pattern to match against each bean attribute. The pattern is not anchored. Capture groups can be used in other options. Defaults to matching everything. attrNameSnakeCase | Converts the attribute name to snake case. This is seen in the names matched by the pattern and the default format. For example, anAttrName to an\_attr\_name. Defaults to false. name | The metric name to set. Capture groups from the `pattern` can be used. If not specified, the default format will be used. If it evaluates to empty, processing of this attribute stops with no output. value | Value for the metric. Static values and capture groups from the `pattern` can be used. If not specified the scraped mBean value will be used. valueFactor | Optional number that `value` (or the scraped mBean value if `value` is not specified) is multiplied by, mainly used to convert mBean values from milliseconds to seconds. labels | A map of label name to label value pairs. Capture groups from `pattern` can be used in each. `name` must be set to use this. Empty names and values are ignored. If not specified and the default format is not being used, no labels are set. help | Help text for the metric. Capture groups from `pattern` can be used. `name` must be set to use this. Defaults to the mBean attribute description, domain, and name of the attribute. cache | Whether to cache bean name expressions to rule computation (match and mismatch). Not recommended for rules matching on bean value, as only the value from the first scrape will be cached and re-used. This can increase performance when collecting a lot of mbeans. Defaults to `false`. type | The type of the metric, can be `GAUGE`, `COUNTER` or `UNTYPED`. `name` must be set to use this. Defaults to `U