OpenTelemetry Collector for MongoDB

Kloudfuse can receive MongoDB metrics collected by the OpenTelemetry Collector mongodbreceiver. The receiver connects directly to MongoDB using the Go MongoDB driver, queries serverStatus and related commands, and exports the results to Kloudfuse via the OTLP HTTP exporter. This approach works in any environment — Kubernetes, virtual machines, or bare metal — without requiring the Kloudfuse observability agent.

Overview

The mongodbreceiver is part of the OpenTelemetry Collector Contrib distribution (otel/opentelemetry-collector-contrib). You configure it with one or more MongoDB endpoints and credentials, and it periodically collects:

• Connection pool statistics (serverStatus.connections)
• Operation counters — inserts, queries, updates, deletes, getmores, commands
• Memory usage — resident and virtual
• Lock wait queue lengths
• Replication lag and oplog window (replica set members)
• Database and collection sizes (dbStats)
• Index access statistics

The collector emits these as OTLP metrics and forwards them to the Kloudfuse ingestion endpoint, where they are queryable via PromQL and FuseQL.

Prerequisites

Create a Monitoring User

Create a dedicated low-privilege user in the admin database:

use admin
db.createUser({
  user: "kfmon",
  pwd: "<password>",
  roles: [
    { role: "read", db: "admin" },
    { role: "clusterMonitor", db: "admin" },
    { role: "read", db: "local" }
  ]
})

The clusterMonitor role grants access to serverStatus and replica set status commands. The read role on the local database is required to read the oplog for replication metrics.

TLS (Optional)

If your MongoDB deployment requires TLS, you will need to provide a CA certificate file in the collector configuration. For development environments without TLS, set insecure: true in the receiver config.

Configure the Collector

Collector Configuration File

The following config.yaml configures the mongodbreceiver and the otlphttp exporter pointed at Kloudfuse:

receivers:
  mongodb:
    hosts:
      - endpoint: <mongodb-host>:27017
    username: kfmon
    password: <password>
    tls:
      insecure: true            # set to false and add ca_file for TLS
    collection_interval: 60s

processors:
  batch:
    timeout: 10s
  resource:
    attributes:
      - key: service.name
        value: mongodb
        action: upsert

exporters:
  otlphttp:
    metrics_endpoint: https://<kloudfuse-hostname>/ingester/otlp/metrics
    tls:
      insecure: false

service:
  pipelines:
    metrics:
      receivers: [mongodb]
      processors: [resource, batch]
      exporters: [otlphttp]

Replace the following placeholders:

Replica Set

To collect metrics from all members of a replica set, list each member endpoint under hosts. The receiver connects to each member individually and collects member-specific metrics including replication lag:

receivers:
  mongodb:
    hosts:
      - endpoint: <rs-member-1>:27017
      - endpoint: <rs-member-2>:27017
      - endpoint: <rs-member-3>:27017
    username: kfmon
    password: <password>
    tls:
      insecure: true
    collection_interval: 60s

Deploy on Kubernetes (Helm)

1. Add the OpenTelemetry Helm repository:

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

2. Store the MongoDB password in a Kubernetes secret:

kubectl create secret generic otel-mongodb-credentials \
     --from-literal=password='<password>' \
     -n <collector-namespace>

3. Create a values.yaml for the collector Helm chart:

image:
     repository: otel/opentelemetry-collector-contrib

mode: deployment

extraEnvs:
  - name: MONGO_PASSWORD
    valueFrom:
      secretKeyRef:
        name: otel-mongodb-credentials
        key: password

config:
receivers:
    mongodb:
      hosts:
        - endpoint: <mongodb-service>.<mongodb-namespace>.svc.cluster.local:27017
      username: kfmon
      password: ${env:MONGO_PASSWORD}
      tls:
        insecure: true
      collection_interval: 60s

processors:
    batch:
      timeout: 10s
    resource:
      attributes:
        - key: service.name
          value: mongodb
          action: upsert

exporters:
    otlphttp:
      metrics_endpoint: https://<kloudfuse-hostname>/ingester/otlp/metrics

service:
    pipelines:
      metrics:
        receivers: [mongodb]
        processors: [resource, batch]
        exporters: [otlphttp]

4. Install the collector:

helm upgrade --install otel-mongodb open-telemetry/opentelemetry-collector \
     -f values.yaml \
     -n <collector-namespace>

5. Confirm the pod is running:

kubectl get pods -n <collector-namespace> -l app.kubernetes.io/name=opentelemetry-collector

Log Collection (Optional)

MongoDB writes logs to stdout in Kubernetes by default. Add a filelog receiver to collect them:

receivers:
  filelog:
    include:
      - /var/log/pods/<mongodb-namespace>_<pod-name-prefix>*/**/*.log
    operators:
      - type: json_parser        # MongoDB 4.4+ uses structured JSON log format
        timestamp:
          parse_from: attributes.t.$$date
          layout: '%Y-%m-%dT%H:%M:%S.%LZ'
        severity:
          parse_from: attributes.s
          mapping:
            error: E
            warn: W
            info: I
            debug: D

Add logs_endpoint to the exporter and a logs pipeline:

exporters:
  otlphttp:
    metrics_endpoint: https://<kloudfuse-hostname>/ingester/otlp/metrics
    logs_endpoint: https://<kloudfuse-hostname>/ingester/otlp/v1/logs

service:
  pipelines:
    metrics:
      receivers: [mongodb]
      processors: [resource, batch]
      exporters: [otlphttp]
    logs:
      receivers: [filelog]
      processors: [resource, batch]
      exporters: [otlphttp]

Verify Metrics Are Arriving

After deploying the collector, confirm metrics are arriving in the Kloudfuse UI:

1. Click the Metrics tab, then select Explorer from the drop-down menu.
2. Set the time range to the last 15 minutes using the interval picker in the top-right corner.
3. In the metric selector, type mongodb_connection_count and select it from the suggestions list. Confirm a chart appears with data points.
4. Use the label filters to narrow results — for example, filter by service_name="mongodb" to isolate metrics for a specific instance.

Key metrics emitted by the mongodbreceiver:

To verify logs are arriving (when log collection is enabled), click the Logs tab, filter by source mongodb in the Filters panel, and confirm log entries appear in the list.

Troubleshooting

No Metrics in Kloudfuse

If mongodb_connection_count returns no data:

1. Check the collector pod logs for scrape or connection errors:

kubectl logs -n <collector-namespace> -l app.kubernetes.io/instance=otel-mongodb

Look for "Error scraping mongodb" or "connection refused" messages.

2. Confirm the collector can reach the MongoDB service:

kubectl exec -n <collector-namespace> <collector-pod-name> -- \
     nc -zv <mongodb-service>.<mongodb-namespace>.svc.cluster.local 27017

Authentication Errors

If the collector logs show Authentication failed:

• Confirm the password in the Kubernetes secret matches the MongoDB user password.
• Verify the user exists: use admin; db.getUser("kfmon").
• Confirm the user has clusterMonitor in the admin database.
• If MongoDB requires an auth source other than admin, set it explicitly via the connection URI — see the mongodbreceiver docs.

Standalone Warning at Startup

On a standalone (non-replica set) MongoDB instance, the collector logs the following warning at startup:

failed to find secondary hosts: (NoReplicationEnabled) not running with --replSet

This is expected and harmless — the receiver attempts to discover replica set members and falls back gracefully. Metrics from serverStatus and dbStats are collected normally.

Replication Lag Metrics Are Missing

• Confirm all replica set member endpoints are listed under hosts in the receiver config.
• The monitoring user needs the read role on the local database to access oplog data.
• Replication lag is only reported on secondary members — the primary shows 0.

TLS Connection Errors

If the collector logs show certificate signed by unknown authority or similar TLS errors:

• Set tls.insecure_skip_verify: true for development, or provide the CA certificate via tls.ca_file.
• Ensure the MongoDB TLS certificate’s CN or SAN matches the hostname used in endpoint.

External References

• OTel Collector — mongodbreceiver
• mongodbreceiver — Metrics Reference
• OpenTelemetry Collector — Installation
• MongoDB — serverStatus
• MongoDB — replSetGetStatus
• MongoDB — Database Profiler