checkId: check.servicegraph.connection-pools plugin: stellaops.doctor.servicegraph severity: warn tags: [servicegraph, resilience, pool, postgres, live-state]
Connection Pool Saturation
What It Checks
Reads live pool snapshots through the read-only IConnectionPoolStateProvider seam. Evidence includes active connections, max connections, queued requests, saturated pool count, max wait time, and one stable PoolStates row per instrumented pool.
| Condition | Result |
|---|---|
| No live pool-state provider, provider unavailable, or no pools reported | skip |
| Any pool is at max capacity or has queued requests | fail |
| No saturated pool but max wait time is above 250 ms | warn |
| Instrumented pools have headroom and no queueing | pass |
Why It Matters
Pool saturation turns transient database or HTTP pressure into platform-wide latency. Configured max pool size is not enough: operators need the live active/max/queued state to spot leaks and capacity pressure before requests fail.
Common Causes
- Long-running requests hold pooled connections
- Connection leaks in an owning service
- Pool max size is too small for the current workload
- A downstream dependency is slow and callers queue behind pooled resources
How to Fix
Docker Compose
docker compose -f devops/compose/docker-compose.stella-ops.yml logs --tail 100 doctor-web
docker compose -f devops/compose/docker-compose.stella-ops.yml logs --tail 100 postgres
If the evidence names a saturated Postgres pool, review the owning connection string before increasing Max Pool Size; leaks or long transactions should be fixed first.
Bare Metal / systemd
Inspect the owning service logs and database activity. Increase pool size only after confirming PostgreSQL max_connections and service memory headroom can support it.
Kubernetes / Helm
Review pod-level concurrency, connection-string pool limits, and the database connection budget. Scale callers or raise pool limits conservatively so the sum of pod pools does not exceed PostgreSQL capacity.
Verification
stella doctor run --check check.servicegraph.connection-pools
Related Checks
check.servicegraph.circuitbreaker- pool saturation can trigger outbound breaker failurescheck.db.pool.health- database-side pool and connection pressurecheck.db.pool.size- configured Npgsql pool limits