Apache Druid Kafka Emitter 扩展:将集群指标与告警以 JSON 流式输出到 Kafka 的完整指南

原创2026-09-22 19:28:491,413 阅读
文章标签:数据库OLAP大数据后端

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 都可以直接消费。结合实际部署经验,建议:

  1. 按 topic 订阅而非按 feed 过滤:默认按事件类型分 topic 即可天然分流;若使用公共 topic,则消费端按 JSON 中的 feed 字段分组;
  2. 监控丢失计数器:关注 Druid 日志中每 5 分钟输出一次的 metricLost/alertLost/requestLost/segmentMetadataLost/invalidLost,若持续增长,优先排查 Kafka 可用性、buffer.memory 是否过小、max.block.ms 是否过短;
  3. 利用打标维度分组告警:为不同环境(environment)、不同区域(region)、不同集群(clusterName)配置不同的 extra.dimensions 组合,便于在监控平台按维度聚合;
  4. 敏感信息走 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 会被自动加入发送集合,这是为保证旧版本配置兼容而保留的行为。
登录后查看全文
druid