Alert Reference

This document lists all built-in alert rules included with the alerter. Each rule monitors a specific PostgreSQL metric and triggers an alert when the metric exceeds the threshold.

Connection Rules

High Connection Utilization

This rule alerts when database connection usage approaches the maximum limit.

A high connection utilization indicates the database may run out of available connections. Consider increasing max_connections or implementing connection pooling.

High Max Connections

This rule alerts when the max_connections setting exceeds a threshold.

A very high max_connections setting can degrade performance. Consider using a connection pooler such as PgBouncer instead of increasing the connection limit.

Blocked Sessions

This rule alerts when sessions are waiting for locks that other sessions hold.

Blocked sessions indicate lock contention. Investigate the blocking queries and consider optimizing the workload.

Long-Running Idle Transactions

This rule alerts when a transaction has been idle in transaction state too long.

Idle in transaction connections hold locks and prevent vacuum from reclaiming space. Configure idle_in_transaction_session_timeout to automatically terminate these connections.

Long Lock Wait Time

This rule alerts when a session has been waiting for a lock too long.

Long lock waits can indicate deadlock-prone workloads or inefficient query patterns.

Query Performance Rules

Long-Running Query

This rule alerts when a query has been executing for longer than the threshold.

Long-running queries may indicate missing indexes, inefficient query plans, or inappropriate workloads.

Long-Running Transaction

This rule alerts when a transaction has been active for longer than the threshold.

Long transactions can cause bloat and prevent vacuum from running effectively.

Slow Query Count

This rule alerts when the number of slow queries exceeds a threshold. The rule requires the pg_stat_statements extension.

A high slow query count indicates performance problems that need investigation.

Replication Rules

High Replication Lag (Time)

This rule alerts when replication replay is behind the primary.

Replication lag can indicate network issues, replica resource constraints, or write-heavy workloads.

High Replication Lag (Bytes)

This rule alerts when replication is behind by more than the specified byte count.

This metric provides a more accurate view of replication lag when write activity is bursty.

Inactive Replication Slot

This rule alerts when a replication slot becomes inactive.

Inactive replication slots prevent WAL cleanup and can cause disk exhaustion. Drop unused slots or reconnect the subscriber.

High Replication Slot WAL Retention

This rule alerts when a replication slot retains more WAL data than the threshold.

Large WAL retention by a replication slot can lead to disk exhaustion. Investigate the subscriber connection or consider dropping unused slots.

Standby Disconnected

This rule alerts when a standby has no active WAL receiver process.

A disconnected standby is in recovery mode but not receiving WAL from the primary. The standby will fall further behind until an administrator restarts the WAL receiver and replication resumes. Check the PostgreSQL log on the standby for connection errors and verify that the primary server is accessible.

Subscription Worker Down

This rule alerts when a subscription's apply worker is not running.

A subscription worker that is not running means logical replication has stopped for that subscription. This alert covers both native PostgreSQL logical replication and Spock subscriptions. Check the PostgreSQL log on the subscriber for errors and verify that the publisher is accessible. Use ALTER SUBSCRIPTION ... ENABLE to restart a disabled subscription.

Storage Rules

High Disk Usage

This rule alerts when disk usage exceeds the threshold.

High disk usage can lead to database failures. Add storage capacity or clean up unnecessary data.

Critical Disk Usage

This rule alerts when disk usage is critically high.

Critical disk usage requires immediate action to prevent database outages.

High Dead Tuple Percentage

This rule alerts when tables have accumulated too many dead tuples.

Dead tuples indicate vacuum is not keeping up with updates. Check vacuum settings and consider running manual vacuum. The alerter excludes tables with fewer than 1,000 total tuples from evaluation to reduce noise from small catalog and system tables.

High Table Bloat

This rule alerts when table bloat exceeds the threshold.

Table bloat reduces query performance and wastes storage. Consider running VACUUM FULL during a maintenance window.

Stale Autovacuum

This rule alerts when autovacuum has not processed a table recently.

Tables that vacuum has not processed recently may accumulate dead tuples or outdated statistics.

High Transaction ID Age

This rule alerts when transaction IDs are approaching wraparound.

Transaction ID wraparound prevention requires aggressive vacuuming. Monitor this metric carefully on busy databases.

Database Performance Rules

Low Cache Hit Ratio

This rule alerts when the buffer cache hit ratio falls below the threshold.

A low cache hit ratio indicates the database needs more memory for shared_buffers; the working set may also be too large. The alerter calculates the ratio from the change in block reads between collection intervals. This delta-based approach reflects recent performance rather than cumulative counters. The alerter excludes databases with fewer than 10,000 total block operations in an interval to avoid noise from idle databases.

Deadlocks Detected

This rule alerts when deadlocks occur.

Deadlocks indicate lock ordering problems in the application. Review the application logic to prevent deadlocks.

High Temporary File Usage

This rule alerts when temporary file creation exceeds the threshold.

PostgreSQL creates temporary files when work_mem is insufficient for sort and hash operations. Consider increasing work_mem.

System Resource Rules

High CPU Usage

This rule alerts when CPU usage exceeds the threshold.

High CPU usage may indicate inefficient queries, missing indexes, or insufficient hardware capacity.

High Memory Usage

This rule alerts when memory usage exceeds the threshold.

High memory usage can lead to swap usage and performance degradation. Review memory allocation settings.

High System Load

This rule alerts when the 15-minute load average exceeds the threshold.

High system load indicates that the current workload has overloaded the server. Investigate the source of the load and consider scaling resources.

Archive Rules

Archive Failures

This rule alerts when WAL archiving fails.

Archive failures can prevent point-in-time recovery. Check the archive command and destination storage.

Checkpoint Rules

Frequent Requested Checkpoints

This rule alerts when PostgreSQL requests too many checkpoints.

Frequent requested checkpoints indicate checkpoint_segments or max_wal_size may be too low for the workload.

Customizing Rules

Administrators can customize all built-in rules through per-connection overrides, which they configure through the admin panel. See the Monitoring Alerts documentation for details on the alert lifecycle and management.