Runbook category
Observability
Open this category when you cannot yet name the object that is on fire. Before you change work_mem, add an index, or touch vacuum settings, you need a statement id, a wait event, a buffer count, or a progress row you can quote. These runbooks are the instrumentation layer, the difference between guessing and measuring.
The failure modes are blindness and misread signals. pg_stat_statements ranking real cost, or lying because it was never loaded the way you think. EXPLAIN (ANALYZE, BUFFERS) separating disk from CPU. Wait events explaining a stalled session. The pg_stat_progress_* views that turn "is this VACUUM stuck or just slow?" into a block counter. Temp spills, cache hit ratio, checkpoint write pressure, rollback rate, pg_stat_io, and the Sev-1 habit of capturing evidence before recovery erases it.
Query performance is what you do once you have a plan. Vacuum & bloat and Locking & concurrency are what you do once the metric points at dead tuples or a blocker. WAL & replication is the disk and lag half of the same instrumentation story. Start here when the question is still "where do I look?"
- Free
Find your slowest queries with pg_stat_statements
Everything feels slow and you are guessing which query deserves the blame.
- Pro
Read EXPLAIN (ANALYZE, BUFFERS) like a pro
You cannot tell whether the query is slow from disk reads or from CPU.
- Pro
Track table and index bloat over time
You want a bloat early-warning number instead of finding out when the disk fills.
- Pro
Watch wait events in pg_stat_activity
A session is stuck and you need the reason, not another copy of the query text.
- Pro
Measure and raise your buffer cache hit ratio
Someone wants to buy RAM and nobody has measured whether reads miss the cache.
- Pro
Catch queries spilling to temp files
temp_bytes keeps climbing and no one can name the query writing it.
- Pro
Monitor VACUUM progress on a large table
A VACUUM has run for an hour and you cannot tell slow from stalled.
- Pro
Watch CREATE INDEX CONCURRENTLY progress
CREATE INDEX CONCURRENTLY reports zero blocks done and someone is about to cancel it.
- Pro
Track ANALYZE progress on large and partitioned tables
ANALYZE on a partitioned table looks hung, there is no output until it commits.
- Pro
Monitor a CLUSTER or VACUUM FULL rewrite
The table is locked for a full rewrite and the only question left is the ETA.
- Pro
Monitor COPY progress during a bulk load
A multi-gigabyte COPY prints nothing until it commits, so nobody can give an ETA.
- Pro
Diagnose I/O behavior with pg_stat_io
One cache-hit number for the whole cluster while a nightly report evicts your OLTP pages.
- Pro
Spot checkpoint write pressure before it hurts
Requested checkpoints are outrunning timed ones and I/O spikes follow.
- Pro
Catch a high transaction rollback rate
A retry loop quietly rolls back four transactions in ten and everything looks fine.
- Pro
Read pg_locks: relation waits versus tuple waits
pg_locks shows you the granted row, not the waiting one, and you read it wrong.
- Free
Capture Sev-1 evidence before recovery erases it
Every postmortem ends at 'high load' because the evidence was gone by morning.
- Pro
Find out whether pg_stat_statements is lying to you
The slow-query dashboard is empty, or the query you are hunting is not in it.
- Pro
Find what is actually burning CPU
CPU is pinned at 100% and every session looks busy, but you cannot name the query.
- Pro
Know whether you could detect page corruption
A query fails on one block, and nobody can say which table it is or how long it has been wrong.