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

​
与现有 MongoDB 集成

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

​
前置条件

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

​
验证 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>
2

​
为 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，以避免收集器重启时重新摄取日志。
3

​
配置 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
      # ... 其他卷 ...
请确保 ClickStack collector 具有读取 MongoDB 日志文件的相应权限。在生产环境中，请使用只读挂载 (:ro) ，并遵循最小权限原则。
4

​
在 HyperDX 中验证日志

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

​
演示数据集

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

​
下载样本数据集

下载示例日志文件：
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mongodb/mongod.log
2

​
创建测试 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
3

​
使用演示配置运行 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)

​
仪表盘和可视化

1

​
仪表盘配置

2

​
导入预建仪表盘

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

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

对于演示数据集，将时间范围设置为 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 数据。
最后修改于 2026年6月10日