> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/monitor/metrics-reference/mongodb/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# MongoDB metrics reference

> Detailed reference for every MongoDB metric collected by mongodb_exporter, including PromQL expressions, alert thresholds, and troubleshooting guidance.

This page expands on the [MongoDB alert thresholds](/itential-platform/monitor/exporters#mongodb_exporter) in [Exporters](/itential-platform/monitor/exporters) with a per-metric description, a PromQL expression, alert thresholds, and troubleshooting guidance. Use it when you're building alert rules from scratch or investigating an alert that already fired.

MongoDB is Platform's primary datastore. Every job, task, workflow definition, adapter configuration, and audit record lives there, so a degraded MongoDB instance affects everything Platform does.

Configure alerts to group by `instance` and `rs_nm` (replica set name) so you can immediately identify which member and replica set is affected. Route `Warning` alerts to a team channel and `Critical` or `Emergency` alerts to on-call, and configure alert dependencies so replication lag doesn't page separately when the member is already alerting as down.

## Normalized CPU usage on all replica sets

High CPU usage can indicate an inefficient query, a missing index causing a collection scan, a complex aggregation pipeline, or a background operation such as an index build consuming excessive resources. Sustained high CPU can cause query timeouts, connection pool exhaustion, and replication lag as secondaries struggle to keep up.

**PromQL:**

```
100 - (avg by (instance, rs_nm) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
```

| Threshold | Condition | Duration |
| --------- | --------- | -------- |
| Warning   | CPU > 70% | 5 min    |
| Critical  | CPU > 85% | 5 min    |
| Emergency | CPU > 95% | 2 min    |

Identify expensive queries with `db.currentOp()` and the profiler, review the slow query log, add indexes for frequently run queries, and check for a runaway background operation.

## Normalized memory usage on all replicas

MongoDB uses memory-mapped files and aggressive WiredTiger caching by design, so high memory usage on its own is expected. The danger is memory pressure that forces swapping, since disk I/O is orders of magnitude slower than RAM access and can degrade performance catastrophically.

**PromQL:**

```
100 * (1 - ((node_memory_MemAvailable_bytes{job="node_exporter"} or
  (node_memory_MemFree_bytes{job="node_exporter"} + node_memory_Cached_bytes{job="node_exporter"} + node_memory_Buffers_bytes{job="node_exporter"}))
  / node_memory_MemTotal_bytes{job="node_exporter"}))
```

| Threshold | Condition                      | Duration |
| --------- | ------------------------------ | -------- |
| Warning   | Memory usage > 80%             | 5 min    |
| Critical  | Memory usage > 90%             | 5 min    |
| Emergency | Swap usage > 10% of total swap | 2 min    |

Check the WiredTiger cache size configuration (target roughly 50% of RAM), review working set size against available RAM, and treat any swap activity as a critical red flag regardless of the memory percentage.

## Normalized disk space utilization

MongoDB needs disk space for data files, the WiredTiger journal, the oplog, temporary sort and aggregation files, and backup snapshots. Running out of space causes MongoDB to shut down immediately to prevent data corruption.

**PromQL:**

```
100 - ((node_filesystem_avail_bytes{mountpoint=~"/data.*|/var/lib/mongo.*"} /
  node_filesystem_size_bytes{mountpoint=~"/data.*|/var/lib/mongo.*"}) * 100)
```

| Threshold | Condition        | Duration |
| --------- | ---------------- | -------- |
| Warning   | Disk usage > 75% | 5 min    |
| Critical  | Disk usage > 85% | 5 min    |
| Emergency | Disk usage > 95% | 1 min    |

This is the second most critical MongoDB alert after an instance being down, since disk exhaustion means immediate shutdown. Free space by removing old backups and logs, review data retention policies, and consider compacting collections (`compact`, which requires downtime) or enabling compression.

## Member health or status

A replica set member can be in state `PRIMARY`, `SECONDARY`, `RECOVERING`, `STARTUP`, `DOWN`, `ARBITER`, or `ROLLBACK`. An unhealthy member compromises high availability and, if enough members are unhealthy to lose quorum, the primary steps down and writes are blocked cluster-wide.

**PromQL:**

```
mongodb_rs_members_health{rs_nm!=""}
```

| Threshold | Condition                                              | Duration |
| --------- | ------------------------------------------------------ | -------- |
| Critical  | `mongodb_rs_members_health == 0`                       | 2 min    |
| Warning   | Member state == `RECOVERING`                           | 10 min   |
| Emergency | No member in `PRIMARY` state                           | 30 sec   |
| Emergency | Fewer than a majority of members healthy (quorum lost) | 1 min    |

Check MongoDB logs on the affected member, verify network connectivity between replica set members, confirm `mongod` is running (`systemctl status mongod`), and check for resource exhaustion (CPU, memory, disk).

## MongoDB connections

Current connections are all open connections from application servers, monitoring tools, and administrative sessions. MongoDB has a hard connection limit (default 65536, though the effective limit is usually lower due to memory and file descriptor constraints), and rejected connections mean direct user-facing errors.

**PromQL:**

```
sum(mongodb_ss_connections{conn_type=~"(current|rejected)"}) by (conn_type)
```

| Threshold | Condition                                             | Duration |
| --------- | ----------------------------------------------------- | -------- |
| Warning   | Current connections > 80% of `maxIncomingConnections` | 5 min    |
| Critical  | Current connections > 95% of `maxIncomingConnections` | 2 min    |
| Critical  | Any rejected connections                              | 1 min    |
| Warning   | Connection count increases > 20% in 5 minutes         | 5 min    |

Identify connection sources with `db.currentOp()`, check for a connection leak in application code, and tune connection pool sizes rather than increasing `maxIncomingConnections` as a first response.

## Available connections

This is the runway before connection exhaustion: the number of unused connections MongoDB can still accept before hitting `maxIncomingConnections`. It's a predictive metric that gives advance warning before rejected connections actually start.

**PromQL:**

```
mongodb_ss_connections{env="", conn_type="available"}
```

| Threshold | Condition                     | Duration |
| --------- | ----------------------------- | -------- |
| Warning   | Available connections \< 1000 | 5 min    |
| Critical  | Available connections \< 500  | 2 min    |
| Emergency | Available connections \< 100  | 1 min    |

## Active connections

Active connections are executing an operation right now, as opposed to sitting idle in a pool. This metric distinguishes legitimate traffic growth from operations getting stuck: a spike alongside increasing query latency points to stuck operations, while a spike alone may just be a traffic increase.

**PromQL:**

```
mongodb_ss_connections{env="", conn_type="current"}
```

| Threshold | Condition                                            | Duration |
| --------- | ---------------------------------------------------- | -------- |
| Warning   | Active connections > 2x baseline average             | 10 min   |
| Critical  | Active connections high and query latency increasing | 5 min    |
| Warning   | Active connections increase > 3x in 5 minutes        | 5 min    |

Use `db.currentOp()` to identify long-running operations and the slow query log to find problematic queries before killing anything stuck.

## Replication lag

Replication lag is the delay between the primary and a secondary applying operations from the oplog, in seconds. High lag means stale reads from that secondary, a longer recovery time if it needs to become primary, and risk of falling off the oplog entirely, which forces a full resync.

**PromQL:**

```
mongodb_rs_members_optimeDate{member_state="PRIMARY"} - on(rs_nm) group_right
  mongodb_rs_members_optimeDate{member_state="SECONDARY"}
```

| Threshold | Condition                                     | Duration |
| --------- | --------------------------------------------- | -------- |
| Warning   | Lag > 10 sec                                  | 5 min    |
| Critical  | Lag > 60 sec                                  | 5 min    |
| Emergency | Lag > 300 sec (risk of falling off the oplog) | 2 min    |
| Warning   | Lag increasing steadily                       | 30 min   |

Check network latency between members (`mongodb_rs_members_pingMs`), review the secondary's CPU and disk I/O, and check for a long-running operation on the secondary with `db.currentOp()`.

## Database size

Total storage size per database, excluding `admin`, `config`, and `local`. Unexpected growth can point to a missing time-to-live (TTL) index, an application bug creating duplicate data, or a data model issue, ahead of it becoming a disk space emergency.

**PromQL:**

```
sum(mongodb_dbstats_storageSize{database!~"(admin|config|local)"}) by (database)
```

| Threshold | Condition                                     | Duration |
| --------- | --------------------------------------------- | -------- |
| Warning   | Growth > 20% per week                         | 1 week   |
| Critical  | Size > 80% of provisioned storage             | 1 hour   |
| Warning   | Size exceeds the expected data model by > 50% | 1 day    |

Use `db.stats()` and `db.collection.stats()` to identify which collections are growing, and check for orphaned or duplicate documents.

## Average object size

Average document size per database (total data size divided by document count). A significant change can indicate document bloat, large binary data stored inline instead of in GridFS, or an unbounded array growing without limit.

**PromQL:**

```
sum(mongodb_dbstats_avgObjSize{database!~"(admin|config|local)"}) by (database)
```

| Threshold | Condition                                              | Duration  |
| --------- | ------------------------------------------------------ | --------- |
| Warning   | Increase > 50% from baseline                           | 1 day     |
| Critical  | Average object size > 1 MB                             | 1 hour    |
| Critical  | Any document approaching the 16 MB document size limit | immediate |

## Oplog size

The oplog is a rolling record of every operation that modifies data, used for replication, initial sync, and point-in-time recovery. The oplog window is how much time it spans. If a secondary is offline longer than the window, it falls off the oplog and needs a full resync, which can take hours or days.

**PromQL:**

```
mongodb_oplog_stats_timeDiff{rs_nm!=""}
```

| Threshold | Condition                            | Duration |
| --------- | ------------------------------------ | -------- |
| Warning   | Oplog window \< 24 hours             | 1 hour   |
| Critical  | Oplog window \< 12 hours             | 30 min   |
| Emergency | Oplog window \< 4 hours              | 15 min   |
| Warning   | Oplog window shrinking > 20% per day | 1 day    |

Increase the oplog size online with `replSetResizeOplog`, and make sure the window comfortably covers your longest planned maintenance window.

## Allocated storage to collections

Total disk space allocated to collections and their indexes, including space pre-allocated for growth. A high ratio of allocated space to actual data size indicates fragmentation from deletes and updates.

**PromQL:**

```
sum(mongodb_collstats_storageSize) by (database, collection)
```

| Threshold | Condition                                                  | Duration |
| --------- | ---------------------------------------------------------- | -------- |
| Warning   | Storage allocation > 80% of provisioned capacity           | 1 hour   |
| Critical  | Storage allocation > 90% of provisioned capacity           | 30 min   |
| Warning   | Allocated storage / actual data size > 1.5 (fragmentation) | 1 day    |
| Warning   | Allocation growth > 30% per week                           | 1 week   |

The `compact` command reclaims fragmented space but requires blocking writes to that collection, so schedule it during a maintenance window.

## Disk I/O performance

### Read latency

Average time to complete a disk read (total read time divided by read count). Queries not served from cache, index scans reading from disk, and large aggregations are all sensitive to this.

**PromQL:**

```
rate(node_disk_read_time_seconds_total{device=~"sd.*|nvme.*"}[5m]) /
  rate(node_disk_reads_completed_total{device=~"sd.*|nvme.*"}[5m])
```

| Threshold | Condition (SSD) | Condition (HDD) | Duration |
| --------- | --------------- | --------------- | -------- |
| Warning   | > 10 ms         | > 50 ms         | 10 min   |
| Critical  | > 20 ms         | > 100 ms        | 5 min    |
| Emergency | > 50 ms         | > 200 ms        | 2 min    |

### Write latency

Average time to complete a disk write. MongoDB's durability guarantee depends on writes reaching the journal, so write latency also drives replication lag and write concern timeouts.

**PromQL:**

```
rate(node_disk_write_time_seconds_total{device=~"sd.*|nvme.*"}[5m]) /
  rate(node_disk_writes_completed_total{device=~"sd.*|nvme.*"}[5m])
```

| Threshold | Condition (SSD) | Condition (HDD) | Duration |
| --------- | --------------- | --------------- | -------- |
| Warning   | > 10 ms         | > 50 ms         | 10 min   |
| Critical  | > 20 ms         | > 100 ms        | 5 min    |
| Emergency | > 50 ms         | > 200 ms        | 2 min    |

Ensure the journal is on fast storage, ideally the same tier as the data files, and check for fsync or checkpoint stalls.

### I/O wait percentage

The percentage of CPU time spent waiting on disk I/O. High I/O wait means the storage subsystem, not CPU or memory, is the bottleneck, and it correlates directly with slow queries and replication lag even when CPU and memory both look fine.

**PromQL:**

```
avg by (instance) (rate(node_cpu_seconds_total{mode="iowait"}[5m])) * 100
```

| Threshold | Condition      | Duration |
| --------- | -------------- | -------- |
| Warning   | I/O wait > 20% | 10 min   |
| Critical  | I/O wait > 40% | 5 min    |
| Emergency | I/O wait > 60% | 2 min    |

Add indexes to reduce data scanned, increase RAM so the working set fits in memory, and consider faster storage or sharding to distribute I/O load.

> Detailed reference for every MongoDB metric collected by mongodb_exporter, including PromQL expressions, alert thresholds, and troubleshooting guidance.