> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 ClickStack 监控 MongoDB 日志

> 使用 ClickStack 监控 MongoDB 日志

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<Info>
  **简而言之**

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

<div id="existing-mongodb">
  ## 与现有 MongoDB 集成
</div>

本节介绍如何通过修改 ClickStack OTel collector 的配置，将您现有的 MongoDB 部署配置为向 ClickStack 发送日志。
如果您想先测试 MongoDB 集成，再配置自己的现有环境，可以在["演示数据集"](/zh/clickstack/integration-examples/mongodb-logs#demo-dataset)部分使用我们预先配置的环境和示例数据进行测试。

<div id="prerequisites">
  ### 前置条件
</div>

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

<Steps>
  <Step>
    #### 验证 MongoDB 日志配置

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

    ```bash theme={null}
    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`，将其配置为写入文件：

    ```yaml theme={null}
    systemLog:
      destination: file
      path: /var/log/mongodb/mongod.log
      logAppend: true
    ```

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

    ```bash theme={null}
    # 适用于 systemd
    sudo systemctl restart mongod

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

  <Step>
    #### 为 MongoDB 创建自定义 OTel collector 配置

    ClickStack 支持通过挂载自定义配置文件并设置环境变量来扩展基础 OpenTelemetry Collector 配置。自定义配置会与由 HyperDX 通过 OpAMP 管理的基础配置合并。

    创建一个名为 `mongodb-monitoring.yaml` 的文件，内容如下：

    ```yaml theme={null}
    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
    ```

    <Note>
      * 你只需在自定义配置中定义新的接收器和管道。处理器 (`memory_limiter`、`transform`、`batch`) 和导出器 (`clickhouse`) 已在 ClickStack 的基础配置中定义好——你只需按名称引用即可。
      * 此配置使用 `start_at: beginning`，以便在收集器启动时读取所有现有日志。对于生产环境中的部署，请改为 `start_at: end`，以避免收集器重启时重新摄取日志。
    </Note>
  </Step>

  <Step>
    #### 配置 ClickStack 以加载自定义配置

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

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

    <Tabs>
      <Tab title="Docker Compose">
        更新 ClickStack 部署配置：

        ```yaml theme={null}
        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
              # ... 其他卷 ...
        ```
      </Tab>

      <Tab title="Docker Run (一体化镜像)">
        如果您使用 Docker 运行一体化镜像，请执行：

        ```bash theme={null}
        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
        ```
      </Tab>
    </Tabs>

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

  <Step>
    #### 在 HyperDX 中验证日志

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/mongodb/search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=44947436c39c45973858dd912f4258b0" alt="MongoDB 日志搜索视图" width="3808" height="1934" data-path="images/clickstack/mongodb/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/mongodb/log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=f220701b68f6b12d34aa59d9263912b5" alt="MongoDB 日志详情视图" width="3808" height="1934" data-path="images/clickstack/mongodb/log-view.png" />
  </Step>
</Steps>

<div id="demo-dataset">
  ## 演示数据集
</div>

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

<Steps>
  <Step>
    #### 下载样本数据集

    下载示例日志文件：

    ```bash theme={null}
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/mongodb/mongod.log
    ```
  </Step>

  <Step>
    #### 创建测试 collector 配置

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

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step>
    #### 使用演示配置运行 ClickStack

    使用演示日志和配置运行 ClickStack：

    ```bash theme={null}
    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](http://localhost:8080/) 并登录您的账户 (您可能需要先创建一个账户)
    2. 进入搜索视图，并将数据源设为 `Logs`
    3. 将时间范围设置为包含 **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/mongodb/search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=44947436c39c45973858dd912f4258b0" alt="MongoDB 日志搜索视图" width="3808" height="1934" data-path="images/clickstack/mongodb/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/mongodb/log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=f220701b68f6b12d34aa59d9263912b5" alt="MongoDB 日志详情视图" width="3808" height="1934" data-path="images/clickstack/mongodb/log-view.png" />
  </Step>
</Steps>

<div id="dashboards">
  ## 仪表盘和可视化
</div>

<Steps>
  <Step>
    #### <TrackedLink href={'/zh/examples/mongodb-logs-dashboard.json'} download="mongodb-logs-dashboard.json" eventName="docs.mongodb_logs_monitoring.dashboard_download">下载</TrackedLink> 仪表盘配置
  </Step>

  <Step>
    #### 导入预建仪表盘

    1. 打开 HyperDX，进入 Dashboards 部分。
    2. 点击右上角省略号菜单中的“Import Dashboard”。

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=21af53f2ddc48534745ebc3f01de39ef" alt="导入仪表盘" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/mongodb/finish-import.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=cce28e62e49846f31cb0419c6a0e0315" alt="完成导入 MongoDB 日志仪表盘" width="3354" height="1934" data-path="images/clickstack/mongodb/finish-import.png" />
  </Step>

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/mongodb/example-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=340ad52d6517bddfd61c28d36e92573a" alt="MongoDB 日志仪表盘" width="3836" height="1934" data-path="images/clickstack/mongodb/example-dashboard.png" />
  </Step>
</Steps>

<div id="troubleshooting">
  ## 故障排查
</div>

<div id="no-logs">
  ### HyperDX 中未显示任何日志
</div>

请确认生效的配置中包含 filelog 接收器：

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
```

检查 collector 日志中是否有错误：

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log
```

<div id="logs-not-parsing">
  ### 日志解析不正确
</div>

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

```bash theme={null}
tail -1 /var/log/mongodb/mongod.log | python3 -m json.tool
```

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

<div id="next-steps">
  ## 后续步骤
</div>

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

<div id="going-to-production">
  ## 进入生产环境
</div>

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