$ guides / pgbouncer / pgbouncer-high-cpu ▌

Operations Guides

PgBouncer high CPU: single-core saturation, TLS, and connection churn

PgBouncer is consuming a disproportionate share of one CPU core. The process sits at 70%, 90%, or 100% of a single core while system-wide CPU looks normal. Application queries slow down and the admin console feels sluggish.

PgBouncer is a single-threaded, event-driven process built on libevent. It runs on exactly one CPU core regardless of how many cores the machine has. A busy PgBouncer looks nearly idle on a multi-core box because system-wide CPU averages dilute the one saturated core. Measure per-process or per-core CPU, not system-wide averages.

Under normal conditions, PgBouncer uses less than 5% of one core, even with thousands of established connections. Anything above 30% is unusual. The dominant cause is TLS handshake overhead under high connection churn, followed by verbose logging, SCRAM authentication storms, and very high query-per-second rates (above roughly 100k QPS).

How CPU saturation affects the event loop

When PgBouncer’s single thread saturates its CPU core, the event loop cannot keep up. Every operation slows proportionally: client reads, server writes, admin queries, DNS resolution, authentication. All pools degrade simultaneously because they share the same thread.

The admin console is the best proxy for event loop health. Under normal conditions, SHOW LISTS responds in under 50ms. Above 200ms, something is straining the event loop. Above 1-2 seconds, the loop is effectively stalled and all traffic is affected.

flowchart TD
    A[PgBouncer CPU above 30% of one core] --> B{TLS configured?}
    B -- Yes --> C{Connection churn high?}
    C -- Yes --> D[TLS handshake overhead]
    C -- No --> E[Check logging level]
    B -- No --> F{QPS above 100k?}
    F -- Yes --> G[Throughput-driven saturation]
    F -- No --> H{Auth failures spiking?}
    H -- Yes --> I[SCRAM or auth_query cost]
    H -- No --> J[Check prepared statement tracking]

Common causes

Cause	What it looks like	First thing to check
TLS handshakes under connection churn	CPU spikes track new connection rate, not query throughput	`SHOW CLIENTS` tls column; log connection rate
Verbose logging	CPU proportional to query/transaction rate; log file growing fast	`SHOW CONFIG` for log_connections, log_disconnections, log_stats
SCRAM authentication storms	sv_login elevated, auth failures or spikes in log	Log grep for auth failures; `SHOW POOLS` sv_login
Very high QPS	CPU proportional to throughput, no other anomaly	`SHOW STATS_AVERAGES` avg_query_count column
Prepared statement tracking overhead	CPU elevated after upgrade to 1.24+ with default config	`SHOW CONFIG` max_prepared_statements

Quick checks

All read-only and safe to run during an incident.

# Check per-process CPU of PgBouncer (not system-wide)
PGBPID=$(pgrep -f pgbouncer)
top -bn1 -p $PGBPID | tail -1

# Time the admin console response (should be under 50ms normally)
time psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW LISTS;" > /dev/null

# Check TLS status of client connections (inspect the tls column)
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW CLIENTS;"

# Check logging configuration
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW CONFIG;" | grep -E "log_connections|log_disconnections|log_stats|log_level"

# Check query throughput
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW STATS_AVERAGES;"

# Check server login queue and pool states (look at sv_login column)
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -c "SHOW POOLS;"

# Check prepared statement tracking config
psql -h 127.0.0.1 -p 6432 -U pgbouncer pgbouncer -Atc "SHOW CONFIG;" | grep max_prepared_statements

# Count recent connection/disconnection log lines (connection churn indicator)
# Adjust the log path to match your deployment
grep -c "login\|disconnect" /var/log/pgbouncer/pgbouncer.log

How to diagnose it

Confirm the CPU is actually PgBouncer’s. Check per-process CPU, not system-wide. On a 16-core box, one core at 100% shows as roughly 6% system CPU. Use top -p $(pgrep pgbouncer) or per-core CPU metrics.
Check admin console latency. Run time psql ... -c "SHOW LISTS;". If it takes more than 200ms, the event loop is under pressure. Above 1-2 seconds, the loop is near-stalled. This confirms the saturation is affecting operations, not just appearing as a monitoring artifact.
Correlate CPU with connection rate, not just query rate. If CPU spikes track new connections per second rather than queries per second, TLS handshakes are the likely driver. If log_connections and log_disconnections are enabled (both default to 1), high churn means high CPU from both TLS and logging simultaneously.
Check whether TLS is in use. Run SHOW CLIENTS and inspect the tls column. If connections show TLS version and cipher strings (for example TLSv1.3/ECDHE-RSA-AES256-GCM-SHA384/256bits), every new connection requires a full TLS handshake on PgBouncer’s single thread. The asymmetric cryptography overhead is the largest CPU consumer.
Check the logging configuration. Run SHOW CONFIG and look at log_connections (default 1), log_disconnections (default 1), log_stats (default 1), and log_level. Under high connection churn with defaults, PgBouncer writes two log lines per connection lifecycle plus periodic stats every stats_period seconds (default 60). At thousands of connections per second, log serialization becomes a measurable CPU drain.
Check authentication pressure. Look at sv_login in SHOW POOLS and grep the log for auth failures. If sv_login is persistently elevated, PgBouncer is churning through backend authentications. SCRAM-SHA-256 is computationally expensive, and a storm of simultaneous logins amplifies this. PgBouncer 1.25.0 specifically improved SCRAM performance (“Greatly improve performance of ad hoc SCRAM authentication”, PR #1338).
Check prepared statement tracking. 1.21.0 introduced max_prepared_statements with a default of 0. 1.23.0 changed the default to 200, enabling prepared statement support out of the box. If max_prepared_statements is non-zero, PgBouncer inspects and rewrites every query, adding CPU overhead proportional to query rate. If your workload does not need protocol-level prepared statement support, setting max_prepared_statements to 0 eliminates this cost.
Check for event loop monopolization. If sbuf_loopcnt is set to 0 (unlimited), a single connection streaming a large result set can monopolize the event loop, starving all other connections. The default of 5 is safe. Verify via SHOW CONFIG.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
Per-process CPU (% of one core)	PgBouncer is single-threaded; one core is the ceiling	Above 30% is unusual; above 70% is approaching saturation
Admin console latency	Proxy for event loop health	Above 200ms warrants investigation; above 2s is a stall
New connections per second	TLS handshake rate is the dominant CPU driver	Sustained high rate with TLS enabled
`avg_query_count` from SHOW STATS_AVERAGES	Pure throughput pressure	Above roughly 100k QPS, CPU becomes relevant even without TLS
`sv_login` from SHOW POOLS	Backend authentication pressure	Persistently above 0 with auth failures in log
`avg_wait_time`	Pool-induced latency from event loop pressure	Non-zero across all pools simultaneously (not pool-specific)
`max_prepared_statements` config	Query inspection and rewrite overhead	Non-zero value on 1.24+ with high QPS

Fixes

Reduce TLS overhead

TLS handshakes are the single biggest CPU cost. Two approaches:

Terminate TLS in front of PgBouncer. Place a TCP load balancer (HAProxy, Envoy, or similar) between clients and PgBouncer. The load balancer handles TLS termination, and connections from it to PgBouncer are plaintext. This offloads all cryptographic work from PgBouncer’s single thread. The tradeoff is an additional network hop and another component to manage.

Reduce connection churn. If TLS must stay on PgBouncer, reduce how often new TLS handshakes occur. Fix application-side connection pooling to minimize connection cycling. Longer-lived client connections mean fewer handshakes per second. Review your application’s connection pool settings to ensure connections are reused across requests, not opened and closed per operation.

Reduce logging overhead

Under high connection churn, the default log_connections=1 and log_disconnections=1 produce two log writes per connection lifecycle. At scale, log serialization competes with the event loop for CPU.

Set log_connections and log_disconnections to 0 if you have external monitoring that tracks connection rates independently. Keep them enabled during initial debugging or when investigating specific connection issues. The log_stats setting (default 1) writes aggregated stats every stats_period seconds (default 60). This is a minor cost but can be disabled if you scrape stats via SHOW commands externally.

Reduce authentication overhead

If SCRAM authentication is driving CPU during login storms, consider upgrading PgBouncer to 1.25.0 or later, which greatly improved ad-hoc SCRAM authentication performance (PR #1338). The scram_iterations setting (default: 4096, matching RFC 5802) controls the hash iteration count. Lowering it reduces CPU per authentication but also weakens security. Coordinate with your security team before changing this value.

If you use auth_query, ensure the auth_user has a reserved connection slot on PostgreSQL so auth queries do not compete with client traffic during overload.

Scale out: multi-process PgBouncer

When a single PgBouncer process cannot keep up, run multiple processes sharing the listen port via so_reuseport (available since v1.12). Each process is still single-threaded, but the kernel distributes incoming connections across processes, giving you multi-core scaling.

Key operational considerations:

Each process has independent pools and stats. max_client_conn, pool_size, and max_db_connections apply per process, not globally. Divide your connection budget across processes manually.
SHOW STATS shows only one process. Monitoring must aggregate across all processes by querying each one.
Cancel requests need peering. A Postgres cancel request arrives on a new connection with a cancel key. The kernel may route it to a different process than the one holding the session. Peering (available since v1.19) forwards the cancel to the correct process. Without peering, cancel requests can silently fail under so_reuseport.
Pool limits are not shared. Each process maintains its own pool against PostgreSQL. The total server connection budget across all processes must fit within PostgreSQL’s max_connections.

Alternatively, run multiple PgBouncer instances on different ports behind a TCP load balancer. This gives the same multi-core benefit without so_reuseport complexity, at the cost of managing multiple listen ports and ensuring the load balancer distributes evenly.

Prevention

Monitor per-process CPU, not system-wide. A single-core saturation pattern is invisible in aggregate CPU charts. Alert on PgBouncer’s process CPU relative to a single core, not total system CPU.
Set a CPU threshold for capacity planning. PgBouncer normally uses under 5% of one core. Use 50% at peak as the trigger to plan scale-out. Do not wait for 100%.
Track connection churn rate. Monitor new connections per second from the PgBouncer log or from deltas in SHOW STATS. A rising churn rate with TLS enabled is a leading indicator of CPU pressure.
Review logging defaults under load. Disable log_connections and log_disconnections once your monitoring tracks connection rates independently.
Plan the scale-out path before you need it. so_reuseport, peering, and load balancer integration require testing. Do not configure multi-process PgBouncer for the first time during an incident.

How Netdata helps

Per-process CPU monitoring catches the single-core saturation pattern that system-wide CPU averages hide. Netdata shows how much of one core PgBouncer is consuming, not a diluted multi-core average.
Admin console latency tracking provides an event loop health proxy. Correlating admin console response time with CPU spikes confirms whether the event loop is the bottleneck.
Connection rate correlation lets you overlay new connections per second against PgBouncer process CPU. If the two track together, TLS handshakes are the driver.
avg_wait_time and avg_query_time side by side distinguish pool-induced latency (elevated wait time across all pools) from backend-induced latency (elevated query time). When CPU saturation affects the event loop, avg_wait_time rises uniformly across all pools.
Per-second metric resolution captures connection churn spikes that longer polling intervals miss. A burst of TLS handshakes lasting a few seconds may not appear in 60-second averages but will drive CPU to 100% during that window.