Alert Rule 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 threshold is exceeded.

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.

The rule divides the most recent session count by the newest recorded max_connections value. The settings probe only stores a snapshot when the configuration changes, so the newest snapshot may be days or weeks old on a stable server.

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.

The rule reads the newest stored pg_settings snapshot, which the collector writes only when the configuration changes.

Blocked Sessions

This rule alerts when sessions are waiting for locks held by other sessions.

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 should be investigated.

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 the WAL receiver is restarted 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 (Retired)

This rule is retired and disabled by default. The alerter no longer collects the table_bloat_ratio metric, so enabling the rule produces no alerts.

The rule duplicated the High Dead Tuple Percentage rule with a different denominator, so the two rules fired on the same tables at different thresholds. The rule definition remains in the datastore so that historical alerts stay attributable, and any alerts that were active at upgrade time are cleared. Use the High Dead Tuple Percentage rule to monitor table maintenance.

Stale Autovacuum

This rule alerts when a table has not been autovacuumed recently.

Tables that have not been vacuumed may have accumulated dead tuples or outdated statistics.

High Transaction ID Age

This rule alerts when transaction IDs are approaching wraparound.

The value is the transaction ID age of the oldest database on the server, expressed as a percentage of the 2147483647 wraparound limit. It comes from age(datfrozenxid) in pg_database, which the collector samples every 300 seconds.

Template databases count towards this metric, because wraparound is decided by the oldest transaction ID age in the cluster regardless of which database holds it. This matters in practice: template0 does not allow connections, so autovacuum only reaches it on the anti-wraparound path, which makes it the database most likely to age while every user database stays fresh.

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 have occurred in the last hour.

The value counts the deadlocks recorded for each database in the last hour, so the result does not depend on how often the collector samples pg_stat_database. A reset of the database statistics contributes no deadlocks. The hourly window does not change when this rule fires: with a threshold of 0, any deadlock at all raised an alert under the previous comparison too.

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

High Temporary File Usage

This rule alerts when the number of temporary files created in the last hour exceeds the threshold.

The value counts the temporary files created for each database in the last hour, so the result does not depend on how often the collector samples pg_stat_database. A reset of the database statistics contributes no files.

The hourly window makes this rule considerably more sensitive than it was. The rule previously compared the threshold against the change between two consecutive samples, and at the default sampling interval of 300 seconds twelve samples fall inside an hour. A database that steadily creates 300 temporary files an hour reported about 25 under the old comparison and reports 300 now, so the rule fires on databases where it did not fire before. To keep the previous sensitivity, multiply the threshold by 3600 divided by the sampling interval in seconds; at the default interval, that gives a threshold of 1200.

Temporary files are created 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.

The value is the busy percentage of the host CPU. The system_stats extension reports different columns on different platforms, so the rule uses processor_time_percent on Windows and derives the busy percentage from the idle and per-mode percentages on Linux.

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 the server is overloaded. Investigate the source of the load and consider scaling resources.

Archive Rules

Archive Failures

This rule alerts when WAL archiving fails.

The value counts the archive failures recorded in the last hour, read from the archiver columns of metrics.pg_stat_wal. A reset of the archiver statistics contributes no failures.

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

Checkpoint Rules

Frequent Requested Checkpoints

This rule alerts when checkpoints are requested too frequently.

The value counts the requested checkpoints recorded in the last hour, so the default threshold corresponds to an average of one requested checkpoint every five minutes. Timed checkpoints are not counted.

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

Customizing Rules

All built-in rules can be customized through per-connection overrides. Administrators configure overrides through the admin panel. See the Alerts documentation for details on the alert lifecycle and management.