Apache Druid Kafka 流式摄入:Supervisor 配置与 Kafka 输入格式实战指南
Apache Druid Kafka 流式摄入:Supervisor 配置与 Kafka 输入格式实战指南
Apache Druid 的 Kafka indexing service 通过 Overlord 上的 supervisor 统一管理 Kafka 摄入任务的创建与生命周期,借助 Kafka 的 partition 与 offset 机制实现 exactly-once 摄入,并自动协调 handoff、故障恢复、扩缩容与副本需求。本文围绕 docs/ingestion/kafka-ingestion.md 展开,完整覆盖 supervisor spec 的 I/O 配置、消费者属性、多 topic 摄入、idle 配置、Kafka 输入格式(含元数据解析)与 tuning 配置,并结合仓库源码揭示其底层实现,帮助读者掌握从搭建扩展到投产调优的完整路径。
前置条件与扩展加载
要使用 Kafka indexing service,首先必须在 Overlord 和 MiddleManager 两台服务上加载 druid-kafka-indexing-service 扩展。加载方式是通过 druid.extensions.loadList 配置项指定扩展列表,例如在 common.runtime.properties 中配置:
druid.extensions.loadList=["druid-kafka-indexing-service"]
该扩展在 docs/configuration/extensions.md 中被描述为"Supervised exactly-once Apache Kafka ingestion for the indexing service"。扩展的代码位于仓库的 extensions-core/kafka-indexing-service,核心类包括 KafkaSupervisor、KafkaIndexTask 以及 KafkaInputFormat 等。
版本前提:使用 Kafka indexing service 需要 Apache Kafka 0.11.x 或更高版本。如果使用的是更老版本的 Kafka,请先参考 Kafka 官方升级指南完成升级。
Supervisor spec 配置总览
supervisor spec 是一份 JSON 配置,描述 Druid 应如何消费、处理并索引流式数据。Kafka 专属的 spec 顶层结构如下:
{
"type": "kafka",
"spec": {
"dataSchema": { ... },
"ioConfig": { ... },
"tuningConfig": { ... }
},
"suspended": false
}
其中 type 必须为 kafka,spec 是配置容器,包含 dataSchema(数据模式)、ioConfig(I/O 配置)与可选的 tuningConfig(调优配置)。suspended 用于将 supervisor 置于挂起状态。
以下是一份完整的 Kafka supervisor spec 示例(来自 docs/ingestion/kafka-ingestion.md):
{
"type": "kafka",
"spec": {
"dataSchema": {
"dataSource": "metrics-kafka",
"timestampSpec": {
"column": "timestamp",
"format": "auto"
},
"dimensionsSpec": {
"dimensions": [],
"dimensionExclusions": [
"timestamp",
"value"
]
},
"metricsSpec": [
{ "name": "count", "type": "count" },
{ "name": "value_sum", "fieldName": "value", "type": "doubleSum" },
{ "name": "value_min", "fieldName": "value", "type": "doubleMin" },
{ "name": "value_max", "fieldName": "value", "type": "doubleMax" }
],
"granularitySpec": {
"type": "uniform",
"segmentGranularity": "HOUR",
"queryGranularity": "NONE"
}
},
"ioConfig": {
"topic": "metrics",
"inputFormat": { "type": "json" },
"consumerProperties": {
"bootstrap.servers": "localhost:9092"
},
"taskCount": 1,
"replicas": 1,
"taskDuration": "PT1H"
},
"tuningConfig": {
"type": "kafka",
"maxRowsPerSegment": 5000000
}
}
}
对于所有流式摄入方法(Kafka / Kinesis)共享的配置项,参见 Supervisor spec。
I/O 配置(ioConfig)
下表列出 Kafka 专属的 ioConfig 属性;共享属性参见 Supervisor I/O configuration。
| 属性 | 类型 | 描述 | 是否必填 | 默认值 |
|---|---|---|---|---|
topic |
String | 要读取的 Kafka topic。要从多个 topic 摄入数据,使用 topicPattern。 |
当 topicPattern 未设置时必填 |
|
topicPattern |
String | 要从多个 topic 摄入数据时,以正则表达式形式传入。详见 多 topic 摄入。 | 当 topic 未设置时必填 |
|
consumerProperties |
String, Object | 传递给 Kafka consumer 的属性映射。详见 消费者属性。 | 必填。至少需设置 bootstrap.servers 以建立与 Kafka 集群的初始连接 |
|
pollTimeout |
Long | 等待 Kafka consumer 轮询记录的时间,单位毫秒。 | 否 | 100 |
useEarliestOffset |
Boolean | 当 supervisor 首次管理某个 datasource 时,会从 Kafka 获取一组起始 offset。该标志决定是取 Kafka 中的最早(earliest)还是最新(latest)offset。正常情况下,后续任务从上一批 segment 结束的位置继续读取。Druid 仅在首次运行时使用 useEarliestOffset。 |
否 | false |
idleConfig |
Object | 定义 Kafka supervisor 何时以及如何进入 idle 状态。详见 Idle 配置。 | 否 | null |
从源码看,这些属性在 KafkaSupervisorIOConfig 中被解析:
consumerProperties通过Preconditions.checkNotNull强制非空,并校验必须包含bootstrap.servers键,否则抛出异常(对应源码中的BOOTSTRAP_SERVERS_KEY常量检查);pollTimeout未指定时使用默认值DEFAULT_POLL_TIMEOUT_MILLIS = 100;topic与topicPattern通过checkTopicArguments静态方法校验:两者必须且只能指定一个——都为空会抛出Either topic or topicPattern must be specified,同时指定则抛出Only one of topic or topicPattern must be specified;isMultiTopic()方法根据topicPattern != null判断是否处于多 topic 模式。
多 topic 摄入
:::info 如果对某个 datasource 启用了多 topic 摄入,降级到 28.0.0 之前的版本将导致该 datasource 的摄入失败。 :::
你可以从一个或多个 topic 摄入数据。从多个 topic 摄入时,Druid 基于 topic 名称的 hashcode 与该 topic 内 partition 的 ID 来分配 partition,因此 partition 在任务间的分配可能并不均匀。Druid 假设各 topic 内的 partition 负载相近。如果希望在同一 supervisor 中同时摄入高负载与低负载 topic,建议高负载 topic 配置更多的 partition、低负载 topic 配置更少的 partition。
使用 topicPattern 代替 topic 即可从多个 topic 摄入,传入多个 topic 的正则表达式。例如,要从 clicks 和 impressions 两个 topic 摄入,将 topicPattern 设为 clicks|impressions;同理,metrics-.* 表示摄入所有以 metrics- 开头的 topic。如果集群中新增了匹配该正则的 topic,Druid 会自动开始摄入新 topic。注意:仅部分匹配的 topic 名称(如 my-metrics-12)不会被摄入。
从源码看,多 topic 模式下 supervisor 会以 KafkaTopicPartition(topic, partitionId) 作为任务分配的最小单元,相关实现位于 KafkaTopicPartition 与 KafkaSeekableStreamStartSequenceNumbers。
消费者属性(consumerProperties)
消费者属性控制 supervisor 如何从 Kafka 流中读取和处理事件消息。关于 consumer 的完整说明可参考 Apache Kafka 官方文档。
consumerProperties 对象必须包含 bootstrap.servers 属性,其形式为 Kafka broker 列表:<BROKER_1>:<PORT_1>,<BROKER_2>:<PORT_2>,...。
默认情况下,isolation.level 被设置为 read_committed——即 Druid 只消费已提交的事务消息。如果你使用的 Kafka 服务端版本较老、不支持事务,或者不希望 Druid 只消费已提交事务,可将 isolation.level 设为 read_uncommitted。如果需要让 Druid 消费更老版本的 Kafka,请确保 offset 是连续的,因为 Druid 内部不做 offset 空洞检查。
如果 Kafka 集群启用了基于 consumer group 的 ACL,可以在 consumerProperties 中设置 group.id 覆盖默认自动生成的 group ID。
运行时动态提供消费者属性
有些场景下需要在运行时获取消费者属性,例如 bootstrap.servers 事先未知或不固定;启用 SSL 连接时,keystore、truststore、key 的密码也需要机密传递。此时可以借助动态配置提供器(dynamic config provider),例如 Druid 自带的环境变量配置提供器。详见 Dynamic config provider。
例如,在运行 Overlord 与 Peon 服务的机器上为 Druid 用户设置以下环境变量,以启用 Kafka 的 SASL 与 SSL:
export KAFKA_JAAS_CONFIG="org.apache.kafka.common.security.plain.PlainLoginModule required username='admin_user' password='admin_password';"
export SSL_KEY_PASSWORD=mysecretkeypassword
export SSL_KEYSTORE_PASSWORD=mysecretkeystorepassword
export SSL_TRUSTSTORE_PASSWORD=mysecrettruststorepassword
然后在 supervisor spec 的 consumerProperties 中通过 druid.dynamic.config.provider 引用这些环境变量:
"druid.dynamic.config.provider": {
"type": "environment",
"variables": {
"sasl.jaas.config": "KAFKA_JAAS_CONFIG",
"ssl.key.password": "SSL_KEY_PASSWORD",
"ssl.keystore.password": "SSL_KEYSTORE_PASSWORD",
"ssl.truststore.password": "SSL_TRUSTSTORE_PASSWORD"
}
}
请务必把上述所有配置值替换为你自己的环境。在 Druid 数据加载界面(data loader)的 Connect tab 的 Consumer properties 字段中,可以直接使用环境变量配置提供器的语法;连接 Kafka 时,Druid 会将环境变量替换为对应的值。
另外,也可以通过 Password provider 接口提供 SSL 连接所需的 keystore、truststore 和 key,但该特性已被标记为废弃(deprecated)。
从源码看,Kafka consumer 的默认配置在 KafkaConsumerConfigs 中统一管理:
metadata.max.age.ms=10000、auto.offset.reset=none、enable.auto.commit=false。其中auto.offset.reset=none意味着当 offset 无效时 consumer 不会自动重置,而是交由 supervisor 的resetOffsetAutomatically逻辑处理;enable.auto.commit=false则保证 offset 推进完全由 Druid 任务在完成 segment 持久化后手动提交,这是 exactly-once 语义的基础。
Idle 配置
:::info Idle 状态切换目前被标记为实验性特性。 :::
当 supervisor 进入 idle 状态后,在当前执行中的任务完成之后不再启动新任务。对于数据稀疏、偶发写入的 topic,这一策略可以降低集群运营成本。
idleConfig 的配置项如下:
| 属性 | 描述 | 必填 | 默认值 |
|---|---|---|---|
enabled |
如果为 true,当输入流或 topic 在一段时间内没有数据时,supervisor 进入 idle 状态。 |
否 | false |
inactiveAfterMillis |
当输入 topic 中所有已有数据均已被读取,且在 inactiveAfterMillis 毫秒内没有新数据发布时,supervisor 进入 idle 状态。 |
否 | 600_000 |
以下示例展示了启用 idle 配置的 supervisor spec(同时演示了任务自动扩缩容 autoScalerConfig 的配置):
{
"type": "kafka",
"spec": {
"dataSchema": { "...": "..." },
"ioConfig": {
"topic": "metrics",
"inputFormat": { "type": "json" },
"consumerProperties": {
"bootstrap.servers": "localhost:9092"
},
"autoScalerConfig": {
"enableTaskAutoScaler": true,
"taskCountMax": 6,
"taskCountMin": 2,
"minTriggerScaleActionFrequencyMillis": 600000,
"autoScalerStrategy": "lagBased",
"lagCollectionIntervalMillis": 30000,
"lagCollectionRangeMillis": 600000,
"scaleOutThreshold": 6000000,
"triggerScaleOutFractionThreshold": 0.3,
"scaleInThreshold": 1000000,
"triggerScaleInFractionThreshold": 0.9,
"scaleActionStartDelayMillis": 300000,
"scaleActionPeriodMillis": 60000,
"scaleInStep": 1,
"scaleOutStep": 2
},
"taskCount": 1,
"replicas": 1,
"taskDuration": "PT1H",
"idleConfig": {
"enabled": true,
"inactiveAfterMillis": 600000
}
},
"tuningConfig": { "...": "..." }
}
}
关于任务自动扩缩容(autoScalerConfig)各参数的完整说明,参见 Supervisor Task autoscaler:Druid 目前仅支持 lagBased 策略,依据 lagCollectionIntervalMillis(默认 30000ms)与 lagCollectionRangeMillis(默认 600000ms)收集 lag 指标点,结合 scaleOutThreshold/triggerScaleOutFractionThreshold 与 scaleInThreshold/triggerScaleInFractionThreshold 判断扩容/缩容,并支持 scaleInStep(默认 1)、scaleOutStep(默认 2)控制每次调整的任务数。
数据格式与 Kafka 输入格式
Kafka indexing service 同时支持 inputFormat 与旧版 parser 两种方式来指定数据格式。除非你需要使用仅旧版 parser 支持的格式,否则应使用 inputFormat。详见 Source input formats。
inputFormat 支持的值包括:
csvtvsjsonkafkaavro_streamprotobuf
(另可用 parser 读取 thrift 格式。)
Kafka 输入格式(kafka input format)
kafka 输入格式在解析 Kafka payload 值内容之外,还可以解析 Kafka 元数据字段。它包装在 payload 解析输入格式的外层,将 Kafka 事件时间戳、Kafka topic 名称、Kafka 事件 headers,以及 key 字段(key 本身可以用任意可用输入格式解析)追加到输出数据中。
例如,考虑一条代表开发环境中 wiki 编辑记录的 Kafka 消息,其结构如下:
- Kafka timestamp:
1680795276351 - Kafka topic:
wiki-edits - Kafka headers:
env=developmentzone=z1
- Kafka key:
wiki-edit - Kafka payload value:
{"channel":"#sv.wikipedia","timestamp":"2016-06-27T00:00:11.080Z","page":"Salo Toraut","delta":31,"namespace":"Main"}
如果使用 { "type": "json" } 作为输入格式,则只能解析 payload 值。要同时解析 Kafka 元数据,应使用 kafka 输入格式,其配置字段如下:
-
valueFormat:定义如何解析 payload 值,设置为 payload 解析输入格式(如{ "type": "json" })。 -
timestampColumnName:为 Druid schema 中的 Kafka 时间戳列指定自定义名称,避免与 payload 中的列冲突。默认值为kafka.timestamp。 -
topicColumnName:为 Druid schema 中的 Kafka topic 列指定自定义名称,避免与 payload 中的列冲突。默认值为kafka.topic。当从多个 topic 摄入数据到同一 datasource 时该字段非常有用。 -
headerFormat:默认值string表示以 UTF-8 编码从 Kafka header 解码字符串。其他支持的编码格式包括:ISO-8859-1:ISO Latin Alphabet No. 1,即 ISO-LATIN-1。US-ASCII:七位 ASCII,又称 ISO646-US,即 Unicode 字符集的 Basic Latin 块。UTF-16:十六位 UCS 转换格式,字节序由可选的字节序标记识别。UTF-16BE:十六位 UCS 转换格式,大端字节序。UTF-16LE:十六位 UCS 转换格式,小端字节序。
-
headerColumnPrefix:为 Kafka headers 提供前缀,避免与 payload 中的列冲突。默认值为kafka.header.。以上述示例消息为例,Druid 将 headers 映射为kafka.header.env、kafka.header.zone两列。 -
keyFormat:提供用于解析 key 的输入格式,只使用第一个值。如果如示例中所示 key 值是简单字符串,可以使用tsv格式解析:{ "type": "tsv", "findColumnsFromHeader": false, "columns": ["x"] }注意:对于
tsv、csv、regex格式,需要提供columns数组才能构成合法输入格式;其中只有第一个被使用,且其名称会被忽略,改用keyColumnName。 -
keyColumnName:为 Kafka key 列指定名称,避免与 payload 中的列冲突。默认值为kafka.key。
以下输入格式对 timestampColumnName、topicColumnName、headerColumnPrefix 与 keyColumnName 均采用默认值:
{
"type": "kafka",
"valueFormat": { "type": "json" },
"headerFormat": { "type": "string" },
"keyFormat": {
"type": "tsv",
"findColumnsFromHeader": false,
"columns": ["x"]
}
}
它会把示例消息解析为如下行:
{
"channel": "#sv.wikipedia",
"timestamp": "2016-06-27T00:00:11.080Z",
"page": "Salo Toraut",
"delta": 31,
"namespace": "Main",
"kafka.timestamp": 1680795276351,
"kafka.topic": "wiki-edits",
"kafka.header.env": "development",
"kafka.header.zone": "z1",
"kafka.key": "wiki-edit"
}
最后,将这些 Kafka 元数据列加入 dimensionsSpec,或将 dimensionsSpec 设置为自动探测列。
以下 supervisor spec 演示了如何把 Kafka header、key、timestamp、topic 摄入为 Druid 维度:
{
"type": "kafka",
"spec": {
"ioConfig": {
"type": "kafka",
"consumerProperties": {
"bootstrap.servers": "localhost:9092"
},
"topic": "wiki-edits",
"inputFormat": {
"type": "kafka",
"valueFormat": { "type": "json" },
"headerFormat": { "type": "string" },
"keyFormat": {
"type": "tsv",
"findColumnsFromHeader": false,
"columns": ["x"]
}
},
"useEarliestOffset": true
},
"dataSchema": {
"dataSource": "wikiticker",
"timestampSpec": {
"column": "timestamp",
"format": "posix"
},
"dimensionsSpec": {
"useSchemaDiscovery": true,
"includeAllDimensions": true
},
"granularitySpec": {
"queryGranularity": "none",
"rollup": false,
"segmentGranularity": "day"
}
},
"tuningConfig": {
"type": "kafka"
}
}
}
Druid 摄入完成后,可以这样查询 Kafka 元数据列:
SELECT
"kafka.header.env",
"kafka.key",
"kafka.timestamp",
"kafka.topic"
FROM "wikiticker"
查询结果为:
kafka.header.env |
kafka.key |
kafka.timestamp |
kafka.topic |
|---|---|---|---|
development |
wiki-edit |
1680795276351 |
wiki-edits |
Kafka 输入格式的源码实现
从源码看,kafka 输入格式由 KafkaInputFormat 实现:
- 四个默认列名以常量形式定义:
kafka.header.(header 前缀)、kafka.timestamp、kafka.topic、kafka.key,与文档描述一致; valueFormat通过Preconditions.checkNotNull强制非空,是整个输入格式的必选部分;- header 解析器由 KafkaStringHeaderFormat 实现,未指定
encoding时默认使用UTF-8,与文档中headerFormat默认值string对应; - 实际的行混合逻辑在 KafkaInputReader 中完成:
extractHeaderAndKeys将 header、record timestamp、topic 与 key 合并到一张mergedHeaderMap中,其中 timestamp 与 topic 只在同名键不存在时通过putIfAbsent写入,避免与 header/payload 列冲突;key 解析只取第一行("Key currently only takes the first row and ignores the rest");随后buildBlendedRows将 payload 解析结果与元数据 map 混合,生成最终的MapBasedInputRow; - 需要注意,key 解析要求输入格式返回
MapBasedInputRow类型的行,否则抛出Unsupported keyFormat异常(对应源码中buildBlendedEventMap前对 key 行的ClassCastException捕获)。这些行为均有对应的单元测试,例如 KafkaInputFormatTest 与 KafkaStringHeaderFormatTest。
Tuning 配置(tuningConfig)
下表列出 Kafka 专属的 tuningConfig 属性;共享属性参见 Supervisor tuning configuration。
| 属性 | 类型 | 描述 | 必填 | 默认值 |
|---|---|---|---|---|
numPersistThreads |
Integer | 用于创建并持久化增量 segment 到磁盘的线程数。摄入吞吐越高,增量 segment 数量越多,创建增量 segment 会消耗大量 CPU。对于列数成百上千的 datasource,增量 segment 的创建可能耗时数秒。这两种场景下摄入可能频繁停滞或暂停,导致落后。只要 CPU 资源充足,可以使用额外线程并行化 segment 创建,避免阻塞摄入。 | 否 | 1 |
chatAsync |
Boolean | 如果为 true,使用与索引任务之间的异步通信,并忽略 chatThreads 参数;如果为 false,使用大小为 chatThreads 的线程池进行同步通信。 |
否 | true |
chatThreads |
Integer | 用于与索引任务通信的线程数。当 chatAsync 为 true 时忽略。 |
否 | min(10, taskCount * replicas) |
从源码看,supervisor 级
tuningConfig由 KafkaSupervisorTuningConfig 承载,它继承了 KafkaIndexTaskTuningConfig,并额外定义了 supervisor 运行所需的通信参数:workerThreads、chatRetries(默认 8)、httpTimeout(默认PT10S)、shutdownTimeout(默认PT80S)、offsetFetchPeriod(默认PT30S)。这些默认值定义在 SeekableStreamSupervisorTuningConfig(DEFAULT_CHAT_RETRIES = 8、DEFAULT_HTTP_TIMEOUT = "PT10S"、DEFAULT_SHUTDOWN_TIMEOUT = "PT80S"、DEFAULT_OFFSET_FETCH_PERIOD = "PT30S"),并在构造时通过defaultDuration兜底。任务真正执行时,convertToTaskTuningConfig()会把 supervisor 配置转换为任务级 tuning config 下发给KafkaIndexTask。
共享 tuning 配置要点
以下属性对 Kafka 与 Kinesis 均适用,在配置 Kafka 摄入时同样关键:
| 属性 | 默认值 | 说明 |
|---|---|---|
maxRowsInMemory |
150000 | 内存中累积多少行(聚合后行数)后触发持久化。最大堆内存占用约为 maxRowsInMemory * (2 + maxPendingPersists)。 |
maxBytesInMemory |
JVM 最大内存的六分之一 | 持久化前在堆内存中累积的字节数(粗略估算)。最大堆内存占用约为 maxBytesInMemory * (2 + maxPendingPersists)。 |
maxRowsPerSegment |
5000000 | 单个 segment 存储的行数(聚合后)。达到 maxRowsPerSegment、maxTotalRows 或间隔 intermediateHandoffPeriod 三者之一即触发 handoff。 |
maxTotalRows |
20000000 | 所有 segment 累计的行数(聚合后),达到即触发 handoff。 |
intermediateHandoffPeriod |
P2147483647D |
任务每隔该周期执行一次 segment handoff。 |
intermediatePersistPeriod |
PT10M |
中间持久化的执行频率。 |
maxPendingPersists |
0 | 允许排队未开始的持久化最大数量,超出则阻塞摄入直到当前持久化完成。 |
handoffConditionTimeout |
Kafka 为 900000(15 分钟) | 等待 segment handoff 的毫秒数;0 表示无限等待。 |
resetOffsetAutomatically |
false |
当 sequence number 不可用时是否重置 partition;为 false 时任务失败并停止摄入,需要人工干预(例如通过 重置 supervisor)。 |
offsetFetchPeriod |
PT30S |
supervisor 查询流与任务获取当前 offset、计算 lag 的频率;低于 PT5S 的值会被忽略并采用最小值。 |
logParseExceptions / maxParseExceptions / maxSavedParseExceptions |
false / 无限制 / 0 |
解析异常的处理策略:是否记录、超过多少停止摄入、保存多少个最近的异常实例供任务报告查询。 |
完整参数表参见 Supervisor tuning configuration。
Kafka partition 与 Druid segment 的部署要点
Druid 将 Kafka partition 分配给每个 Kafka 索引任务。任务将消费到的事件写入单个 segment(对应 segment granularity 区间),直到达到以下任一限制:maxRowsPerSegment、maxTotalRows 或 intermediateHandoffPeriod。此时,任务会为该 segment granularity 新建一个 partition 以容纳后续事件。
Kafka 索引任务还支持增量 handoff(incremental handoffs):segment 就绪即发布,无需等待任务结束时才统一发布。当任务达到 maxRowsPerSegment、maxTotalRows 或 intermediateHandoffPeriod 时,它会将当前所有 segment 全部 handoff,并为后续事件创建新的一组 segment。这使得任务可以运行更长时间,而无需在 MiddleManager 上累积旧 segment。
Kafka indexing service 仍可能产生一些小 segment。例如以下场景:
- 任务时长为 4 小时;
- segment granularity 设为 HOUR;
- supervisor 在 9:10 启动。
4 小时后(13:10),Druid 会启动新的一组任务。区间 13:00–14:00 的事件可能被拆分到现有任务与新任务中,从而产生小 segment。要将其合并为理想大小(约 500–700 MB/segment)的新 segment,可以调度 re-indexing 任务,并可选地使用不同的 segment granularity。
关于如何优化 segment 大小,参见 Segment size optimization。
Supervisor 的运行机制与运维
启动与生命周期
当 Overlord 获得领导权(启动或另一台 Overlord 故障转移)时,它会为元数据库中的每个 supervisor spec 派生一个 supervisor。supervisor 会发现正在运行的索引任务并尝试收养它们(若与配置兼容);不兼容则终止任务并创建新任务集。因此,supervisor 摄入任务能够跨 Overlord 重启与故障转移存活。
注意:每个 datasource 只能有一个 supervisor,再次提交同 datasource 的 spec 会覆盖前一个。提交新 spec 后,Overlord 会对现有 supervisor 发起优雅关闭——任务停止读取并开始发布,然后以新配置创建新 supervisor。Druid 在保留现有发布任务的同时应用新 schema,并让新任务从上一任务的 offset 继续读取,因此配置变更无需暂停摄入。
状态报告
supervisor 状态报告包含任务状态与最近抛出的异常数组(recentErrors)。报告中 state 与 detailedState 两个属性描述 supervisor 状态:
state的可能取值:PENDING、RUNNING、SUSPENDED、STOPPING、UNHEALTHY_SUPERVISOR、UNHEALTHY_TASKS;detailedState提供更细粒度的实现级状态,例如UNABLE_TO_CONNECT_TO_STREAM、LOST_CONTACT_WITH_STREAM、CONNECTING_TO_STREAM、DISCOVERING_INITIAL_TASKS、CREATING_TASKS、IDLE等,其与state的映射关系详见 Supervisor 状态报告。
在 supervisor 的每个运行循环迭代中,会依次完成:获取 partition 列表与各 partition 起始 offset → 发现并收养/停止运行中的任务 → 向每个受管任务发送状态请求 → 处理超过 taskDuration 的任务(从读取转入发布)→ 处理已完成发布的任务并让冗余副本停止 → 处理失败任务并清理内部状态 → 将健康任务数与 taskCount/replicas 对比,按需创建新任务。
对于 Kafka indexing service,若 supervisor 尚未收到 Kafka 的最新 offset 响应,单 partition 的 consumer lag 可能显示为负值,但聚合 lag 始终 >= 0。
容量规划
索引任务运行在 MiddleManager 上,受 druid.worker.capacity 限制。运行中的任务处于**读取(reading)或发布(publishing)**两种状态:任务在 taskDuration 期间保持读取状态,随后转入发布状态(生成 segment、推送到 deep storage、加载到 Historical),直至完成或 completionTimeout 超时。读取任务数量由 replicas * taskCount 决定(若 taskCount 超过 Kafka partition 数则取 partition 数)。为支持读写任务并行,最低容量要求为:
workerCapacity = 2 * replicas * taskCount
如果发布耗时(生成 segment、推送到 deep storage、加载到 Historical)大于 taskDuration,可能出现多组任务同时发布的合法场景,但需要额外的 worker 容量。一般建议让 taskDuration 足够大,使上一组任务在当前组开始前完成发布。完整的容量规划分析参见 Supervisor capacity planning。
常用管理操作
supervisor 支持通过 Web 控制台 Supervisors 视图或 Supervisor API 进行管理:
- Suspend(挂起):暂停运行中的 supervisor,任务保持挂起直到恢复,日志与指标继续输出;
- Set offsets(设置 offset):重置指定 partition 的 offset,终止并重建这些 partition 的活动任务,使其从指定 offset 开始读取。操作需谨慎,可能导致消息跳过、数据丢失或重复;
- Hard reset(硬重置):清除 supervisor 元数据,使其依据
useEarliestOffset从最早或最新位置重新读取,同时终止并重建活动任务。用于从 offset 缺失导致的停止状态恢复,同样需谨慎操作; - Terminate(终止):停止 supervisor 及其索引任务并触发 segment 发布,在元数据库写入 tombstone 标记防止重启后重新加载;已终止的 supervisor 仍保留在元数据库,可检索其历史。
小结与延伸阅读
本文完整覆盖了 Apache Druid Kafka indexing service 的 supervisor spec 配置:从扩展加载、ioConfig(topic/topicPattern、consumerProperties、pollTimeout、useEarliestOffset、idleConfig),到 Kafka 输入格式的元数据解析(timestamp/topic/header/key),再到 tuningConfig 的持久化与通信参数,以及 partition 与 segment 的部署要点。仓库源码(KafkaSupervisorIOConfig、KafkaSupervisorTuningConfig、KafkaInputFormat)印证了各配置项的校验逻辑与默认值。
进一步学习可参考:
- Supervisor API:使用 API 管理与监控 supervisor;
- Supervisor:supervisor 状态与容量规划;
- 从 Apache Kafka 加载数据教程:从 Apache Kafka 流式摄入数据的实战演练;
- Source input formats:
kafka输入格式及其他数据格式的详细说明。