Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

使用 ClickStack 监控 MongoDB 日志

View as MarkdownEdit this pageReport an issueSet up docs MCP

与现有 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：

# For systemd
sudo systemctl restart mongod

# For 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

配置 ClickStack 以加载自定义配置

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

  1. 将自定义配置文件挂载到 /etc/otelcol-contrib/custom.config.yaml
  2. 设置环境变量 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. 挂载 MongoDB 的日志目录，以便 collector 读取其中的日志

更新 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
      # ... 其他卷 ...

在 HyperDX 中验证日志

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

MongoDB 日志搜索视图
MongoDB 日志详情视图

演示数据集

在配置生产系统之前，先使用预先生成的演示数据集测试 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 运行后：

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

仪表盘和可视化

下载仪表盘配置

下载仪表盘配置文件。

导入预置仪表盘

  1. 打开 HyperDX，进入 Dashboards 部分。
  2. 点击右上角省略号菜单中的“导入仪表盘”。
导入仪表盘
  1. 上传 mongodb-logs-dashboard.json 文件，然后点击完成导入。
完成导入 MongoDB 日志仪表盘

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

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

MongoDB 日志仪表盘

故障排查

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

Navigation