Understand
Mental model
A useful investigation moves across four evidence windows: what sessions are doing now, what counters accumulated over time, what the server logged at the moment of failure, and what the operating system saw. No single window can prove the whole story.
Calibrate
What healthy usually looks like
- Active sessions are doing attributable work rather than waiting in unexplained queues.
- Statistics reset times and collection settings are known.
- Slow-query and error logs retain enough context to reconstruct an incident without logging every statement.
Observe
Ask the database a bounded question
Diagnostic query
See current sessions and waits
Find long-running activity, idle transactions, and sessions waiting on locks, I/O, clients, or internal resources.
SELECT
pid,
usename AS user_name,
application_name,
state,
wait_event_type,
wait_event,
now() - query_start AS query_age,
now() - xact_start AS transaction_age,
left(query, 140) AS query_preview
FROM pg_stat_activity
WHERE datname = current_database()
AND pid <> pg_backend_pid()
ORDER BY query_age DESC NULLS LAST;low observation cost
Interpret
Read the output
- Take observations close together and record timestamps; a current-activity view can change between two queries.
- Prefer rates and distributions over isolated averages. A stable average can hide a damaging tail.
- Preserve query identifiers so evidence from activity, logs, plans, and statement statistics can be connected.
Avoid
Common traps
- Assuming an active session is consuming CPU when it may be waiting.
- Using averages without calls, total time, and variability.
- Resetting statistics during an incident before capturing their timestamp and useful counters.
Verify
Check your reasoning
Continue
Related runbooks
Verify independently