Apache Druid Kafka Emitter 扩展:将集群指标与告警以 JSON 流式输出到 Kafka 的完整指南
Apache Druid Kafka Emitter 扩展:将集群指标与告警以 JSON 流式输出到 Kafka 的完整指南
本文以仓库中 kafka-emitter 扩展文档 为核心骨架,结合
extensions-contrib/kafka-emitter模块的源码与测试,系统讲解 Apache Druid 如何通过kafka-emitter扩展把服务指标(metrics)、告警(alerts)、请求日志(request logs)与段元数据(segment metadata)以 JSON 格式直接写入 Apache Kafka。读完本文,你将掌握该扩展的加载方式、全部配置项及其校验规则、消息格式与底层缓冲/丢失机制,能够在一套已有 Kafka 生态内快速搭建 Druid 集群的监控数据管道。
一、扩展概述与适用场景
kafka-emitter 是 Apache Druid 的社区扩展(community extension),位于仓库 extensions-contrib/kafka-emitter 目录,其作用是把 Druid 各服务进程产生的监控事件以 JSON 格式直接写入 Kafka,而不再依赖 Druid 内置的 logging、http 等发射器。
这一设计的主要价值在于:Kafka 拥有成熟的生态与现成的 Consumer API。如果集群已经在使用 Kafka,就可以借助本扩展把 Druid 的运行状态(指标、告警等)接入已有的消息管道,进而复用 Kafka 周边丰富的工具链与 UI 来做集群监控,无需为 Druid 单独搭一套监控投递通道。
从 pom.xml 可以看到,该模块的核心依赖是 org.apache.kafka:kafka-clients(版本由父 POM 的 ${apache.kafka.version} 统一管理),运行时还依赖 druid-processing 与 druid-server(均为 provided 作用域),也就是说扩展本身只负责"封装 + 投递",事件数据的产生仍来自 Druid 服务端。
典型适用场景:
- 已有 Kafka 基础设施,希望将 Druid 指标统一汇入公司级监控总线;
- 需要按
feed(事件类型)分主题订阅 Druid 的请求日志与段元数据,用于查询审计或数据资产管理; - 希望通过
extra.dimensions、clusterName在事件上打标,实现多集群、多环境的监控分组。
二、安装与加载扩展
2.1 加入扩展加载列表
要在 Druid 中启用该扩展,需要把 kafka-emitter 加入扩展加载列表。加载扩展的完整机制见 扩展加载文档:在 common.runtime.properties 中通过 druid.extensions.loadList 指定需要加载的扩展名:
druid.extensions.loadList=["kafka-emitter"]
kafka-emitter 属于社区扩展(社区扩展清单见 extensions.md 中的 kafka-emitter|Kafka metrics emitter 一行),不会随默认发行包附带。若发行包中未包含该扩展,可使用 pull-deps 按 Maven 坐标拉取(社区扩展的 groupId 一般为 org.apache.druid.extensions.contrib):
java \
-cp "lib/*" \
-Ddruid.extensions.directory="extensions" \
-Ddruid.extensions.hadoopDependenciesDir="hadoop-dependencies" \
org.apache.druid.cli.Main tools pull-deps \
--no-default-hadoop \
-c "org.apache.druid.extensions.contrib:kafka-emitter:<DRUID_VERSION>"
安装完成后,在 druid.extensions.loadList 中加入 "kafka-emitter" 并重启相关服务即可。需要说明的是,扩展加载列表通常配置在集群各服务共用的 common.runtime.properties(例如仓库示例 examples/conf/druid/cluster/_common/common.runtime.properties),因为监控事件可能来自 Coordinator、Overlord、Historical、Broker 等所有进程。
2.2 模块结构与源码入口
该扩展的源码结构非常清晰,全部位于 extensions-contrib/kafka-emitter/src:
KafkaEmitterConfig.java:配置类,负责解析druid.emitter.kafka.*全部参数并执行必填项校验;KafkaEmitter.java:实现 Druid 的Emitter接口,完成事件序列化、缓冲、异步发送与丢失统计;KafkaEmitterModule.java:Guice 模块,把配置绑定到druid.emitter.kafka前缀,并对外提供名为kafka的Emitter实例;- 测试目录下的
KafkaEmitterConfigTest.java与KafkaEmitterTest.java覆盖了配置校验与各类事件的收发行为。
三、配置参数详解
kafka-emitter 的全部配置参数都位于 druid.emitter.kafka 前缀之下(源码层面由 KafkaEmitterModule.java 通过 JsonConfigProvider.bind(binder, "druid.emitter.kafka", KafkaEmitterConfig.class) 完成绑定)。下表完整列出所有参数:
| Property | 说明 | 是否必填 | 默认值 |
|---|---|---|---|
druid.emitter.kafka.bootstrap.servers |
Kafka broker 列表,逗号分隔([hostname:port],[hostname:port]...) |
是 | 无 |
druid.emitter.kafka.event.types |
逗号分隔的事件类型。支持 alerts、metrics、requests、segment_metadata |
否 | ["metrics", "alerts"] |
druid.emitter.kafka.metric.topic |
服务指标(metrics)的目标 Kafka topic。若 event.types 包含 metrics,则该字段不能为空 |
否 | 无 |
druid.emitter.kafka.alert.topic |
告警(alerts)的目标 Kafka topic。若 event.types 包含 alerts,则该字段不能为空 |
否 | 无 |
druid.emitter.kafka.request.topic |
请求日志(request logs)的目标 Kafka topic。若 event.types 包含 requests,则该字段不能为空 |
否 | 无 |
druid.emitter.kafka.segmentMetadata.topic |
段元数据(segment metadata)的目标 Kafka topic。若 event.types 包含 segment_metadata,则该字段不能为空 |
否 | 无 |
druid.emitter.kafka.producer.config |
JSON 格式,用于给 Kafka Producer 设置额外属性 | 否 | 无 |
druid.emitter.kafka.clusterName |
可选,指定 Druid 集群名称,便于在监控环境中分组 | 否 | 无 |
druid.emitter.kafka.extra.dimensions |
可选,JSON 格式的字符串维度 Map,会附加到发出的每条事件上,便于监控分组 | 否 | 无 |
druid.emitter.kafka.producer.hiddenProperties |
JSON 格式,用于指定敏感型 Kafka Producer 属性(如用户名、密码)。该属性接受 DynamicConfigProvider 实现 | 否 | 无 |
3.1 必填校验的源码依据
上述"必填/联动"规则并非文档口头约定,而是在 KafkaEmitterConfig.java 的构造函数中硬编码执行的:bootstrap.servers 为空会抛出 druid.emitter.kafka.bootstrap.servers must be specified.;而当 event.types 包含某类事件但对应 topic 为空时,会分别抛出对应错误信息(例如 druid.emitter.kafka.metric.topic must be specified if druid.emitter.kafka.event.types contains metrics.)。这些行为在 KafkaEmitterConfigTest.java 中通过 DruidExceptionMatcher 逐条断言验证,测试中还确认了非法取值如 "segmentMetadata"(应为 segment_metadata)会直接导致反序列化失败(ValueInstantiationException)。
3.2 事件类型枚举与大小写
事件类型在源码中由 KafkaEmitterConfig.java 内部的 EventType 枚举定义:METRICS、ALERTS、REQUESTS、SEGMENT_METADATA。JSON 序列化时统一转成小写形式(metrics、alerts、requests、segment_metadata),反序列化时则按大写后 valueOf 解析,因此配置值大小写不敏感,但必须使用枚举对应的下划线命名,segmentMetadata 这类驼峰写法不被接受。
3.3 默认事件类型与向后兼容行为
一个容易被忽略的细节:当 druid.emitter.kafka.event.types 未显式设置时,并不会简单地使用 <a href="https://link.gitcode.com/i/4ae217e240ee9f14d349dd2a4c7d546d" target="_blank">"metrics", "alerts"]。源码 [maybeUpdateEventTypes 的逻辑是:
- 先取默认集合
DEFAULT_EVENT_TYPES(即alerts+metrics,定义于 KafkaEmitterConfig.java); - 同时为保持向后兼容,若配置了
request.topic,则自动把requests也加入事件类型集合。
也就是说,老版本用户只要配置了 request.topic,即使不写 event.types 也能继续收到请求日志,升级无需改动配置。
四、配置示例与实战
原文档给出的完整示例(注意其中 alerts 前缺少的引号属文档笔误,以下为修正后的可运行版本):
druid.emitter.kafka.bootstrap.servers=hostname1:9092,hostname2:9092
druid.emitter.kafka.event.types=["metrics", "alerts", "requests", "segment_metadata"]
druid.emitter.kafka.metric.topic=druid-metric
druid.emitter.kafka.alert.topic=druid-alert
druid.emitter.kafka.request.topic=druid-request-logs
druid.emitter.kafka.segmentMetadata.topic=druid-segment-metadata
druid.emitter.kafka.producer.config={"max.block.ms":10000}
druid.emitter.kafka.extra.dimensions={"region":"us-east-1","environment":"preProd"}
druid.emitter.kafka.producer.hiddenProperties={"config":{"sasl.jaas.config": "org.apache.kafka.common.security.plain.PlainLoginModule required username=\\"KV...NI\\" password=\\"gA3...n6a/\\";"}}
4.1 最小可用配置
如果只关心指标与告警(默认事件类型),最小配置只需 broker 地址与两个 topic:
druid.emitter.kafka.bootstrap.servers=localhost:9092
druid.emitter.kafka.metric.topic=druid-metric
druid.emitter.kafka.alert.topic=druid-alert
4.2 与 Druid 监控体系配合
kafka-emitter 只是"发射器"(emitter)的一种实现。要让指标真正产生并流动起来,还需要在 runtime.properties 中同时配置监控器与发射器选择,参考 metrics 文档 与 配置索引:
# 开启监控器(示例为 JVM 监控 + 服务状态监控)
druid.monitoring.monitors=["org.apache.druid.java.util.metrics.JvmMonitor", "org.apache.druid.server.metrics.ServiceStatusMonitor"]
# 选择 kafka emitter 作为发射器(默认是 noop,即关闭指标发射)
druid.emitter=kafka
# kafka-emitter 扩展自身的参数
druid.emitter.kafka.bootstrap.servers=localhost:9092
druid.emitter.kafka.metric.topic=druid-metric
druid.emitter.kafka.alert.topic=druid-alert
仓库示例配置 examples/conf/druid/cluster/_common/common.runtime.properties 中默认使用 druid.emitter=noop,需要接入 Kafka 时把该值改为 kafka 并补充上述 druid.emitter.kafka.* 参数即可。druid.monitoring.monitors 可按进程类型单独配置(例如在 historical/runtime.properties 与 broker/runtime.properties 中差异化设置),druid.emitter.* 则可放在集群共用的 common.runtime.properties 中。
4.3 producer.config 的典型用法
producer.config 以 JSON 形式透传给 Kafka Producer。除示例中的 max.block.ms 外,最常用的还包括与扩展内部缓冲强相关的 buffer.memory(默认 33554432,即 32 MiB,与 Kafka Producer 默认一致)。其余 Kafka Producer 属性(如 acks、linger.ms、compression.type、retries 等)同样可以在此传入,但需要注意:
bootstrap.servers、key/value 序列化器、retries这几个属性会被扩展内部固定设置(见下文源码分析),即使传入也会被覆盖;- 队列内存边界直接读取
producer.config中的buffer.memory值(KafkaEmitter.java),调大该值可提升事件缓冲能力。
4.4 extra.dimensions 与 clusterName 的打标能力
extra.dimensions 与 clusterName 都会作为额外维度注入每条事件,用于监控分组。二者在事件合并时的行为由 addExtraDimensionsToEvent 决定:
- 若设置了
clusterName,事件会带上"clusterName": "<值>"; - 若设置了
extra.dimensions,其全部键值会并入事件; - 执行顺序上
extra.dimensions在clusterName之后putAll,因此当extra.dimensions中恰好含有clusterName键时,以extra.dimensions中的值为准。这一优先级在测试 KafkaEmitterTest.java 中被显式验证(注释clusterName again, extraDimensions should take precedence)。
4.5 hiddenProperties 与敏感信息管理
producer.hiddenProperties 用于存放用户名、密码等敏感 Producer 属性,避免把密钥明文写进配置文件。它接受 Druid 的 DynamicConfigProvider 实现,例如使用内置的环境变量提供器(EnvironmentVariableDynamicConfigProvider):
druid.emitter.kafka.producer.hiddenProperties={"type":"environment","variables":{"sasl.jaas.config":"KAFKA_SASL_JAAS_CONFIG"}}
源码层面,KafkaEmitter.java 在构造 Producer 时会把 producer.config 与 producer.hiddenProperties 解析出的属性依次 putAll 进 Properties,因此动态配置提供器解析出的值会覆盖普通 producer.config 中同名的键。若未配置,则默认使用 MapStringDynamicConfigProvider 的空 Map(KafkaEmitterConfig.java)。
五、事件类型、消息格式与 Topic 分流
5.1 四类事件与对应 Topic
kafka-emitter 将事件按 Java 类型分流到不同队列与 topic(KafkaEmitter.java):
| 事件类型 | 对应 Java 类 | 写入 topic 配置项 | 说明 |
|---|---|---|---|
metrics |
ServiceMetricEvent |
metric.topic |
服务指标,如 JVM、缓存、查询统计等 |
alerts |
AlertEvent |
alert.topic |
服务告警 |
requests |
RequestLogEvent |
request.topic |
查询请求日志(含 SQL 与查询统计) |
segment_metadata |
SegmentMetadataEvent |
segmentMetadata.topic |
段元数据事件 |
测试 KafkaEmitterTest.java 中的 testAllEvents 一次性注入上述全部四类事件,断言它们都被无丢失地写入各自 topic;testAllEventsWithCommonTopic 则验证了四类事件可以共用同一个 topic(此时四个 topic 配置项填写相同值即可)。由于扩展本身并不限制 topic 名称,生产实践中既可按 feed 拆分 topic,也可合并成单一主题后再由下游按 feed 字段区分。
5.2 消息格式
每条消息是事件的 JSON 序列化结果(jsonMapper.writeValueAsString(event.toMap())),并附加 clusterName/extra.dimensions 注入的维度。测试 trackActualEventsPerFeed 展示了消费端的典型处理方式:解析 JSON 后按 feed 字段分组。因此下游 Consumer 可以直接用任意 JSON 解析库(或 Druid 的 DefaultObjectMapper)把消息还原为事件 Map 使用。
5.3 发送节奏与丢失统计
发送是异步批量化的,而非逐条同步投递(KafkaEmitter.java):
- 扩展启动后,每个启用的事件类型都有一个独立的定时发送任务,默认每 10 秒从对应内存队列取一批消息调用
producer.send(...)(DEFAULT_SEND_INTERVAL_SECONDS = 10); - 另有一个每 5 分钟执行一次的日志任务(
DEFAULT_SEND_LOST_INTERVAL_MINUTES = 5),周期性打印各类型丢失计数:metricLost、alertLost、requestLost、segmentMetadataLost、invalidLost。运维时可从日志中观察这些计数器判断是否存在积压或投递失败; - 发送失败(Producer 回调收到异常)时,对应类型的丢失计数
incrementAndGet(),事件不会无限重试。
六、底层实现原理:缓冲、背压与生命周期
6.1 内存有界队列与背压
为避免 Kafka 故障时事件无限堆积拖垮 Druid 进程,扩展为每个事件类型维护了一个内存有界队列 MemoryBoundLinkedBlockingQueue,其内存上限直接取自 producer.config 的 buffer.memory(默认 32 MiB,KafkaEmitter.java)。emit() 时先计算 JSON 字节数(StringUtils.toUtf8(resultJson).length)再按字节计费入队;队列满时 offer 失败,事件被丢弃并计入对应丢失计数器。测试 testDropEventsWhenQueueFull 精确构造了"队列恰好装满 N-3 个事件"的场景,断言最后 3 个事件被丢弃且 metricLostCount 等于 3。
6.2 Producer 的构建细节
setKafkaProducer 展示了 Producer 的完整构建逻辑:
- key/value 序列化器固定为
StringSerializer; retries固定为 3(DEFAULT_RETRIES = 3);- 先
putAll(config.getKafkaProducerConfig()),再putAll(config.getKafkaProducerSecrets().getConfig()),实现"普通配置 + 敏感配置"的合并; - 构建期间会临时切换线程上下文类加载器为扩展自身类加载器,避免扩展类加载隔离环境下的序列化器加载问题。
6.3 生命周期管理
KafkaEmitter 实现了 Druid 的 Emitter 接口(start/flush/close):start() 中启动各事件类型的定时发送任务;flush() 调用 producer.flush() 强制冲刷;close() 用 @LifecycleStop 标注,停止调度线程并关闭 Producer。在 Guice 侧,KafkaEmitterModule.java 通过 @ManageLifecycle 注解把 kafka 命名的 Emitter 纳入 Druid 生命周期管理,进程退出时会自动执行关闭流程。
6.4 测试对行为的印证
仓库测试对行为契约给出了强验证,可作为理解实现的参考:
- KafkaEmitterConfigTest.java 验证配置的序列化/反序列化往返、各必填项缺失时的异常信息、事件类型大小写解析;
- KafkaEmitterTest.java 验证四类事件的正常投递、默认事件类型行为、未订阅事件的丢弃计数(如只订阅 alerts 时 metrics 计数全部计入丢失)、未知事件类型计入
invalidLost、队列满时的丢弃行为,以及extra.dimensions对clusterName的覆盖优先级。
七、消费端集成建议
由于消息是标准 JSON,任何语言的 Kafka Consumer 都可以直接消费。结合实际部署经验,建议:
- 按 topic 订阅而非按 feed 过滤:默认按事件类型分 topic 即可天然分流;若使用公共 topic,则消费端按 JSON 中的
feed字段分组; - 监控丢失计数器:关注 Druid 日志中每 5 分钟输出一次的
metricLost/alertLost/requestLost/segmentMetadataLost/invalidLost,若持续增长,优先排查 Kafka 可用性、buffer.memory是否过小、max.block.ms是否过短; - 利用打标维度分组告警:为不同环境(
environment)、不同区域(region)、不同集群(clusterName)配置不同的extra.dimensions组合,便于在监控平台按维度聚合; - 敏感信息走 DynamicConfigProvider:涉及 SASL/SSL 密码时使用 环境变量动态配置提供器,并确保环境变量对运行 Druid 服务的系统用户可见。
八、常见问题与注意事项
bootstrap.servers必填:缺失时 Druid 启动阶段即抛出DruidException(NOT_FOUND类别、OPERATOR视角),配置阶段即可发现,而不是运行时才报错。- topic 与事件类型必须联动:只要
event.types声明了某类事件,对应 topic 就不能为空;反之,未声明的事件类型即使配置了 topic 也不会发送(emit()中会先检查eventTypes.contains(...))。 segment_metadata的写法:使用下划线形式,驼峰写法(segmentMetadata)会导致配置解析失败。- 事件类型大小写不敏感:
METRICS与metrics等价,但键名(如event.types、segmentMetadata.topic)仍需按文档原样书写。 extra.dimensions会覆盖clusterName:若两者都配置且键冲突,以extra.dimensions为准(有源码与测试双重佐证)。producer.hiddenProperties覆盖producer.config:敏感配置解析结果优先生效,适合存放需要"隐藏"的 SASL、SSL 类属性。- 队列满即丢弃:这是扩展的背压策略——宁可丢弃监控事件,也不阻塞 Druid 主流程;需要更大缓冲时通过
producer.config调大buffer.memory,并通过日志中的丢失计数评估是否匹配。 - 默认事件类型的行为差异:显式设置
event.types与不设置的默认行为不同——不设置时若配置了request.topic,requests会被自动加入发送集合,这是为保证旧版本配置兼容而保留的行为。