Setting the file. One moment.
Chapter 02 · MongoDB Connection
Subchapter 2.1
references/monitoring-guide.mdMarkdown8 KBView on GitHub
This reference provides detailed guidance on monitoring connection pool health, interpreting metrics, and taking action based on what you observe. Consult this when users need to verify their configuration is working or troubleshoot connection-related issues.
All MongoDB drivers implement the Connection Monitoring and Pooling specification (opens in a new tab), which defines standard events for tracking pool lifecycle and connection state:
Pool lifecycle events:
ConnectionPoolCreated / ConnectionPoolClosed - Track when pools are initialized or shut downConnection lifecycle events:
ConnectionCreated / ConnectionClosed - Monitor connection churn (rapid creation = pooling issues)Check-out events:
ConnectionCheckOutStarted - Operation requests a connectionConnectionCheckedOut / ConnectionCheckedIn - Track when connections are borrowed/returnedConnectionCheckOutFailed - Critical alert signal - indicates pool exhaustionTip: Send ConnectionCheckOutFailed events and rapid ConnectionCreated events to your monitoring system immediately.
Access methods vary by driver. Consult your driver’s documentation (opens in a new tab) for how to subscribe to these standard events.
What it is: The total number of connections the pool has established since initialization.
Events:
ConnectionCreatedEvent - fired when a new connection object is instantiated.What to watch for: Rapid increases (+100 connections/hour in steady state) indicate connection churn due to network issues or misconfiguration.
Healthy pattern: Gradual increase during application startup as the pool warms up, then relatively stable. You should see increases mainly when:
Troubleshooting:
maxIdleTimeMS is not too aggressiveWhat it is: The number of connections currently borrowed from the pool and serving application requests.
Events:
ConnectionCheckedOutEvent - increment counter (connection borrowed)ConnectionCheckedInEvent - decrement counter (connection returned)What to watch for: Consistently high values approaching maxPoolSize signal potential pool exhaustion.
Healthy pattern: Fluctuates with application traffic while maintaining headroom. Should correlate with request volume.
Action thresholds:
maxPoolSize by 20-30%What it is: The number of open but unused connections ready in the pool.
Events:
ConnectionCheckedInEvent - increases available countConnectionCheckedOutEvent - decreases available countWhat to watch for: Consistently zero means the pool is undersized.
Healthy pattern: Some available connections (10-20% of maxPoolSize) ready to handle sudden traffic spikes without waiting for new connection establishment.
Action thresholds:
maxPoolSize or minPoolSizeWhat it is: The number of operations currently waiting for an available connection because the pool is at capacity.
Event:
ConnectionCheckoutStartedEvent - track when threads enter wait queue.What to watch for: Any value above zero indicates possible pool exhaustion. This is a critical metric.
Healthy pattern: Zero most of the time, or occasional spikes during peak loads.
Action thresholds:
maxPoolSize or reduce operation durationWhy this matters: If waitQueueTimeoutMS is reached, users see errors.
What it is: The duration operations spend waiting for connections to become available.
Events – Calculate duration: (checked out time) - (checkout started time)
ConnectionCheckoutStartedEvent - record timestamp when entering queueConnectionCheckedOutEvent - record timestamp when successfully acquiredWhat to watch for: This wait time directly adds to application latency. Even moderate wait times (50-100ms) can degrade user experience.
Healthy pattern: Consistently near-zero milliseconds.
Action thresholds:
Use db.serverStatus().connections via MongoDB shell or driver equivalent.
Available fields:
current - Total active client connectionsavailable - Remaining capacity before hitting maxIncomingConnectionstotalCreated - Cumulative connections created since server startactive - Connections currently executing operationsexhaustIsMaster / exhaustHello - Streaming topology monitoring connectionsawaitingTopologyChanges - Connections waiting for topology updatesWhat it is: The number of active client connections currently established to the MongoDB server.
What to watch for: Approaching maxIncomingConnections indicates server-side saturation.
Default maxIncomingConnections values per OS:
(RLIMIT_NOFILE / 2) * 0.8 (MongoDB enforces this limit even if configured higher)Healthy pattern: Stable value with headroom for growth. Should roughly match the sum of all client pool sizes across all application instances.
Action thresholds:
Calculation example: If you have 10 application instances each with maxPoolSize: 50, you could have up to 500 connections in a single-server deployment. In a 3-member replica set, potentially 1,500 total connections across all members.
What it is: How many more connections the server can accept before hitting its configured limit.
What to watch for: Low values indicate risk of connection refusal for new clients or scaling operations.
Healthy pattern: Substantial headroom even during peak traffic. At least 20-30% of maxIncomingConnections should remain available.
Action thresholds:
What it is: The cumulative total of all connections created since the MongoDB server started.
What to watch for: The rate of increase indicates connection churn. Compare snapshots over time to calculate rate.
Healthy pattern: Increases mainly during:
Diagnosis:
Example: If you see totalCreated increasing by 1,000 connections/hour but you only restart apps once per day (not serverless), something is causing unnecessary connection cycling.