Kafka 指标，直达 OpenTelemetry

monedula-metrics-reporter 运行在 broker 内部，通过 OTLP 把指标推送到你的 collector：包括两套 Kafka 指标 registry、JVM 指标和 KIP-714 客户端遥测，并以标签形式附带 broker 身份。即使 collector 下线，Kafka 也毫无察觉。

Maven CentralGitHub Release

Maven Central

VERSION=0.10.0
curl -L -o monedula-metrics-reporter-${VERSION}.jar \
  https://repo1.maven.org/maven2/dev/monedula/monedula-metrics-reporter/${VERSION}/monedula-metrics-reporter-${VERSION}.jar

GitHub Release

VERSION=0.10.0
curl -L -o monedula-metrics-reporter-${VERSION}.jar \
  https://github.com/monedula-dev/monedula-metrics-reporter/releases/download/v${VERSION}/monedula-metrics-reporter-${VERSION}.jar

运行快速上手示例（英文） GitHub

server.properties

metric.reporters=dev.monedula.metricsreporter.OtlpMetricReporter

otlp.metric.reporter.endpoint=http://otel-collector:4317
otlp.metric.reporter.transport=grpc

终端

$ cp monedula-metrics-reporter-0.10.0.jar $KAFKA_HOME/libs/# then add the lines above to server.properties# every series carries the broker's cluster and node IDs as resource attributes

问题所在

大多数 Kafka 指标都在绕远路。

常见的技术栈会给每个 broker 挂上一个 JMX exporter：它从 JMX MBean 中把 Kafka 的指标读回来，用规则文件把它们映射为指标名，再暴露出来供抓取，或者继续推送到 collector。

monedula-metrics-reporter 接入 Kafka 自身的 MetricsReporter 接口，直接用 OTLP 与 collector 通信。

3: 导出流水线：Kafka SPI 与 Yammer、JVM 运行时，以及 KIP-714 客户端遥测
3.7 到 4.3: 为 0.10.0 测试过的 Apache Kafka 版本，使用 JDK 17 和 21

工作原理

Kafka broker Kafka SPI 与 Yammer registry
KIP-714 客户端 生产者和消费者经由 broker 推送
→
monedula-metrics-reporter 进程内，异步
→
OpenTelemetry Collector 基于 gRPC 或 HTTP 的 OTLP
→
Prometheus、Grafana 或任意 OTLP 后端 路由和扇出都在 collector 中完成

指标从 Kafka 出发，经由进程内的 reporter 流向 OpenTelemetry Collector，再由它路由到任意后端。

collector 宕机时，Kafka 照常运行

指标回调只更新一个内存中的映射；所有网络 I/O 都在守护线程上进行。没有重试队列，也不会无限制地占用内存，因此即使 collector 变慢或不可用，produce 和 fetch 请求也绝不会被拖住。

故障安全设计的工作方式（英文）

collector 不可达
导出调用超时
批次被丢弃，并计入自监控指标
下一个 tick 重新开始；Kafka 从不等待

同一个插件提供 SPI 和 Yammer 指标

Kafka broker 通过两套并行的系统暴露指标。若干 broker 信号只在遗留的 Yammer registry 中注册，因此只支持 SPI 的 reporter 会漏掉它们。这个插件用一份配置同时挂接到两者，而且同一个 JAR 在客户端上也能原样运行。

UnderReplicatedPartitions
OfflinePartitionsCount
ActiveControllerCount
按主题划分的 BrokerTopicMetrics

KIP-714

无需改动客户端的客户端指标

在 broker 上，该插件还会接收 KIP-714 客户端推送的遥测数据，例如客户端侧的请求延迟和重平衡耗时，并把它们转发到同一个 collector。客户端时间序列带有 broker 的身份和 client id，因此可以在 PromQL 中与 broker 时间序列关联。

采集客户端指标（英文）

转发的客户端指标上的标签
`kafka_cluster_id`, `kafka_node_id`	默认开启
`client_id`	默认开启
`client_instance_id`	默认关闭，高基数
principal 和客户端地址	默认关闭，个人数据

附带仪表盘

快速上手示例用 Docker Compose 启动 Kafka、reporter、OpenTelemetry Collector、Prometheus 和 Grafana，并附带可直接使用的 Grafana 仪表盘和 Prometheus 告警规则。

Grafana 快速上手示例（英文）

monedula-metrics-reporter 导出的 Kafka 指标的 Grafana 概览仪表盘

安装

Maven CentralGitHub Release

Maven Central

VERSION=0.10.0
curl -L -o monedula-metrics-reporter-${VERSION}.jar \
  https://repo1.maven.org/maven2/dev/monedula/monedula-metrics-reporter/${VERSION}/monedula-metrics-reporter-${VERSION}.jar

GitHub Release

VERSION=0.10.0
curl -L -o monedula-metrics-reporter-${VERSION}.jar \
  https://github.com/monedula-dev/monedula-metrics-reporter/releases/download/v${VERSION}/monedula-metrics-reporter-${VERSION}.jar

坐标：dev.monedula:monedula-metrics-reporter。每个 GitHub release 还附带 JAR，以及 CycloneDX SBOM 和 Sigstore 签名。

常见问题

monedula-metrics-reporter 免费吗？可以在工作中使用吗？

是的。它采用 AGPL-3.0 许可证，没有付费版本；在你自己的 broker 和客户端中运行它，并不要求你公开代码或配置：AGPL 义务在你分发它（无论是否经过修改）或让他人通过网络使用修改后的版本时适用。

为了获取客户端指标，我的客户端应用需要修改吗？

不需要。KIP-714 推送在 Java 客户端以及 librdkafka 2.5 及更高版本中默认开启。你只需在 broker 端创建一份客户端指标订阅即可集中启用它，reporter 会转发客户端推送的内容。参见采集客户端指标（英文）。

我需要 Prometheus 吗？

不需要。reporter 通过 OTLP 与 OpenTelemetry Collector 通信，而 collector 可以导出到它支持的任意后端。路由、扇出和各厂商的 exporter 都在 collector 中配置。

它支持哪些 Java 和 Kafka 版本？

Java 17 或更高版本，以及 Apache Kafka 3.7.0 到 4.3.0，broker 和客户端均适用：针对 0.10.0，CI 在 Kafka 3.7.0、3.9.0、4.2.0 和 4.3.0 上测试了 JDK 17 和 21。3.7 之前的 Kafka 版本缺少该插件所实现的 ClientTelemetry 接口，也未经测试。参见兼容性（英文）。

它和 jmx_exporter 有什么不同？

两者都可以运行在 Kafka JVM 内部。monedula-metrics-reporter 不需要规则文件：它根据 Kafka 自己的名称派生指标名，用集群 ID 和节点 ID 为 broker 时间序列打标签，并转发 KIP-714 客户端指标。对比页面（英文）介绍了其他方案。