Skip to main content
View rawEdit

Metrics reference

Reference documentation for all metrics collected by PostgresAI monitoring.

Metric sources​

PostgresAI monitoring collects metrics from multiple PostgreSQL sources:

pgwatch metric groupUnderlying view(s)Dashboard usage
pg_stat_statementspg_stat_statements02, 03
pg_stat_activity / wait_eventspg_stat_activity01, 04
table_stats / pg_stat_all_tablespg_stat_all_tables07, 08, 09
pg_stat_all_indexes / pg_statio_all_indexespg_stat_all_indexes, pg_statio_all_indexes10, 11
pg_stat_replication / replicationpg_stat_replication06
bgwriterpg_stat_bgwriter01
db_statspg_stat_database01

Metric naming convention​

pgwatch exports each series as:

pgwatch_{metric-group}_{column}

Examples (these are the names you query in VictoriaMetrics/Grafana):

  • pgwatch_pg_stat_statements_calls — query calls (no _total suffix)
  • pgwatch_pg_stat_activity_count — session count
  • pgwatch_pg_stat_all_tables_seq_tup_read — tuples read by sequential scans
  • pgwatch_db_stats_xact_commit — transactions committed

There is no pg_{source}_{metric_name} naming in this stack; all series carry the pgwatch_ prefix and use the column name (not a _total/_seconds suffix convention).

Collection intervals​

Intervals are set per metric group in config/pgwatch-prometheus/metrics.yml (the full preset). Representative defaults:

Metric groupDefault interval
pg_stat_activity, wait_events15s
pg_stat_statements30s
table_stats, pg_stat_all_tables, pg_stat_all_indexes30s
db_stats, bgwriter, replication30s
settings300s
Bloat groups (pg_table_bloat, pg_btree_bloat)7200s

Metric categories​

pg_stat_statements metrics​

Query performance metrics including:

  • Execution counts and timing
  • Row counts
  • Buffer usage
  • Planning time

Wait event metrics​

Active session history data:

  • Wait event types and categories
  • Session state distribution
  • Lock wait analysis

Table metrics​

Table-level statistics:

  • Sequential vs index scans
  • Dead tuple counts
  • HOT update ratios
  • Table sizes

Index metrics​

Index usage and health:

  • Scan counts
  • Tuple reads
  • Index sizes
  • Bloat estimates

System metrics​

PostgreSQL system-level metrics:

  • Connection counts
  • Transaction rates
  • Checkpoint activity
  • Buffer cache statistics

Prometheus/VictoriaMetrics queries​

All metrics are stored in VictoriaMetrics (Prometheus-compatible). Example queries:

Rate calculations​

# Queries per second
rate(pgwatch_pg_stat_statements_calls[5m])

# Transactions per second
rate(pgwatch_db_stats_xact_commit[5m])

Aggregations​

# Active sessions across all databases (the activity metric carries a `state` label)
sum(pgwatch_pg_stat_activity_count{state="active"})

# Average exec time per call by database. There is no mean_exec_time series;
# derive it from the cumulative exec_time_total (ms) and calls counters.
sum by (datname) (rate(pgwatch_pg_stat_statements_exec_time_total[5m]))
/
sum by (datname) (rate(pgwatch_pg_stat_statements_calls[5m]))