使用 ClickStack 监控 Kafka 日志

与现有 Kafka 集成

本节介绍如何通过修改 ClickStack OTel collector 配置，将现有 Kafka 部署中的 broker 日志发送到 ClickStack。如果您想在配置自己的现有环境之前先测试 Kafka 日志集成，可以先在“演示数据集”部分使用我们预先配置的环境和示例数据进行测试。

前置条件

ClickStack 实例正在运行
已有 Kafka 安装 (2.0 或更高版本)
可访问 Kafka 的日志文件 (server.log、controller.log 等)

验证 Kafka 日志配置

Kafka 使用 Log4j，并将日志写入由系统属性 kafka.logs.dir 或环境变量 LOG_DIR 指定的目录。请检查日志文件的位置：

# Default locations
ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
ls /var/log/kafka/        # RPM/DEB package installations

Kafka 的关键日志文件：

server.log：通用 broker 日志 (启动、连接、复制、错误)
controller.log：控制器相关事件 (leader 选举、分区重新分配)
state-change.log：分区和副本的状态转换

Kafka 默认的 Log4j pattern 会生成类似下面这样的行：

[2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)

为 Kafka 创建自定义 OTel collector 配置

ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。该自定义配置会与由 HyperDX 通过 OpAMP 管理的基础配置合并。

创建一个名为 kafka-logs-monitoring.yaml 的文件，内容如下：

receivers:
  filelog/kafka:
    include:
      - /var/log/kafka/server.log
      - /var/log/kafka/controller.log  # optional, only exists if log4j is configured with separate file appenders
      - /var/log/kafka/state-change.log  # optional, same as above
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

      - type: move
        from: attributes.message
        to: body

      - type: add
        field: attributes.source
        value: "kafka"

      - type: add
        field: resource["service.name"]
        value: "kafka-production"

service:
  pipelines:
    logs/kafka:
      receivers: [filelog/kafka]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

配置 ClickStack 以加载自定义配置

要在现有的 ClickStack 部署中启用自定义 collector 配置，您需要：

将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
挂载 Kafka 日志目录，以便 collector 能够读取日志

更新 ClickStack 部署配置：

services:
  clickstack:
    # ... 现有配置 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... 其他环境变量 ...
    volumes:
      - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/kafka:/var/log/kafka:ro
      # ... 其他卷 ...

如果您使用的是 Docker 的 all-in-one 镜像，请运行：

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/kafka:/var/log/kafka:ro \
  clickhouse/clickstack-all-in-one:latest

在 HyperDX 中验证日志

配置完成后，登录 HyperDX，确认日志已开始流入：

演示数据集

在配置生产系统之前，先使用预生成的样本数据集测试 Kafka 日志集成。

下载样本数据集

下载样本日志文件：

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log

创建测试用 collector 配置

创建一个名为 kafka-logs-demo.yaml 的文件，内容如下：

cat > kafka-logs-demo.yaml << 'EOF'
receivers:
  filelog/kafka:
    include:
      - /tmp/kafka-demo/server.log
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

      - type: move
        from: attributes.message
        to: body

      - type: add
        field: attributes.source
        value: "kafka-demo"

      - type: add
        field: resource["service.name"]
        value: "kafka-demo"

service:
  pipelines:
    logs/kafka-demo:
      receivers: [filelog/kafka]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

使用演示配置运行 ClickStack

使用演示日志和配置运行 ClickStack：

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
  clickhouse/clickstack-all-in-one:latest

在 HyperDX 中验证日志

ClickStack 运行后：

打开 HyperDX 并登录你的账户 (你可能需要先创建一个账户)
进入搜索视图，并将数据源设为 Logs
将时间范围设置为包含 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

仪表盘与可视化

下载仪表盘配置

下载仪表盘配置文件。

导入预置仪表盘

打开 HyperDX，进入“仪表盘”部分。
点击右上角省略号下方的“导入仪表盘”。

上传 kafka-logs-dashboard.json 文件，然后点击“完成导入”。

仪表盘将创建完成，且所有可视化均已预先配置

对于演示数据集，请将时间范围设置为 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)。

故障排查

确认生效的配置中包含您的 filelog 接收器：

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

检查 collector 错误：

docker exec <container> cat /etc/otel/supervisor-data/agent.log

验证 Kafka 日志格式是否符合预期模式：

tail -1 /var/log/kafka/server.log

如果你的 Kafka 安装使用了自定义的 Log4j 格式，请相应调整 regex_parser 中的正则表达式。

后续步骤

为关键事件 (broker 故障、复制错误、消费者组问题) 设置告警
结合 Kafka Metrics 进行全面的 Kafka 监控
针对特定场景 (controller 事件、分区重新分配) 创建更多仪表盘

投入生产环境

本指南使用 ClickStack 内置的 OpenTelemetry Collector 进行快速设置。对于生产环境部署，我们建议运行您自己的 OTel Collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅发送 OpenTelemetry 数据。