Prerequisites
- PostgreSQL 10+ (12+ recommended for full
pg_stat_statementssupport) - Network access from the HealOps environment to your PostgreSQL instance
- A read-only user with access to system views
Setup
Option 1: Interactive CLI
Option 2: Environment variables
Add to your.env:
Option 3: Persistent store
Integrations are automatically persisted to~/.config/healops/integrations.json:
Creating a read-only user
pg_monitor (available in PostgreSQL 10+) grants read access to all monitoring views including pg_stat_activity, pg_stat_replication, and pg_stat_statements without superuser privileges.Enabling slow query tracking
Slow query analysis requires thepg_stat_statements extension. Add to postgresql.conf:
Investigation tools
When HealOps investigates a PostgreSQL-related alert, five diagnostic tools are available:Server status
Retrieves version, uptime, connection counts (total, active, idle, max), transaction commit/rollback rates, and buffer cache hit ratio per database. Useful for spotting connection saturation or cache efficiency drops.Current queries
Lists active queries running longer than a configurable threshold (default 1 s), excluding the monitoring connection itself. Includes PID, user, client address, duration, wait event, and a truncated query string.Replication status
Usespg_is_in_recovery() to reliably detect replica vs primary. On a primary, reports WAL position and per-replica lag (write, flush, replay). Returns a note if the server is a replica or if no replicas are connected.
Slow queries
Readspg_stat_statements to surface queries with the highest mean execution time. Results include call count, total/mean/min/max execution time (in ms with sub-millisecond precision), rows returned, and buffer cache hit percentage.
Slow query data requires the
pg_stat_statements extension to be installed and loaded via shared_preload_libraries. HealOps returns an informative message if the extension is not available.Table statistics
Readspg_stat_user_tables and pg_class for a given schema (default public). Returns insert/update/delete/live/dead tuple counts, sequential vs index scan ratios, last vacuum/analyze timestamps, and table sizes in bytes and MB.
Verify
Troubleshooting
Security best practices
- Use a dedicated read-only user with
pg_monitor— avoid superuser credentials for monitoring. - Enable SSL (
POSTGRESQL_SSL_MODE=require) in production environments. - Use
scram-sha-256authentication inpg_hba.confrather thanmd5. - Store credentials in
.env, never in source code. - Rotate credentials periodically.
Tracer