Monitor MongoDB with OpenTelemetry

Osuite monitors MongoDB through the OpenTelemetry Collector’s mongodb receiver, which reads server and database statistics and exports them over OTLP. Connection counts, cache behavior, and lock time arrive with the same resource attributes as your services, so query latency in APM correlates with the database serving it.

Note

The mongodb receiver ships in the Collector contrib distribution. Use otelcol-contrib (or any build that includes it), not the core otelcol binary.

Setup

Prerequisites

• A reachable MongoDB deployment (4.0 or later).
• A least-privilege user with the built-in clusterMonitor role.

Create the monitoring user in the admin database:

db.getSiblingDB("admin").createUser({
  user: "otel",
  pwd: "a-strong-password",
  roles: [{ role: "clusterMonitor", db: "admin" }]
})

Export the password to the Collector’s environment:

export MONGODB_PASSWORD='a-strong-password'

Configure the Collector

1. Add the mongodb receiver, the otlp/osuite exporter, and a metrics pipeline. The hosts field is a list — add one entry per member to monitor a replica set. Pick the tab that matches where your Collector runs.

   Bare host

   receivers:
     mongodb:
       hosts:
         - endpoint: localhost:27017
       username: otel
       password: ${env:MONGODB_PASSWORD}
       collection_interval: 60s
       tls:
         insecure: true
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [mongodb]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Docker

   receivers:
     mongodb:
       hosts:
         - endpoint: mongodb:27017
       username: otel
       password: ${env:MONGODB_PASSWORD}
       collection_interval: 60s
       tls:
         insecure: true
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [mongodb]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Kubernetes

   receivers:
     mongodb:
       hosts:
         - endpoint: mongodb.default.svc.cluster.local:27017
       username: otel
       password: ${env:MONGODB_PASSWORD}
       collection_interval: 60s
       tls:
         insecure: true
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [mongodb]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

2. Start the Collector. On Docker and Kubernetes, the Collector and MongoDB must share a network so the endpoint resolves.

Caution

tls.insecure: true disables certificate verification for the database connection. Set it to false and provide ca_file when MongoDB enforces TLS.

Validate

What you should see

Metrics named mongodb.* appear in Dashboards → Explore metrics within a minute, tagged with the host or pod the Collector runs on.

Data collected

Metric	Description	Unit
mongodb.connection.count	Connections by type (active, available, current)	{connections}
mongodb.cache.operations	Cache hits and misses	{operations}
mongodb.operation.count*	Operations by type (insert, query, update, delete)	{operations}
mongodb.document.operation.count	Document operations by type	{documents}
mongodb.cursor.count	Open cursors held for clients	{cursors}
mongodb.global_lock.time	Time the global lock has been held	ms
mongodb.data.size	Uncompressed data size	By
mongodb.collection.count	Collections per database	{collections}
mongodb.database.count	Number of databases	{databases}
mongodb.index.access.count	Times an index has been accessed	{accesses}

*mongodb.operation.count reports server-wide operation rates; the receiver exposes many more per-database and per-collection metrics through optional toggles.

Dashboards and alerts

Once metrics arrive, build a MongoDB dashboard in the dashboard builder from the series above. Alerts in Osuite are PromQL-based — see Alerts. Useful starting conditions: connection saturation (mongodb.connection.count), a falling cache hit ratio (mongodb.cache.operations), and rising mongodb.global_lock.time.

Troubleshooting

• Authentication failed — confirm the otel user was created in the admin database and that the Collector authenticates against admin (the receiver’s default auth source).
• Missing metrics — a user without clusterMonitor can connect but cannot read server statistics; confirm the role grant.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.