使用 ClickStack 监控 Kafka 日志 - ClickHouse Documentation

摘要使用 OTel filelog 接收器在 ClickStack 中采集并可视化 Kafka Broker 日志 (Log4j 格式) 。包含演示数据集和预置仪表盘。

与现有 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 指定的目录。请检查日志文件的位置：

# 默认位置
ls $KAFKA_HOME/logs/      # 标准 Apache Kafka（默认路径为 <install-dir>/logs/）
ls /var/log/kafka/        # RPM/DEB 软件包安装

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)

对于基于 Docker 的 Kafka 部署 (例如 confluentinc/cp-kafka) ，默认的 Log4j 配置只包含控制台 appender，不包含文件 appender，因此日志只会写入 stdout。要使用 filelog receiver，需要将日志重定向到文件，可通过在 log4j.properties 中添加文件 appender，或将 stdout 通过管道写入文件 (例如 | tee /var/log/kafka/server.log) 。

为 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  # 可选，仅在 log4j 配置了独立文件 appender 时存在
      - /var/log/kafka/state-change.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"

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

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

你只需在自定义配置中定义新的 receiver 和管道。处理器 (memory_limiter、transform、batch) 和 exporter (clickhouse) 已在基础 ClickStack 配置中预先定义好——你只需按名称引用它们。
multiline 配置可确保将堆栈跟踪捕获为一条日志记录。
此配置使用 start_at: beginning，以便在采集器启动时读取所有现有日志。对于生产环境中的部署，请改为 start_at: end，以避免在采集器重启时重复摄取日志。

配置 ClickStack 以加载自定义配置

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

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

Docker Compose
Docker Run（All-in-One 镜像）

更新 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

请确保 ClickStack collector 具有读取 Kafka 日志文件的相应权限。在生产环境中，请使用只读挂载 (:ro) ，并遵循最小权限原则。

在 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 数据。

​与现有 Kafka 集成

​前置条件

​验证 Kafka 日志配置

​为 Kafka 创建自定义 OTel collector 配置

​配置 ClickStack 以加载自定义配置

​在 HyperDX 中验证日志

​演示数据集

​下载样本数据集

​创建测试用 collector 配置

​使用演示配置运行 ClickStack

​在 HyperDX 中验证日志

​仪表盘与可视化

​ 仪表盘配置

​导入预构建仪表盘

​仪表盘创建后，所有可视化均已预先配置

​故障排查

​后续步骤

​进入生产环境

与现有 Kafka 集成

前置条件

验证 Kafka 日志配置

为 Kafka 创建自定义 OTel collector 配置

配置 ClickStack 以加载自定义配置

在 HyperDX 中验证日志

演示数据集

下载样本数据集

创建测试用 collector 配置

使用演示配置运行 ClickStack

在 HyperDX 中验证日志

仪表盘与可视化

仪表盘配置

导入预构建仪表盘

仪表盘创建后，所有可视化均已预先配置

故障排查

后续步骤

进入生产环境