使用 ClickStack 监控 Kafka 日志

简述

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

与现有 Kafka 集成

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

前提条件

正在运行的 ClickStack 实例
已安装 Kafka (版本 2.0 或更高)
具有访问 Kafka 日志 File (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 模式生成如下格式的日志行：

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

注意

对于基于 Docker 的 Kafka 部署 (例如 confluentinc/cp-kafka) ，默认的 Log4j 配置仅包含控制台追加器 (console appender) ，不包含文件追加器 (file appender) ，因此日志只会写入 stdout。若要使用 filelog 接收器，需要将日志重定向到文件，可通过在 log4j.properties 中添加文件追加器，或将 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  # 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

注意

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

配置 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 运行一体化镜像，请执行：

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 并登录您的账户 (您可能需要先创建账户)
进入 Search 视图，并将 source 设置为 Logs
将时间范围设置为包含 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)

仪表板和可视化

下载仪表板配置

导入预构建的仪表板

打开 HyperDX 并导航到 Dashboards 部分。
点击右上角省略号下方的“Import Dashboard”。

上传 kafka-logs-dashboard.json File，然后点击完成导入。

仪表板将被创建，并且所有可视化都已预先配置好

对于演示数据集，将时间范围设置为包含 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 指标对 Kafka 进行全面监控
为特定用例 (控制器事件、分区重新分配) 创建更多仪表板

生产环境部署

本指南利用 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 中验证日志

仪表板和可视化

下载仪表板配置

导入预构建的仪表板

仪表板将被创建，并且所有可视化都已预先配置好

故障排查

后续步骤

生产环境部署