Datadog Agent for MongoDB

Kloudfuse collects metrics and logs from self-managed MongoDB deployments using the Kloudfuse observability agent. The agent discovers MongoDB pods automatically via Kubernetes pod annotations — no separate scraper deployment is required.

Overview

The Kloudfuse observability agent (kfuse-observability-agent) is a customised Datadog agent that runs as a DaemonSet — one pod on every Kubernetes node in your cluster. It uses Datadog Autodiscovery: it continuously watches pod annotations prefixed with ad.datadoghq.com/ to find services to monitor.

When the agent finds a MongoDB pod with the right annotations, it:

  1. Resolves %%host%% to the pod’s cluster IP and %%port%% to its port — automatically, from the pod’s own network identity.

  2. Opens a connection to MongoDB using the credentials in the annotation.

  3. Runs the built-in mongo integration check, querying serverStatus, dbStats, replSetGetStatus, and the profiler collections.

  4. Forwards the results to the Kloudfuse ingester as time-series metrics.

For replica sets, you must configure a check instance for each mongod member individually so that replication lag and member-specific metrics are collected from each node. For sharded clusters, add an additional instance pointing to the mongos proxy to collect router metrics.

Prerequisites

Create a Monitoring User

The mongo check connects using a dedicated low-privilege user. Create the user in the admin database:

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

For MongoDB 3.6 and earlier, substitute clusterMonitor with the explicit privilege grants described in the Datadog MongoDB integration docs.

Enable the Slow Query Profiler (Optional)

To collect slow operation metrics from the MongoDB profiler, set the profiling level on each database you want to monitor:

use <database-name>
db.setProfilingLevel(1, { slowms: 100 })   -- log operations slower than 100 ms
js

Verify the Observability Agent Is Running

Confirm DaemonSet pods are running on the same nodes as your MongoDB pods:

kubectl get pods -n <kloudfuse-namespace> -l app=kfuse-observability-agent -o wide
kubectl get pods -n <mongodb-namespace> -l app.kubernetes.io/name=mongodb -o wide

Every node that runs a MongoDB pod must also have a healthy observability agent pod.

Configure Autodiscovery Annotations

The observability agent picks up the MongoDB check when your pod carries the following annotations. Add them to the pod template of your MongoDB Deployment, StatefulSet, or Helm chart values.

Standalone or Replica Set Member

podAnnotations:
  ad.datadoghq.com/mongodb.check_names: '["mongo"]'
  ad.datadoghq.com/mongodb.init_configs: '[{}]'
  ad.datadoghq.com/mongodb.instances: >-
    [{
      "hosts": ["%%host%%:%%port%%"],
      "username": "datadog",
      "password": "<password>",
      "database": "admin",
      "options": {},
      "replica_check": true,
      "tags": ["env:<environment>", "service:mongodb"]
    }]
yaml

%%host%% and %%port%% are Autodiscovery template variables that the agent resolves to the pod’s cluster IP and exposed port at runtime.

If you use the Bitnami mongodb chart, add the annotations under podAnnotations:

mongodb:
  podAnnotations:
    ad.datadoghq.com/mongodb.check_names: '["mongo"]'
    ad.datadoghq.com/mongodb.init_configs: '[{}]'
    ad.datadoghq.com/mongodb.instances: >-
      [{"hosts": ["%%host%%:%%port%%"], "username": "datadog", "password": "<password>", "database": "admin", "replica_check": true, "tags": []}]
yaml

Replica Set

For a replica set, each member (primary and secondaries) must have its own annotation block so the check runs against each node individually. The replica_check: true flag collects replication lag and member state metrics.

If your replica set is managed as a StatefulSet, annotate the pod template and the check runs on every replica:

podAnnotations:
  ad.datadoghq.com/mongodb.check_names: '["mongo"]'
  ad.datadoghq.com/mongodb.init_configs: '[{}]'
  ad.datadoghq.com/mongodb.instances: >-
    [{"hosts": ["%%host%%:%%port%%"], "username": "datadog", "password": "<password>", "database": "admin", "replica_check": true, "tags": []}]
yaml

Sharded Cluster (mongos)

For sharded clusters, also annotate the mongos router pods:

podAnnotations:
  ad.datadoghq.com/mongodb.check_names: '["mongo"]'
  ad.datadoghq.com/mongodb.init_configs: '[{}]'
  ad.datadoghq.com/mongodb.instances: >-
    [{"hosts": ["%%host%%:%%port%%"], "username": "datadog", "password": "<password>", "database": "admin", "tags": ["role:mongos"]}]
yaml

Logs

To collect MongoDB logs alongside metrics, add:

podAnnotations:
  ad.datadoghq.com/mongodb.logs: >-
    [{"source": "mongodb", "service": "mongodb"}]
yaml

Combine this with the metrics annotations in a single podAnnotations block.

Apply the Annotations

kubectl rollout restart statefulset/<mongodb-statefulset> -n <namespace>

The agent detects the new annotations within the next Autodiscovery refresh cycle (typically within 30 seconds of pod startup).

Verify Metrics Are Arriving

After restarting the agent, 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_connections_current 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="mongodb" to isolate metrics for a specific instance.

Key metrics collected by the mongo check:

Metric Description

mongodb_connections_current

Number of current client connections

mongodb_connections_available

Number of unused available connections

mongodb_opcounters_queryps / _insertps / _updateps / _deleteps

Operation rate per second by type

mongodb_mem_resident

Resident memory used by MongoDB in MB

mongodb_mem_virtual

Virtual memory used by MongoDB in MB

mongodb_globallock_currentqueue_total

Total number of operations queued waiting for a lock

mongodb_oplatencies_reads_latency

Cumulative read operation latency in microseconds

mongodb_stats_datasize

Total data size for the database in bytes

mongodb_stats_indexsize

Total index size for the database in bytes

mongodb_uptime

MongoDB process uptime in seconds

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

Troubleshooting

No MongoDB Metrics in Kloudfuse

If mongodb_connections_current returns no data:

  1. Check that the agent pod is on the same node as the MongoDB pod:

    kubectl get pods -n <agent-namespace> -l app=<agent-release-name> -o wide
kubectl get pods -n <mongodb-namespace> -l app.kubernetes.io/name=mongodb -o wide

  2. Run the check manually from the agent pod:

    AGENT_POD=$(kubectl get pod -n <agent-namespace> -l app=<agent-release-name> -o jsonpath='{.items[0].metadata.name}')
kubectl exec -n <agent-namespace> $AGENT_POD -- agent check mongo

  3. Check agent logs for connection errors:

    kubectl logs -n <agent-namespace> $AGENT_POD | grep -i "mongo"

Authentication Error in Agent Logs

If the agent logs show Authentication failed:

  • Confirm the password in ad.datadoghq.com/mongodb.instances matches the MongoDB user password.

  • Verify the user exists: use admin; db.getUser("<username>").

  • Confirm the user has the clusterMonitor role in the admin database.

Replication Lag Metrics Are Missing

  • Confirm "replica_check": true is set in the instances annotation.

  • Verify the check is running on each replica member, not only the primary — each mongod pod needs its own annotation.

  • The monitoring user needs the read role on the local database to read the oplog.

Sharded Cluster Metrics Are Missing

  • Annotate the mongos pods separately from the mongod shard pods.

  • The mongos proxy does not expose replSetGetStatus, so replica_check should be false on mongos instances.

External References