Metrics

PostgreSQL v2 exposes a combination of infrastructure and database health metrics so you can monitor the state of your clusters. Infrastructure metrics describe the underlying node's resource usage, while database health metrics describe the behavior of the PostgreSQL engine itself.

Infrastructure metrics

Infrastructure metrics describe the health of the underlying node that hosts a database cluster, rather than the database engine itself. These metrics are collected by node_exporter and cover CPU, memory, disk I/O, filesystem capacity, and network throughput at the operating-system level. Use them together with database-specific metrics to distinguish node-level resource constraints, such as CPU saturation or low disk space, from issues originating inside the database engine.

The following metrics are available to gauge the infrastructure health of a database cluster.

CPU and system load

Metric	Description
node_cpu_seconds_total	Cumulative CPU time spent in each mode (idle, user, system, I/O wait) per core. Apply rate() to convert to per-second usage. Monitor this metric to detect storage bottlenecks that degrade query execution. Alert if I/O wait exceeds 1%.
node_load1	Average number of runnable or uninterruptible processes over the last minute. Reflects immediate CPU demand on the node. Monitor this metric to detect contention that delays query processing. A sustained value above the number of available CPU cores indicates load pressure.
node_load5	Average number of runnable or uninterruptible processes over the last 5 minutes. Smooths short-lived spikes to confirm whether a node_load1 spike represents a genuine load trend. Monitor this metric to distinguish transient spikes from sustained pressure.
node_load15	Average number of runnable or uninterruptible processes over the last 15 minutes. Serves as a long-term trend indicator. Monitor this metric to assess sustained workload growth and plan capacity adjustments for the cluster.
node_boot_time_seconds	Unix timestamp recording when the node last started. Subtract this value from the current time (time() - node_boot_time_seconds) to derive node uptime. Monitor this metric to detect unexpected restarts or failover events in the cluster.

Memory

Metric	Description
node_memory_MemAvailable_bytes	Estimated memory available for new allocations without swapping, accounting for reclaimable memory and buffers. Monitor this metric to detect memory pressure that can slow queries. Alert if the value falls below 10% of node_memory_MemTotal_bytes.
node_memory_MemTotal_bytes	Total physical memory installed on the node. Use the value as the denominator when calculating the memory utilisation ratio (1 - MemAvailable_bytes / MemTotal_bytes).

Disk I/O

Metric	Description
node_disk_io_time_seconds_total	Cumulative time the disk device was actively processing I/O requests. Apply rate() to obtain a utilisation ratio between 0 and 1. Monitor this metric to detect I/O saturation. A ratio above 0.9 indicates saturation that can degrade query or command execution.
node_disk_read_bytes_total	Cumulative bytes read from the disk device since node start. Apply rate() to derive read throughput in bytes per second. Monitor this metric to detect sequential scans or index rebuilds on the data volume.
node_disk_written_bytes_total	Cumulative bytes written to the disk device since node start. Apply rate() to derive write throughput in bytes per second. Monitor this metric to track write throughput and identify sustained write pressure on the data volume.
node_disk_reads_completed_total	Cumulative read operations successfully completed by the disk device. Apply rate() to compute read IOPS. Monitor this metric to detect frequent buffer cache misses that force data retrieval from disk.
node_disk_writes_completed_total	Cumulative write operations successfully completed by the disk device. Apply rate() to compute write IOPS. Monitor this metric to identify spikes from transaction commits, background maintenance operations, or bulk load operations.

Filesystem

Metric	Description
node_filesystem_avail_bytes	Bytes available to unprivileged processes on the filesystem, monitored separately for the DBDATA and BACKUP volumes. Monitor this metric to prevent write failures. Alert if the value falls below 15% of node_filesystem_size_bytes.
node_filesystem_size_bytes	Total capacity of the filesystem in bytes. Use the value as the denominator for the capacity utilisation ratio (1 - avail_bytes / size_bytes). Tracked across DBDATA and BACKUP mount points to support storage sizing decisions.

Network

Metric	Description
node_network_receive_bytes_total	Cumulative bytes received on the network adapter since node start. Apply rate() to derive inbound throughput in bytes per second. Monitor this metric to detect spikes in client connections, replication traffic, or backup data ingestion.
node_network_transmit_bytes_total	Cumulative bytes transmitted on the network adapter since node start. Apply rate() to derive outbound throughput in bytes per second. Monitor this metric to track large query result sets, replication traffic to standby nodes, or backup data egress.

Note: Interpret these Infrastructure metrics together with PostgreSQL engine behavior:

• Disk I/O utilisation (node_disk_io_time_seconds_total): Sustained saturation delays Write-Ahead Log (WAL) flushing and checkpoint completion. If checkpoint-triggered spikes are frequent, consider increasing max_wal_size.
• Write throughput (node_disk_written_bytes_total): Elevated write rates typically reflect checkpoint flushes and WAL archiving activity.
• Read IOPS (node_disk_reads_completed_total): High values may indicate frequent misses in the shared_buffers cache; consider increasing shared_buffers.
• Write IOPS (node_disk_writes_completed_total): Spikes often coincide with autovacuum runs on large or frequently updated tables.
• Network transmit throughput (node_network_transmit_bytes_total): Elevated values during write-heavy periods typically reflect WAL streaming to standby replicas.

Database health metrics

Unlike the infrastructure metrics, which describe the health of the underlying node, the metrics in this section come from postgres_exporter and describe the health of the PostgreSQL database engine itself. They report on activity inside the running instance, such as connection counts, database size, transaction throughput, checkpoint and WAL activity, replication status, vacuum and table maintenance, and query statistics, giving you visibility into database-level behavior that node-level resource metrics cannot show.

Note: The pg_stat_statements_sum_querycount metric requires the pg_stat_statements extension, which is active by default on PostgreSQL v2 clusters. For the list of preinstalled and available extensions, see Activate Extensions.

The following metrics are available to gauge the health and performance of PostgreSQL v2 clusters.

Database health and connections

Metric	Description
pg_up	Indicates whether PostgreSQL is reachable. A value of 1 means the instance is up; a value of 0 means it is unreachable. Alert immediately if the value is 0.
pg_stat_activity_count	The number of active sessions grouped by state. States include active, idle, idle in transaction, and others. Monitor this metric to understand connection usage patterns.
pg_stat_database_numbackends	The number of active connections per database. Compare this value with pg_settings_max_connections and alert when usage reaches 80% of the limit.
pg_settings_max_connections	The configured value of the max_connections PostgreSQL setting. Use this together with pg_stat_database_numbackends to calculate connection utilisation.
pg_settings_superuser_reserved_connections	The configured value of superuser_reserved_connections. Subtract this from pg_settings_max_connections to determine the effective connection limit available to regular users.

Database size

Metric	Description
pg_database_size_bytes	The size of each database on disk, measured in bytes. Monitor this metric to track growth and alert when approaching capacity thresholds.

Transactions and errors

Metric	Description
pg_stat_database_xact_commit	The cumulative number of committed transactions per database. Use rate() in PromQL to calculate transactions per second (TPS).
pg_stat_database_xact_rollback	The cumulative number of rolled-back transactions per database. A high rollback rate indicates application errors or logic issues.
pg_stat_database_deadlocks	The cumulative number of deadlock events per database. This value should remain close to zero; any non-zero reading warrants investigation.
pg_stat_database_conflicts	The cumulative number of query conflicts per database. This metric is most relevant when monitoring standby instances, where conflicts arise from replication activity.

Background maintenance and checkpoints

Metric	Description
pg_stat_bgwriter_checkpoints_timed	The cumulative number of checkpoints triggered by the scheduled checkpoint interval. This represents a stable baseline. Compare with pg_stat_bgwriter_checkpoints_req to assess checkpoint pressure.
pg_stat_bgwriter_checkpoints_req	The cumulative number of checkpoints triggered on demand because WAL volume exceeded the configured threshold. If this value consistently exceeds pg_stat_bgwriter_checkpoints_timed, consider increasing max_wal_size.
pg_wal_archive_rate	The rate at which WAL segments are archived. Monitor this metric to detect archiving backlogs or failures that could affect recovery point objectives.

Replication

Metric	Description
pg_replication_lag	The replication lag on a standby instance, measured in seconds. For critical workloads, alert when this value exceeds 30 seconds.
pg_replication_slots_active	The number of active replication slots. Inactive slots that retain WAL segments can cause disk exhaustion if not monitored and removed.

Vacuum and table activity

Metric	Description
pg_stat_user_tables_n_dead_tup	The number of dead (not yet vacuumed) tuples per table. High values indicate a vacuum backlog that may degrade query performance.
pg_stat_user_tables_last_autovacuum	The Unix timestamp of the last autovacuum run per table. Monitor the gap between runs; a long gap indicates that autovacuum is not keeping up with table activity.
pg_stat_user_tables_n_tup_ins	The cumulative number of rows inserted per table. Use rate() to calculate insert throughput.
pg_stat_user_tables_n_tup_upd	The cumulative number of rows updated per table. Includes both HOT and non-HOT updates.
pg_stat_user_tables_n_tup_del	The cumulative number of rows deleted per table. Use rate() to calculate delete throughput.
pg_stat_user_tables_n_tup_hot_upd	The cumulative number of HOT (Heap Only Tuple) updates per table. A high ratio of HOT updates to total updates indicates an effective fillfactor configuration.

Memory performance and query statistics

Metric	Description
pg_statio_user_tables_heap_blks_hit	The cumulative number of in-memory buffer hits for table data. Use together with pg_statio_user_tables_heap_blks_read to compute the hit ratio. The target hit ratio is above 99%.
pg_statio_user_tables_heap_blks_read	The cumulative number of disk reads for table data. A high value relative to in-memory hits indicates memory misses; consider increasing shared_buffers.
pg_stat_statements_sum_querycount	The total number of query executions across all tracked statements. Requires the pg_stat_statements extension to be enabled in the PostgreSQL configuration.

View metrics

You can view these metrics in the Grafana dashboard, accessed either through the DCD or through the API.