Wait event, and the wait event types

A wait event names the specific thing a PostgreSQL process is blocked on at the instant you look. Every backend and every background process publishes one, or publishes nothing when it is running rather than waiting. The event has two parts: a type, which is the class of resource, and a name, which is the individual resource inside that class. pg_stat_activity carries both, sampled live, with no history and no aggregation of any kind.

Why the type is the half worth learning

There are hundreds of event names and roughly ten types, and the type is what turns an unfamiliar name into a direction. Lock means a heavyweight lock held by another transaction, so the answer is in the blocking tree. LWLock means a short internal lock on a shared structure, so the answer is a contended buffer or cache, not another user’s query. IO means the process is inside a read or a write. Client means the server is waiting for the application to say something, which is a network or an application problem wearing a database costume. Activity and Timeout are idle background processes on their normal loop, and counting them as load is the most common mistake made with this view.

That last distinction matters more than it looks. A naive dashboard that graphs “waiting sessions” over pg_stat_activity will show a flat several-process baseline on an idle server, because the checkpointer, the walwriter and the autovacuum launcher are all parked on an Activity event forever. Filter on backend_type = 'client backend' before you count anything.

The other trap is stability. Event names are not a contract across majors, and neither is their capitalisation.

Sampling what the processes are on

One grouped read of the live view gives the shape of the moment.

SELECT wait_event_type, wait_event, count(*) AS processes
FROM pg_stat_activity
WHERE wait_event_type IS NOT NULL
GROUP BY wait_event_type, wait_event
ORDER BY wait_event_type, wait_event;

 wait_event_type |     wait_event      | processes 
-----------------+---------------------+-----------
 Activity        | AutoVacuumMain      |         1
 Activity        | BgWriterMain        |         1
 Activity        | CheckpointerMain    |         1
 Activity        | LogicalLauncherMain |         1
 Activity        | WalWriterMain       |         1
(5 rows)

That capture is from 14.24, an idle server with nothing but its own background processes, and every row is the Activity noise floor described above. The same query on 18.6 returns AutovacuumMain and BgwriterMain, capitalised differently, plus three rows for the I/O worker processes that major introduced. A rule matching event names by string across a fleet of mixed versions will silently stop matching on the day one node is upgraded.

Because this is a sample and not a counter, one reading tells you nothing. The useful signal comes from sampling the view on a short interval and counting how often each event appears, which is what the pg_wait_events catalogue in PostgreSQL 17 and later helps you label but does not collect for you.

Turning samples into a diagnosis

Sampling, storing and reading back the result is a small system in itself, and the guide on active session history is the one that builds it, including what interval is honest and what to keep. When the type comes back as Lock the question stops being statistical and becomes a specific question about who holds what, which lock contention and blocking trees answers.