JMX Exporter

JMX Exporter 利用 Java 的 JMX 机制来读取 JVM 运行时的一些监控数据,然后将其转换为 Prometheus 所认知的 Metrics 格式,以便让 Prometheus 对其进行监控采集。

JMX 是 Java Management Extensions 的缩写,是管理 Java 的一种扩展框架,JMX Exporter 正是基于此框架来读取 JVM 的运行时状态的。

Prometheus 官方提供了这个 JMX Exporter ,仓库地址是 https://github.com/prometheus/jmx_exporter ,当前最新版本是 v0.16.1 ,发布于 2021 年 7 月 14 日,最近的发版会一次发两个 JAR 包出来,一个是 Java 7 以及以上用的,另一个是兼容 Java 6 的,大家在下载的时候使用对应的版本就好。

安装运行

JMX Exporter 会作为 Java 的 Agent 运行,通过 HTTP 端口暴露本地 JVM 的指标。它也可以作为一个独立的HTTP 服务运行,并获取远程 JMX 目标,但这样做有很多缺点,比如难以配置和无法暴露进程指标(例如,内存和CPU使用情况)。因此强烈建议将 JMX Exporter 作为 Java Agent 运行。

前边说过,JMX Exporter 会发布两个 JAR 包,一个兼容 Java 6 ,一个是 Java 7 以及以上的,下载好对应的 JAR 包以后,可以使用如下命令和 Java 程序一起启动。

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

启动好以后,可以访问 http://localhost:8080/metrics 来获取监控指标。

绑定特殊的 ip 和端口可以使用 host:port

上边说道,JMX Exporter 可以通过 HTTP 服务的方式单独启动,启动可以使用 run_sample_httpserver.sh 脚本,脚本内容如下:

#!/usr/bin/env bash
# Script to run a java application for testing jmx4prometheus.

version=$(sed -n -e 's#.*<version>\(.*-SNAPSHOT\)</version>#\1#p' pom.xml)

# Note: You can use localhost:5556 instead of 5556 for configuring socket hostname.
java -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.port=5555 -jar jmx_prometheus_httpserver/target/jmx_prometheus_httpserver-${version}-jar-with-dependencies.jar 5556 example_configs/httpserver_sample_config.yml

请注意,由于 JMX 的性质,/metrics 接口可能会超过 Prometheus 的默认抓取超时10秒,这个可以根据实际情况来调整 Prometheus 的值。

配置

下面是官方给出的 jmx_exporter 的配置样例,文件是 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

配置文件里参数的含义如下:

  • 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: -Djavax.net.ssl.keyStore=/home/user/.keystore -Djavax.net.ssl.keyStorePassword=changeit -Djavax.net.ssl.trustStore=/home/user/.truststore -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.
  • whitelistObjectNames A list of ObjectNames to query. Defaults to all mBeans.
  • blacklistObjectNames A list of ObjectNames to not query. Takes precedence over whitelistObjectNames. Defaults to none.
  • 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 and the full 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 UNTYPED.

Metric 名称和 label 名称是经过整理的,符合规范的。

一个最小的配置是{},它将连接到本地 JVM 并以默认格式收集所有内容。注意,获取监控指标的时候会处理所有 mbean,即使它们没有被导出。

Javaagent 的配置文件示例可以在 https://github.com/prometheus/jmx_exporter/tree/master/example_configs 里找到。

输入格式

输入格式:

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

domain |Bean name. This is the part before the colon in the JMX object name. beanPropertyName/Value |Bean properties. These are the key/values after the colon in the JMX object name. keyN |If composite or tabular data is encountered, the name of the attribute is added to this list. attrName |The name of the attribute. For tabular data, this will be the name of the column. If attrNameSnakeCase is set, this will be converted to snake case. value |The value of the attribute.

除了设置了 attrNameSnakeCase 之外,不会对这些值进行转义或其他更改。默认帮助包括这个字符串,除了值。

输出格式:

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

rules 的使用

rules的主要功能是进行指标的过滤和清洗。还有一个功能是对value进行转化。prometheus无法接受字符数据,但有时候我们确实需要这个字符串信息,这时候就可以用rules进行配置转化。 下面以一个案例来介绍rules的使用。

JMX 的格式为一个 JSON 对象,里面是一个包含多个bean对象的数组:

{ 
 "beans":[
  {bean},
  {bean}
 ]
}

下面是 Hadoop 监控时候的一个 bean 对象,

{
   "name" : "Hadoop:service=NameNode,name=FSNamesystemState",
   "modelerType" : "org.apache.hadoop.hdfs.server.namenode.FSNamesystem",
   "PendingReplicationBlocks" : 0,
   "PendingReconstructionBlocks" : 0,
   "UnderReplicatedBlocks" : 0,
   "LowRedundancyBlocks" : 0,
   "ScheduledReplicationBlocks" : 0,
   "PendingDeletionBlocks" : 0,
   "BlockDeletionStartTime" : 1591347343145,
   "FSState" : "Operational",
},

其中 "FSState"是HDFS文件系统的状态,有两个值 Safemode(安全模式)和Operational(可使用)。我希望我的监控可以监测到文件系统的状态。可jmx_exporter中确找不到这个指标。因为我的配置文件是空的,jmx_exporter会过滤到所有字符串value,因为prometheus无法接收。因此我需要配置rules将字符串转化为数值型。 首先是需要根据pattern import的格式把指标的输入格式写出来: Hadoop<>FSState:value 然后用正则表达式进行判断,value含有Safemode 为 0, 含有Operational为1 为了与其他指标统一,我的name的写法与默认输出相同。 最后的配置为:

---
rules:
  - pattern: 'Hadoop<service=NameNode, name=FSNamesystemState><>FSState:.*?Safemode.*?'
    name: Hadoop_NameNode_FSState
    value: 0
  - pattern: 'Hadoop<service=NameNode, name=FSNamesystemState><>FSState:.*?Operational.*?'
    name: Hadoop_NameNode_FSState
    value: 1
  - pattern: '.*'

注意到这里我最后加了一个匹配所有指标的正则表达。如果不加的话,最后exporter除了jvm的指标,只会输出在rules中匹配成功的指标。 还有一个十分tricky的点!- pattern: ‘.*’ 必须放在最后。

我们回头看看rules的描述,是顺序执行的,每个指标而且完成匹配后就会停止继续匹配。如果把全局匹配放在最前,那所有的指标都会被匹配上,匹配就结束了。但带字符串的被过滤掉了,而且后面的规则也不会生效。那这条指标还是不会出现在 jvm_exporter 的 httpserver 上。

此指标在jmx_exporter上的呈现:

# HELP Hadoop_NameNode_FSState Attribute exposed for management (Hadoop<service=NameNode, name=FSNamesystemState><>FSState)
# TYPE Hadoop_NameNode_FSState untyped
Hadoop_NameNode_FSState 1.0

小结

JMX Exporter 的默认指标有很多,全部收集对监控系统的压力很大,在实际使用过程,根据自己的需要来开关不同的参数。

results matching ""

    No results matching ""