PgBouncer monitoring checklist: the signals every connection pooler needs

PgBouncer is not a database. It is a single-threaded, event-driven proxy that multiplexes many client connections onto a smaller set of PostgreSQL connections, and it should be monitored the way you monitor HAProxy or nginx: queueing, connection exhaustion, and process health. The teams that get burned monitor PgBouncer with their PostgreSQL playbook (replication lag, WAL, bloat) and never check whether clients are actually waiting for connections.

This checklist is organized by maturity level. Start at Level 1, get it alerting correctly, then work down. Every signal below comes from the admin console, the process table, or the PgBouncer log. There is no other source.

Two facts shape everything that follows:

• PgBouncer has zero error counters. No SHOW command exposes authentication failures, connection refusals, or query timeouts. Those live only in the log file. A monitoring strategy that only scrapes SHOW commands is blind to every error condition.
• The admin console is your only real-time window. Connect to the virtual pgbouncer database: psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer. Monitoring users belong in stats_users, not admin_users.

Level 1: survival

The bare minimum to know PgBouncer is alive and not actively harming traffic. Four signals. If you monitor nothing else, monitor these.

Functional check, not port check. A hung event loop still shows LISTEN on the port. SHOW VERSION hanging while ss shows the socket open means the event loop is stalled, which is worse than a clean death because supervisors will not restart it.

cl_waiting is the single most important PgBouncer metric. Zero means every client is being served immediately. Nonzero means the pool cannot keep up and clients are blocked. Teams that monitor connection counts and process up/down but not cl_waiting miss connection starvation entirely. No error is raised until query_wait_timeout (default 120s) fires, and by then the application has been degraded for two minutes.

Log tailing belongs in Level 1. Grep the log for no more connections allowed, auth failed, and timeout keywords. This is the only place connection refusals and auth failures appear.

Level 2: operational

Everything in Level 1, plus the signals that let you diagnose why clients are waiting and how much headroom remains.

Alert on maxwait, not on cl_waiting > 0. Alerting on any nonzero cl_waiting floods you with false positives from normal burst queuing in transaction mode. The signal that separates “brief acceptable spike” from “clients are stuck” is maxwait crossing a threshold and staying there. As a guideline: >1s is noticeable, >5s is user-impacting, >15s means applications are failing. Tune against your application’s actual connection timeout.

Always read avg_wait_time and avg_query_time together. This pair attributes latency correctly. High avg_wait_time with low avg_query_time: PostgreSQL is fast, the pool is too small, fix PgBouncer. Low avg_wait_time with high avg_query_time: the pool is fine, PostgreSQL is slow, fix the database. Operators who skip this comparison blame the wrong system. Note that avg_wait_time had a calculation bug fixed in PgBouncer 1.23.0; on older versions, maxwait from SHOW POOLS is the more trustworthy signal.

avg_xact_time versus avg_query_time detects idle-in-transaction. If transaction time is 10x query time, clients are holding server connections while doing non-database work. That gap is the most common silent cause of pool exhaustion in transaction mode, and no PgBouncer alert fires for it. You have to compute the ratio.

sv_idle is inventory, not waste. In transaction mode, idle server connections are the ready pool. Seeing high sv_idle and shrinking pool_size to “save resources” removes your burst absorption and accelerates the path to queuing. The correct concern is sv_idle sustained at zero: you are one slow query away from a cascade, even while cl_waiting still reads zero.

Validate max_client_conn against the FD limit. Each proxied connection costs roughly two FDs (client socket plus server socket), plus listening sockets, log files, pipe FDs, and admin sockets. Setting max_client_conn = 10000 under a default ulimit -n of 1024 means PgBouncer keeps the setting but can hit the FD ceiling and refuse connections well below that max; its startup log reports the limit and expected FD use for comparison. Budget the FD limit as at least max_client_conn x 2 + 500. Check reality:

# Compare open FDs against the process limit
PGBPID=$(pgrep -f pgbouncer)
ls /proc/$PGBPID/fd | wc -l
grep "Max open files" /proc/$PGBPID/limits

Remember PgBouncer is single-threaded. CPU saturation cannot be fixed by adding cores to the box. Per-process CPU near one full core (TLS termination and connection churn are the usual drivers) means horizontal scaling: multiple PgBouncer processes with so_reuseport, or more instances behind a load balancer. With multi-process deployments, each process has independent pools and stats, so monitoring must aggregate across all of them.

Level 3: mature

Everything above, plus per-pool breakdowns, state context, and the leading indicators that catch trouble before clients queue.

High sv_login with low sv_active is a distinct failure. It means the pool is trying and failing to establish backend connections: PostgreSQL down or at max_connections, network partition, credential mismatch, or DNS failure. Existing connections keep working until they expire, so the pool drains slowly before anything queues hard. Do not confuse this with pool exhaustion, where sv_active is pinned at pool_size and connections are healthy but busy.

Suppress alerts on paused and disabled databases. During PAUSE, cl_waiting spikes and sv_active drains to zero, which is byte-for-byte identical to a real outage from a metric perspective. Every PgBouncer alert must check the paused and disabled columns and stay quiet during administrative operations. DISABLE rejects new clients but lets existing ones finish; SUSPEND stops database socket I/O while keeping the admin pool available so RESUME remains reachable.

Sustained reserve pool usage masks an undersized base pool. Reserve connections (only relevant when reserve_pool_size > 0, default disabled) are overflow for brief spikes, activated after clients wait beyond reserve_pool_timeout (default 5s). If you are drawing from the reserve regularly, raise pool_size. When base and reserve both exhaust, the queuing cliff is even steeper.

Aggregate dashboards hide per-pool incidents. Pools are per (database, user). One saturated pool causing real user impact disappears into an average if the other nine pools are idle. Always break down by pool.

DNS staleness is the quiet failover killer. After a primary failover, PgBouncer’s DNS cache keeps pointing at the dead host until dns_max_ttl expires. Existing connections degrade while new ones fail. SHOW DNS_HOSTS is the only way to see which IP PgBouncer is actually using.

Level 4: expert

Add these after your second or third real incident, when the basics are stable.

• Server assignment rate (avg_server_assignment_count, added in 1.23): pool turnover efficiency. A drop with stable query rate suggests clients are queueing instead of being assigned.
• Prepared statement counters (total_client_parse_count/avg_client_parse_count, total_server_parse_count/avg_server_parse_count, and total_bind_count/avg_bind_count, added in 1.24): relevant if you rely on max_prepared_statements for transaction-mode prepared statement support.
• Connection lifetime analysis: SHOW CLIENTS connect_time to find leaked connections held for hours.
• SHOW CLIENTS and SHOW SERVERS correlation: trace a stuck server connection through the link column back to the source IP of the client holding it.
• Log-based error rate dashboards: auth failures, refusals, and timeout events by type, requiring real log parsing infrastructure.
• Application-side latency correlation: confirm PgBouncer’s avg_wait_time, not network or app code, is the actual bottleneck.

Instrumentation limits to design around

• No percentiles. Averages hide bimodal distributions; 95% fast queries and 5% catastrophic ones average out to “fine.”
• Snapshot blindness. SHOW POOLS is point-in-time. Polling every 10 seconds misses sub-second queue spikes.
• Stats reset on restart. All total_* counters zero out. Use the avg_* per-second columns or compute deltas and handle resets, or every restart looks like a traffic collapse.
• Column positions shift between versions. 1.23 added server-assignment counters and 1.24 added prepared-statement counters. Reference columns by name, never by position.
• Pool mode changes what metrics mean. In session mode, high sv_active and cl_active are expected because connections are held for the whole session. In transaction mode, brief sv_active spikes to 100% are normal if cl_waiting stays zero. And no PgBouncer metric detects pool-mode mismatch damage (prepared statements, temp tables, SET variables vanishing between transactions). Only application error logs reveal that.

How Netdata helps

• Netdata collects PgBouncer’s SHOW POOLS, SHOW STATS, SHOW LISTS, and SHOW DATABASES output per second, turning snapshot metrics like cl_waiting, maxwait, and sv_active into time series you can alert on with duration conditions.
• Per-pool breakdowns are preserved, so one saturated (database, user) pool is visible instead of being averaged away.
• Plotting avg_wait_time against avg_query_time on the same dashboard makes the “pool too small” versus “database too slow” attribution a glance instead of a forensic exercise.
• Host-level correlation closes the gaps the admin console cannot: PgBouncer process CPU against per-core saturation, open FD count against the process limit, and RSS against expected connection footprint.
• Because PgBouncer exposes no error counters, pairing metric collection with log monitoring for no more connections allowed, auth failed, and timeout events covers the failure modes SHOW commands never will.

Related guides

• How PgBouncer actually works in production: a mental model for operators
• PgBouncer monitoring maturity model: from survival to expert
• PgBouncer pool exhaustion: clients queue, wait times climb, and the retry cascade
• PgBouncer maxwait high: the oldest client waiter and how close it is to timing out
• PgBouncer avg_wait_time high: the latency the pool itself is injecting
• PgBouncer query_wait_timeout: clients disconnected after waiting too long for a connection
• PgBouncer pool utilization high: sv_active approaching pool_size before clients queue
• PgBouncer sv_idle at zero: no headroom and one slow query from a cascade
• PgBouncer pool_size sizing: matching pool capacity to transaction time and throughput
• PgBouncer reserve pool activation: overflow capacity that hides an undersized pool
• PgBouncer capacity planning: runway for pools, clients, and PostgreSQL slots
• PgBouncer prepared statement does not exist: transaction pooling and lost session state