Skip to main content
View rawEdit

Wait event metrics

Active session history and wait event metrics from pg_stat_activity.

Data source​

Wait event data is collected from pg_stat_activity:

select
  pid,
  state,
  wait_event_type,
  wait_event,
  query
from pg_stat_activity
where backend_type = 'client backend';

Core metrics​

Session state metrics​

MetricTypeDescription
pg_stat_activity_countGaugeSessions by state
pg_stat_activity_max_tx_duration_secondsGaugeLongest running transaction
pg_stat_activity_oldest_query_secondsGaugeOldest active query duration

Wait event metrics​

MetricTypeDescription
pg_wait_event_countGaugeSessions waiting by event type
pg_wait_event_activity_countGaugeSessions in activity wait states

Labels​

Session state labels​

LabelValuesDescription
stateactive, idle, idle in transaction, idle in transaction (aborted), fastpath function call, disabledSession state
datnameDatabase nameTarget database
usenameUser nameConnected user

Wait event labels​

LabelValuesDescription
wait_event_typeCPU, IO, Lock, LWLock, BufferPin, Activity, Extension, Client, IPC, TimeoutWait category
wait_eventVariousSpecific wait event

Wait event categories​

CPU​

On-CPU processing, no actual wait:

EventDescription
CPUQuery execution on CPU

IO​

Disk I/O operations:

EventDescription
DataFileReadReading data file blocks
DataFileWriteWriting data file blocks
DataFileExtendExtending data file
DataFileFlushFlushing data file
WALReadReading WAL
WALWriteWriting WAL
WALSyncSyncing WAL to disk

Lock​

Row and table-level locks:

EventDescription
relationTable lock wait
tupleRow lock wait
transactionidTransaction lock wait
virtualxidVirtual transaction lock

LWLock​

PostgreSQL internal lightweight locks:

EventDescription
buffer_contentBuffer content lock
buffer_mappingBuffer mapping lock
WALInsertWAL insertion lock
lock_managerLock manager lock
ProcArrayProcess array lock

BufferPin​

Buffer pinning waits:

EventDescription
BufferPinWaiting for buffer pin

Activity​

Background process waits:

EventDescription
LogicalLauncherMainLogical replication launcher
AutoVacuumMainAutovacuum launcher
BgWriterMainBackground writer
CheckpointerMainCheckpointer process
WalWriterMainWAL writer

Common queries​

Sessions by state​

sum by (state) (pg_stat_activity_count)

Wait events distribution​

sum by (wait_event_type) (pg_wait_event_count)

Active (non-idle) sessions​

sum(pg_stat_activity_count{state!~"idle.*"})

Sessions waiting on locks​

sum(pg_wait_event_count{wait_event_type="Lock"})

I/O wait ratio​

sum(pg_wait_event_count{wait_event_type="IO"})
/
sum(pg_stat_activity_count{state="active"})

Long-running transactions​

pg_stat_activity_max_tx_duration_seconds > 300

Dashboard usage​

These metrics are used in:

Troubleshooting​

No wait event data​

  1. Verify pgwatch is collecting from pg_stat_activity:

    docker compose logs pgwatch | grep -i "stat_activity"

  2. Check monitoring user permissions:

    grant pg_read_all_stats to postgres_ai_mon;

Wait events show "unknown"​

Some wait events may not be captured if the session state changes between sampling intervals. This is normal for very short waits.

High "idle in transaction" count​

Indicates connection leaks or application issues:

select pid, usename, state, query_start, query
from pg_stat_activity
where state = 'idle in transaction'
order by query_start;