Wait events: what is this backend actually waiting on? · PostgreSQL

state = 'active' means a backend is executing a statement. It does not mean the backend is doing anything. The wait event tells you which.

The classes

pg_stat_activity.wait_event_type puts every wait into a class, and the class alone narrows the problem enormously.

Type	Means	Typically
`Lock`	Waiting for a heavyweight lock	Application contention. Part IX
`LWLock`	Waiting for an internal shared-memory lock	Internal contention
`IO`	Waiting for storage	Slow disk, or too little cache
`BufferPin`	Waiting to pin a buffer another backend holds	Rare
`Client`	Waiting for the client	Not the database’s problem
`IPC`	Waiting for another PostgreSQL process	Parallel query, sync rep
`Timeout`	Sleeping deliberately	Usually normal
`Extension`	An extension’s own wait	Depends
`NULL`	Not waiting. Actually running	On CPU

Sampling, not snapshotting

A single query against pg_stat_activity catches whatever happened to be true at that instant. One sample is an anecdote. A profile needs many.

Read-only / Safewait events sampled six times during a 16-client run— EXECUTION VALIDATED on 18.6. pgbench -c 16 -j 4 -T 25, sampled every three seconds. Format: samples | type|event|backends.

$ SELECT wait_event_type, wait_event, count(*)
FROM pg_stat_activity
WHERE backend_type='client backend' AND state='active'
GROUP BY 1,2 ORDER BY 3 DESC;

      6 IO|WalSync|1
    5 (running)|-|1
    3 Lock|tuple|3
    3 LWLock|WALWrite|2
    2 Lock|tuple|2
    2 Lock|transactionid|10
    2 LWLock|WALWrite|3
    1 Lock|transactionid|11
    1 Lock|transactionid|9
    1 Lock|transactionid|8
    1 Lock|transactionid|6

Up to eleven of sixteen backends waiting on Lock/transactionid simultaneously.

Lock/transactionid means: this backend wants a row that another transaction has modified and not yet committed, so it is waiting for that transaction to finish. It is row-level contention, and it is exactly Part IX’s subject seen from the waiting side.

The rest of the profile is consistent: Lock/tuple is the queue for the same rows, LWLock/WALWrite and IO/WalSync are the WAL write path under load.

-- a poor man's sampler: run every second, accumulate, and look at the shape
SELECT now(), wait_event_type, wait_event, count(*)
  FROM pg_stat_activity
 WHERE backend_type = 'client backend' AND state = 'active'
 GROUP BY 1, 2, 3;

Reading the common ones

Event	Means	Look at
`Lock/transactionid`	Waiting for another transaction’s row	The blocking transaction. Lesson IX-03
`Lock/relation`	Waiting for a table lock	DDL, or `LOCK TABLE`. Lesson IX-05
`Lock/tuple`	Queued for a row lock	Same root cause
`LWLock/WALWrite`	Waiting to write WAL	Commit rate, `wal_buffers`
`LWLock/BufferContent`	Contention on one buffer	A very hot page
`IO/DataFileRead`	Reading a table or index	`shared_buffers`, storage
`IO/WalSync`	Waiting for WAL fsync	Storage commit latency. Lesson VI-01
`Client/ClientRead`	Waiting for the application	The application
`IPC/SyncRep`	Waiting for a synchronous standby	Lesson XIV-05
`Timeout/VacuumDelay`	Autovacuum’s cost delay	Lesson VIII-03

Why PostgreSQL has no built-in wait-event history, and what to do about it

Oracle has ASH. PostgreSQL has pg_stat_activity and no history at all — the view is a live snapshot, and once a backend stops waiting there is no record it ever did.

This is a deliberate design choice rather than an oversight. Recording every wait transition would mean writing to shared memory on every state change, on a code path executed millions of times a second, and the instrumentation would cost more than the waits it measured. Sampling externally moves that cost outside the database and lets you choose it.

The practical consequences are worth planning for.

A wait you did not sample did not happen, as far as you can tell. Sampling at 1 Hz on a system where the average wait is 5 ms catches roughly one wait in two hundred. That is fine for a profile, because the frequent waits dominate the sample exactly as they dominate the system, and it is useless for finding the one query that blocked for four seconds last Tuesday.

Sample fast enough to be representative, and no faster. One second is a reasonable default; anything under 100 ms starts to have its own cost, because each sample scans every backend.

Bounded incidents need a different instrument. log_lock_waits records lock waits that exceeded deadlock_timeout, with the blocking process identified, and that is a durable history of exactly the waits you most want to know about. It is the right complement to sampling: sampling gives you the shape of normal, and log_lock_waits gives you the individual events that were bad enough to matter.

The pg_wait_sampling extension does in-database sampling and accumulates a history, which is closer to ASH and is the right answer when you need this often enough to justify an extension.

The instrument choice follows from the question. Where does time generally go? — sample. What blocked at 03:14? — the log. Which statement costs most in aggregate? — pg_stat_statements. Reaching for the wrong one produces an answer that is confidently wrong rather than absent, which is worse.

What to take from this

state = 'active' says executing, not working. The wait event says which.
The class narrows it enormously: Lock is application contention, IO is storage, Client is not your problem.
Client/ClientRead with idle in transaction is lesson VII-05’s problem in one row.
Sample repeatedly; one reading is an anecdote.
Measured: 11 of 16 backends on Lock/transactionid, corroborating pg_stat_statements from the opposite direction.
PostgreSQL keeps no wait history by design. Sample for shape, use log_lock_waits for individual events.

Cross-course references

Linux for Production Sysadmins — Part XXXVIII (Linux performance fundamentals) and Part XLIII (eBPF) cover confirming a wait event against what the kernel says the process is doing.
Observability for Production Sysadmins — Part LIX (Database observability) covers sampling wait events into a series, since a single sample is an anecdote.

The classes

Sampling, not snapshotting

Reading the common ones

What to take from this

Cross-course references

Quiz