Troubleshooting

Fast Triage Checklist

Follow these actionable diagnostics to fix container startup issues, pgBouncer connectivity, missing metrics, and alert delivery in pgSentinel.

• Ensure pgSentinel containers are running (docker compose ps or kubectl get pods)
• Confirm the admin API responds: curl http://pgsentinel:8080/api/v1/health should return { "status": "healthy" }
• Verify pgBouncer admin credentials with psql "postgres://admin:secret@pgbouncer:6432/pgbouncer" -c "SHOW STATS"
• Check that Prometheus can scrape /metrics when PGSENTINEL_PROMETHEUS_EXPORT is true

Collect diagnostics in staging before applying production fixes whenever possible. Roll back temporary settings after validation.

Containers Fail to Start

Most startup errors trace back to missing DSNs or conflicting ports.

Gather diagnostics

docker compose ps
docker compose logs pgsentinel | tail -n 50
lsof -i :8080

Common fixes

• Verify PGSENTINEL_PGBOUNCER_DSN and PGSENTINEL_STORAGE_DSN point to reachable services.
• Ensure secrets mounted via Docker/Kubernetes have correct permissions.
• Free port 8080 (or remap) if a reverse proxy is already listening.

Missing Metrics or Empty Dashboards

Confirm polling succeeds and retention is configured correctly.

Check last sample age

SELECT now() - max(observed_at) AS last_sample_age
  FROM pgsentinel.samples;

Remediation tips

• Confirm pgBouncer admin credentials and IP allowlists.
• Increase max_client_conn on pgBouncer if the admin console rejects pgSentinel.
• Set PGSENTINEL_METRICS_RETENTION_DAYS to a positive value (default 30 days).

Alerts Not Firing

Webhooks only trigger when alert evaluation runs successfully and thresholds are crossed.

Send test notification

curl -X POST https://pgsentinel.example.com/api/v1/alerts/test \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id":"slack-primary"}'

Alert checklist

• Set PGSENTINEL_ALERT_INTERVAL (default 30s) to enable evaluations.
• Review pgsentinel.alert_events for muted or suppressed alerts.
• Inspect webhook responses in docker compose logs pgsentinel; pgSentinel stops retrying after five failures.

Support Bundle

Collect logs and metrics snapshots before opening a support ticket.

Generate support bundle

#!/usr/bin/env bash
DEST=/tmp/pgsentinel-support-$(date +%s)
mkdir -p "$DEST"

docker compose ps > "$DEST/compose_ps.txt"
docker compose logs pgsentinel > "$DEST/pgsentinel.log"

curl -s http://localhost:8080/api/v1/health > "$DEST/health.json"
curl -s http://localhost:8080/api/v1/status > "$DEST/status.json"

pg_dump --schema=pgsentinel --format=custom pgsentinel > "$DEST/metrics.dump"

tar -C /tmp -czf pgsentinel-support.tar.gz "$(basename "$DEST")"

Share with pgElephant support

Upload pgsentinel-support.tar.gz together with Docker version, PostgreSQL version, and relevant pgBouncer configuration snippets.