xzxwl/jmx-exporter

JMX Exporter

镜像概述和主要用途

JMX Exporter是一个JMX到Prometheus的导出器，能够可配置地抓取和暴露JMX目标的mBeans。该导出器旨在作为Java Agent运行，暴露HTTP服务器并提供本地JVM的指标。也可作为独立HTTP服务器运行并抓取远程JMX目标，但存在配置复杂、无法暴露进程指标（如内存和CPU使用率）等缺点，因此强烈建议以Java Agent方式运行。

核心功能和特性

• 可配置抓取JMX mBeans并转换为Prometheus指标格式
• 支持本地JVM监控（推荐，通过Java Agent）和远程JMX目标监控
• 灵活的YAML配置，支持白名单/黑名单过滤mBeans
• 自定义指标名称、标签、类型和帮助信息
• 支持SSL配置以安全连接JMX目标
• 指标名称和标签自动 sanitize，确保符合Prometheus规范

使用场景和适用范围

适用于需要将Java应用的JMX指标集成到Prometheus监控系统的场景，包括：

• 监控JVM性能指标（内存、CPU、线程等）
• 收集Java应用的业务指标（如吞吐量、延迟等）
• 为微服务、数据库（如Cassandra）等Java应用提供可观测性数据

使用方法

作为Java Agent运行（推荐）

1. 下载JMX Exporter JAR文件：https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/0.15.0/jmx_prometheus_javaagent-0.15.0.jar

2. 运行Java应用时添加Java Agent参数：

bash
java -javaagent:./jmx_prometheus_javaagent-0.15.0.jar=8080:config.yaml -jar yourJar.jar

• 8080: 暴露指标的HTTP端口
• config.yaml: 配置文件路径

3. 访问指标：指标将在 http://localhost:8080/metrics 可用

4. 绑定到特定IP：将端口号改为 host:port，例如 192.168.1.100:8080:config.yaml

作为独立HTTP服务器运行

参考示例脚本 ./run_sample_httpserver.sh，该脚本演示如何针对自身运行HTTP服务器。

注意：由于JMX特性，/metrics 端点可能超过Prometheus默认的10秒抓取超时时间。

构建

使用Maven构建：

bash
mvn package

配置说明

配置文件采用YAML格式，以下是包含所有可能选项的示例：

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
whitelistObjectNames: ["org.apache.cassandra.metrics:*"]
blacklistObjectNames: ["org.apache.cassandra.metrics:type=ColumnFamily,*"]
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

配置参数说明

规则（rules）参数说明

指标名称和标签处理

指标名称和标签名称会被 sanitize：除[a-zA-Z0-9:_]外的所有字符替换为下划线，相邻下划线会被合并。标签值和帮助文本无限制。

最小配置

最小配置为{}, 将连接本地JVM并以默认格式收集所有指标。注意：即使未导出，抓取器始终处理所有mBeans。

模式输入格式

模式匹配的输入格式为：

domain<beanpropertyName1=beanPropertyValue1, beanpropertyName2=beanPropertyValue2, ...><key1, key2, ...>attrName: value

除attrNameSnakeCase的转换外，这些值不会被转义或修改。默认帮助信息包含此字符串（除value外）。

默认格式

默认格式会将beans转换为合理的指标，格式为：

domain_beanPropertyValue1_key1_key2_...keyN_attrName{beanpropertyName2="beanPropertyValue2", ...}: value

若某部分未设置，则会被排除。

测试

使用Maven运行测试：

bash
mvn test

调试

独立模式启动抓取器

可在独立模式启动JMX抓取器以调试调用：

bash
git clone https://github.com/prometheus/jmx_exporter.git
cd jmx_exporter
mvn package
java -cp collector/target/collector*.jar  io.prometheus.jmx.JmxScraper  service:jmx:rmi:your_url

详细日志

创建logging.properties文件，内容如下：

handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=ALL
io.prometheus.jmx.level=ALL
io.prometheus.jmx.shaded.io.prometheus.jmx.level=ALL

Java启动时添加以下参数：

bash
-Djava.util.logging.config.file=/path/to/logging.properties

安装

构建过程中会创建Debian二进制包，可用于将可执行文件安装到/usr/bin/jmx_exporter，配置文件位于/etc/jmx_exporter/jmx_exporter.yaml。