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

# Monitoring MongoDB logs with ClickStack

> Monitoring MongoDB Logs with ClickStack

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>
  **TL;DR**

  Collect and visualize MongoDB server logs (4.4+ JSON format) in ClickStack using the OTel `filelog` receiver. Includes a demo dataset and pre-built dashboard.
</Info>

<h2 id="existing-mongodb">
  Integration with existing MongoDB
</h2>

This section covers configuring your existing MongoDB installation to send logs to ClickStack by modifying the ClickStack OTel collector configuration.
If you would like to test the MongoDB integration before configuring your own existing setup, you can test with our preconfigured setup and sample data in the ["Demo dataset"](/clickstack/integration-examples/mongodb-logs#demo-dataset) section.

<h3 id="prerequisites">
  Prerequisites
</h3>

* ClickStack instance running
* Existing self-managed MongoDB installation (version 4.4 or newer)
* Access to MongoDB log files

<Steps>
  <Step>
    <h4 id="verify-mongodb">
      Verify MongoDB logging configuration
    </h4>

    MongoDB 4.4+ outputs structured JSON logs by default. Check your log file location:

    ```bash theme={null}
    cat /etc/mongod.conf | grep -A 5 systemLog
    ```

    Common MongoDB log locations:

    * **Linux (apt/yum)**: `/var/log/mongodb/mongod.log`
    * **macOS (Homebrew)**: `/usr/local/var/log/mongodb/mongo.log`
    * **Docker**: Often logged to stdout, but can be configured to write to `/var/log/mongodb/mongod.log`

    If MongoDB is logging to stdout, configure it to write to a file by updating `mongod.conf`:

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

    After changing the configuration, restart MongoDB:

    ```bash theme={null}
    # For systemd
    sudo systemctl restart mongod

    # For Docker
    docker restart <mongodb-container>
    ```
  </Step>

  <Step>
    <h4 id="custom-otel">
      Create a custom OTel collector configuration for MongoDB
    </h4>

    ClickStack allows you to extend the base OpenTelemetry Collector configuration by mounting a custom configuration file and setting an environment variable. The custom configuration is merged with the base configuration managed by HyperDX via OpAMP.

    Create a file named `mongodb-monitoring.yaml` with the following configuration:

    ```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>
      * You only define new receivers and pipelines in the custom config. The processors (`memory_limiter`, `transform`, `batch`) and exporters (`clickhouse`) are already defined in the base ClickStack configuration — you just reference them by name.
      * This configuration uses `start_at: beginning` to read all existing logs when the collector starts. For production deployments, change to `start_at: end` to avoid re-ingesting logs on collector restarts.
    </Note>
  </Step>

  <Step>
    <h4 id="load-custom">
      Configure ClickStack to load custom configuration
    </h4>

    To enable custom collector configuration in your existing ClickStack deployment, you must:

    1. Mount the custom config file at `/etc/otelcol-contrib/custom.config.yaml`
    2. Set the environment variable `CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml`
    3. Mount your MongoDB log directory so the collector can read them

    <Tabs>
      <Tab title="Docker Compose">
        Update your ClickStack deployment configuration:

        ```yaml theme={null}
        services:
          clickstack:
            # ... existing configuration ...
            environment:
              - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
              # ... other environment variables ...
            volumes:
              - ./mongodb-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
              - /var/log/mongodb:/var/log/mongodb:ro
              # ... other volumes ...
        ```
      </Tab>

      <Tab title="Docker Run (All-in-One Image)">
        If you're using the all-in-one image with docker, run:

        ```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>
      Ensure the ClickStack collector has appropriate permissions to read the MongoDB log files. In production, use read-only mounts (`:ro`) and follow the principle of least privilege.
    </Note>
  </Step>

  <Step>
    <h4 id="verifying-logs">
      Verify Logs in HyperDX
    </h4>

    Once configured, log into HyperDX and verify that logs are flowing:

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/mongodb/search-view.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=29c24e9a372f56355a255289a5f0f15a" alt="MongoDB logs search view" width="3808" height="1934" data-path="images/clickstack/mongodb/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/mongodb/log-view.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=842608adf96205d2a8ed394875fc80bd" alt="MongoDB log detail view" width="3808" height="1934" data-path="images/clickstack/mongodb/log-view.png" />
  </Step>
</Steps>

<h2 id="demo-dataset">
  Demo dataset
</h2>

Test the MongoDB integration with a pre-generated sample dataset before configuring your production systems.

<Steps>
  <Step>
    <h4 id="download-sample">
      Download the sample dataset
    </h4>

    Download the sample log file:

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

  <Step>
    <h4 id="test-config">
      Create test collector configuration
    </h4>

    Create a file named `mongodb-demo.yaml` with the following configuration:

    ```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>
    <h4 id="run-demo">
      Run ClickStack with demo configuration
    </h4>

    Run ClickStack with the demo logs and configuration:

    ```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
    ```

    <h2 id="verify-demo-logs">
      Verify logs in HyperDX
    </h2>

    Once ClickStack is running:

    1. Open [HyperDX](http://localhost:8080/) and log in to your account (you may need to create an account first)
    2. Navigate to the Search view and set the source to `Logs`
    3. Set the time range to include **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/mongodb/search-view.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=29c24e9a372f56355a255289a5f0f15a" alt="MongoDB logs search view" width="3808" height="1934" data-path="images/clickstack/mongodb/search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/mongodb/log-view.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=842608adf96205d2a8ed394875fc80bd" alt="MongoDB log detail view" width="3808" height="1934" data-path="images/clickstack/mongodb/log-view.png" />
  </Step>
</Steps>

<h2 id="dashboards">
  Dashboards and visualization
</h2>

<Steps>
  <Step>
    <h4 id="download">
      <TrackedLink href={'/examples/mongodb-logs-dashboard.json'} download="mongodb-logs-dashboard.json" eventName="docs.mongodb_logs_monitoring.dashboard_download">Download</TrackedLink> the dashboard configuration
    </h4>
  </Step>

  <Step>
    <h4 id="import-dashboard">
      Import pre-built dashboard
    </h4>

    1. Open HyperDX and navigate to the Dashboards section.
    2. Click "Import Dashboard" in the upper right corner under the ellipses.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/import-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=eace17d7f86efbec4d3151bbf428941a" alt="Import Dashboard" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. Upload the mongodb-logs-dashboard.json file and click finish import.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/mongodb/finish-import.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=0cf063c2710bb0b775c5ee2b4b998c4d" alt="Finish importing MongoDB logs dashboard" width="3354" height="1934" data-path="images/clickstack/mongodb/finish-import.png" />
  </Step>

  <Step>
    <h4 id="created-dashboard">
      The dashboard will be created with all visualizations pre-configured
    </h4>

    For the demo dataset, set the time range to include **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**.

    <Image img="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/zXCQbzXFHfeD9FBK/images/clickstack/mongodb/example-dashboard.png?fit=max&auto=format&n=zXCQbzXFHfeD9FBK&q=85&s=208e0c927be835dced88c3f7103e6a89" alt="MongoDB logs dashboard" width="3836" height="1934" data-path="images/clickstack/mongodb/example-dashboard.png" />
  </Step>
</Steps>

<h2 id="troubleshooting">
  Troubleshooting
</h2>

<h3 id="no-logs">
  No logs appearing in HyperDX
</h3>

Verify the effective config includes your filelog receiver:

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

Check for errors in the collector logs:

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

<h3 id="logs-not-parsing">
  Logs not parsing correctly
</h3>

Verify MongoDB is outputting JSON logs (4.4+):

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

If the output is not valid JSON, your MongoDB version may be using the legacy text log format (pre-4.4). You'll need to replace the `json_parser` operator with a `regex_parser`, or upgrade to MongoDB 4.4+.

<h2 id="next-steps">
  Next steps
</h2>

* Set up [alerts](/clickstack/features/alerts) for critical events (error spikes, slow query thresholds)
* Create additional [dashboards](/clickstack/features/dashboards/overview) for specific use cases (replica set monitoring, connection tracking)

<h2 id="going-to-production">
  Going to production
</h2>

This guide extends ClickStack's built-in OpenTelemetry Collector for quick setup. For production deployments, we recommend running your own OTel Collector and sending data to ClickStack's OTLP endpoint. See [Sending OpenTelemetry data](/clickstack/ingesting-data/opentelemetry) for production configuration.