pgAgroal Enterprise · Reference
Alerting rules
A catalogue of the Prometheus alerting rules shipped with the Enterprise observability pack. Every expression uses pgagroal's native Prometheus metrics — no extra exporter and no upstream pgagroal change — and is covered by the metric-drift guard. For each alert below: its name, severity, what it fires on in plain terms, and the suggested response.
observability/prometheus/pgagroal-alerts.yaml, packaged as a Prometheus Operator PrometheusRule. The inner groups are also a valid vanilla Prometheus rule file. To apply them, see the observability how-to.Availability
Group pgagroal.availability — the pool itself: is it saturated, are clients queueing, and are any backends down?
| Alert | Severity | Fires on | Suggested response |
|---|---|---|---|
PgagroalPoolSaturated | warning | Active connections exceed 90% of max_connections for 5 minutes. | Clients are about to start queueing. Add capacity or raise max_connections. |
PgagroalConnectionsQueued | warning | Connections have been on-hold awaiting a free backend for 10 minutes. | The pool is undersized for current demand — resize it or tune timeouts. |
PgagroalBackendDown | critical | One or more backend servers are marked failed for 5 minutes. | Check PostgreSQL availability and pgagroal server health. |
Errors
Group pgagroal.errors — connection failures, authentication failure spikes, and FATAL log output.
| Alert | Severity | Fires on | Suggested response |
|---|---|---|---|
PgagroalConnectionErrors | warning | Connection errors or timeouts are occurring for 5 minutes. | Investigate backend reachability and connection limits. |
PgagroalAuthFailureSpike | warning | Sustained authentication failures (bad password or auth error) at a rate above 0.2/s for 5 minutes. | Possible misconfiguration or credential-stuffing — verify credentials and review access. |
PgagroalLogFatal | critical | pgagroal emits FATAL log entries (any rate above zero over 5 minutes), held for 1 minute. | Inspect the instance immediately. |
TLS certificates
Group pgagroal.tls — certificate posture, so TLS does not lapse unnoticed.
| Alert | Severity | Fires on | Suggested response |
|---|---|---|---|
PgagroalCertificateExpired | critical | An expired TLS certificate is in use for 5 minutes. | TLS connections will fail — rotate the certificate immediately. |
PgagroalCertificateExpiringSoon | warning | A TLS certificate expires within 30 days, held for 1 hour. | Schedule a rotation before it lapses. |
Anatomy of a rule
Each rule is a standard Prometheus alerting rule with an expr, a for duration, a severity label, and summary/description annotations. As a representative example, PgagroalPoolSaturated compares active connections against the pool maximum per instance:
- alert: PgagroalPoolSaturated
expr: (sum by (instance) (pgagroal_active_connections) / clamp_min(sum by (instance) (pgagroal_max_connections), 1)) > 0.9
for: 5m
labels:
severity: warning
annotations:
summary: "pgagroal pool >90% saturated on {{ $labels.instance }}"
description: "Active connections have exceeded 90% of max_connections for 5m. Clients will start queueing — add capacity or raise max_connections."The clamp_min(..., 1) guards against a divide-by-zero when max_connections has not yet been scraped, and the sum by (instance) aggregation keeps every alert scoped per-instance so the firing label points at the affected pooler.
Related
- Set up observability — import the dashboards and apply these rules.
- pgagroal Prometheus manual — how the native metrics endpoint is enabled and what it exposes.