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" }
  ]
})
js

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]
yaml

Replace the following placeholders:

Placeholder Value

<mongodb-host>

Hostname or service name of the MongoDB instance

<password>

Password for the monitoring user

<kloudfuse-hostname>

External hostname of your Kloudfuse cluster

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
yaml

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]
    yaml

  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
yaml

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]
yaml

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:

Metric (PromQL name) Description

mongodb_connection_count

Number of connections by state (active, available, current)

mongodb_collection_count

Number of collections in a database

mongodb_cache_operations

WiredTiger cache operations (hits and misses)

mongodb_cursor_count

Number of open cursors by state

mongodb_cursor_timeout_count

Number of cursors that have timed out

mongodb_document_operation_count

Document operations by type (inserted, updated, deleted, returned)

mongodb_index_count

Number of indexes in a database

mongodb_index_size

Total index size for a database in bytes

mongodb_data_size

Data size of a database in bytes

mongodb_storage_size

Storage size allocated for a database in bytes

mongodb_object_count

Number of objects (documents) in a database

mongodb_operation_count

Operation counts by type (insert, query, update, delete, getmore, command)

mongodb_operation_latency_time

Latency of operations by type (reads, writes, commands)

mongodb_uptime

MongoDB server uptime in milliseconds

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