Mongodb Connection

# MongoDB Connection Monitoring Guide

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.

## Driver Events
All MongoDB drivers implement the [Connection Monitoring and Pooling specification](https://github.com/mongodb/specifications/blob/master/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md), which defines standard events for tracking pool lifecycle and connection state:

**Pool lifecycle events**:
- `ConnectionPoolCreated` / `ConnectionPoolClosed` - Track when pools are initialized or shut down

**Connection lifecycle events**:
- `ConnectionCreated` / `ConnectionClosed` - Monitor connection churn (rapid creation = pooling issues)

**Check-out events**:
- `ConnectionCheckOutStarted` - Operation requests a connection
- `ConnectionCheckedOut` / `ConnectionCheckedIn` - Track when connections are borrowed/returned
- `ConnectionCheckOutFailed` - **Critical alert signal** - indicates pool exhaustion

**Tip:** Send `ConnectionCheckOutFailed` events and rapid `ConnectionCreated` events to your monitoring system immediately.

Access methods vary by driver. Consult your driver's [documentation](https://www.mongodb.com/docs/drivers/) for how to subscribe to these standard events.

---

### Driver-Level Metrics to Watch

#### Connections Created

**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:
- Application restarts
- Pool size is increased
- Network disruptions force reconnections

**Troubleshooting**:
- **Rapid growth**: Indicates connection churn. Check:
  - `maxIdleTimeMS` is not too aggressive
  - Network stability
  - Application not creating new clients repeatedly
  - Serverless functions caching clients properly

---

#### Connections In-Use

**What 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**:
- **Sustained >80% of maxPoolSize**: Increase `maxPoolSize` by 20-30%
- **Consistently 100%**: Pool is definitely exhausted; immediate action needed
- **High percentage with high wait queue times**: Clear sign of undersized pool

---

#### Connections Available

**What it is**: The number of open but unused connections ready in the pool.

**Events**:
- `ConnectionCheckedInEvent` - increases available count
- `ConnectionCheckedOutEvent` - decreases available count

**What 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**:
- **Always zero during traffic**: Pool is too small; connections are never released
- **Very low during normal load**: Consider increasing `maxPoolSize` or `minPoolSize`

---

#### Wait Queue Size

**What 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 queu