使用 ClickStack 监控 MongoDB 日志 - ClickHouse Documentation

简而言之使用 OTel filelog 接收器在 ClickStack 中收集并可视化 MongoDB 服务器日志 (4.4+ JSON 格式) 。包含演示数据集和预置仪表盘。

与现有 MongoDB 集成

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

前置条件

正在运行的 ClickStack 实例
现有的自管理 MongoDB 安装 (4.4 或更高版本)
具有访问 MongoDB 日志文件的权限

验证 MongoDB 日志配置

MongoDB 4.4+ 默认输出结构化的 JSON 日志。请检查日志文件的位置：

cat /etc/mongod.conf | grep -A 5 systemLog

常见的 MongoDB 日志路径：

Linux (apt/yum): /var/log/mongodb/mongod.log
macOS (Homebrew): /usr/local/var/log/mongodb/mongo.log
Docker: 通常会输出到 stdout，但也可以配置为写入 /var/log/mongodb/mongod.log

如果 MongoDB 当前将日志输出到 stdout，请更新 mongod.conf，将其配置为写入文件：

systemLog:
  destination: file
  path: /var/log/mongodb/mongod.log
  logAppend: true

更改配置后，重新启动 MongoDB：

# 适用于 systemd
sudo systemctl restart mongod

# 适用于 Docker
docker restart <mongodb-container>

为 MongoDB 创建自定义 OTel collector 配置

ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。自定义配置会与由 HyperDX 通过 OpAMP 管理的基础配置合并。创建一个名为 mongodb-monitoring.yaml 的文件，内容如下：

receivers:
  filelog/mongodb:
    include:
      - /var/log/mongodb/mongod.log
    start_at: beginning
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.t.$$date
          layout: '2006-01-02T15:04:05.000-07:00'
          layout_type: gotime
        severity:
          parse_from: attributes.s
          overwrite_text: true
          mapping:
            fatal: F
            error: E
            warn: W
            info: I
            debug:
              - D1
              - D2
              - D3
              - D4
              - D5

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

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

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

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

你只需在自定义配置中定义新的接收器和管道。处理器 (memory_limiter、transform、batch) 和导出器 (clickhouse) 已在 ClickStack 的基础配置中定义好——你只需按名称引用即可。
此配置使用 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
挂载 MongoDB 的日志目录，以便 collector 读取其中的日志

Docker Compose
Docker Run (一体化镜像)

更新 ClickStack 部署配置：

services:
  clickstack:
    # ... 现有配置 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... 其他环境变量 ...
    volumes:
      - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/mongodb:/var/log/mongodb: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)/mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/mongodb:/var/log/mongodb:ro \
  clickhouse/clickstack-all-in-one:latest

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

在 HyperDX 中验证日志

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

演示数据集

在配置生产系统之前，先使用预先生成的演示数据集测试 MongoDB 集成。

下载样本数据集

下载示例日志文件：

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

创建测试 collector 配置

创建一个名为 mongodb-demo.yaml 的文件，并填入以下配置：

cat > mongodb-demo.yaml << 'EOF'
receivers:
  filelog/mongodb:
    include:
      - /tmp/mongodb-demo/mongod.log
    start_at: beginning
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.t.$$date
          layout: '2006-01-02T15:04:05.000-07:00'
          layout_type: gotime
        severity:
          parse_from: attributes.s
          overwrite_text: true
          mapping:
            fatal: F
            error: E
            warn: W
            info: I
            debug:
              - D1
              - D2
              - D3
              - D4
              - D5

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

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

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

service:
  pipelines:
    logs/mongodb-demo:
      receivers: [filelog/mongodb]
      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)/mongodb-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/mongod.log:/tmp/mongodb-demo/mongod.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，进入 Dashboards 部分。
点击右上角省略号菜单中的“Import Dashboard”。

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

仪表盘创建后将预先配置好所有可视化项

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

故障排查

HyperDX 中未显示任何日志

请确认生效的配置中包含 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

日志解析不正确

确认 MongoDB 正在输出 JSON 日志 (4.4+) ：

tail -1 /var/log/mongodb/mongod.log | python3 -m json.tool

如果输出不是有效的 JSON，可能是因为你的 MongoDB 版本使用的是旧版文本日志格式 (4.4 之前的版本) 。你需要将 json_parser operator 替换为 regex_parser，或者将 MongoDB 升级到 4.4 及以上版本。

后续步骤

为关键事件设置告警 (如错误激增、慢查询阈值)
针对特定用例创建更多仪表盘 (如副本集监控、连接跟踪)

进入生产环境

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

​与现有 MongoDB 集成

​前置条件

​验证 MongoDB 日志配置

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

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

​在 HyperDX 中验证日志

​演示数据集

​下载样本数据集

​创建测试 collector 配置

​使用演示配置运行 ClickStack

​在 HyperDX 中验证日志

​仪表盘和可视化

​ 仪表盘配置

​导入预建仪表盘

​仪表盘创建后将预先配置好所有可视化项

​故障排查

​HyperDX 中未显示任何日志

​日志解析不正确

​后续步骤

​进入生产环境

与现有 MongoDB 集成

前置条件

验证 MongoDB 日志配置

为 MongoDB 创建自定义 OTel collector 配置

配置 ClickStack 以加载自定义配置

在 HyperDX 中验证日志

演示数据集

下载样本数据集

创建测试 collector 配置

使用演示配置运行 ClickStack

在 HyperDX 中验证日志

仪表盘和可视化

仪表盘配置

导入预建仪表盘

仪表盘创建后将预先配置好所有可视化项

故障排查

HyperDX 中未显示任何日志

日志解析不正确

后续步骤

进入生产环境