Skip to main content
View rawEdit

PostgresAI monitoring

PostgresAI monitoring collects the state of your Postgres at short intervals and keeps the history: active sessions and wait events, query statistics, tables and indexes, autovacuum, replication, WAL, and I/O. People read it in Grafana dashboards and checkup reports. AI agents read the same data through the CLI.

The core components are open source (Apache 2.0): gitlab.com/postgres-ai/postgresai.

Install​

Choose one path. Each path needs pg_stat_statements and a monitoring role; see System requirements.

PathUse it whenGuide
Hosted by PostgresAIYou want PostgresAI to run the monitoring stackQuick start, Install from PostgresAI Console
SupabaseYour database is a Supabase projectQuick start for Supabase
Amazon RDS, not publicly accessibleThe monitoring must connect over AWS PrivateLinkQuick start for Amazon RDS over AWS PrivateLink
Your server, with the CLIYou have a Linux machine with DockerCLI installation
Your server, with Docker ComposeYou want to manage the containers yourselfDocker Compose installation
KubernetesYou deploy with HelmHelm installation
Your cloud accountYou provision in AWS, GCP, or AzureCloud installation

To try it without a database of your own, run the demo mode on a Linux machine with Docker:

npx pgai@latest mon local-install --demo

Grafana opens on http://localhost:3000.

For a hosted installation, open PostgresAI Console, go to Monitoring, and choose a plan. Grafana dashboards are part of the Scale plan and of every self-hosted installation; the Starter plan has checkup reports and issues, without Grafana. See pricing.

To upgrade an existing installation, see Upgrading the monitoring stack.

Architecture​

your Postgres ──► pgwatch ──► VictoriaMetrics ──► Grafana dashboards
(read-only (collector) (metrics (14 dashboards)
monitoring role) │ storage) ──► checkup reports, alerts
│
└──► Postgres sink (normalized query texts)
  • pgwatch runs read-only SQL against your database on a schedule and exposes the results as metrics.
  • VictoriaMetrics stores the metrics and answers PromQL queries.
  • A Postgres sink stores normalized query texts, so that dashboards can show the query behind a query ID.
  • Grafana shows the dashboards.
  • The reporter builds checkup reports from the stored metrics.

Most metrics are collected every 30 seconds, and session state and wait events are sampled every 15 seconds. Heavy estimates, such as table and index bloat, run every 2 hours.

More: Architecture, Multi-cluster monitoring, Self-monitoring.

What it collects​

AreaExamplesReference
Sessions and wait eventssessions by state, active session history with wait events per query ID, long transactions, lock waitsWait event metrics
Queriescalls, total and mean time, rows, buffers, WAL, per query IDpg_stat_statements metrics
Tablessize, scans, row changes, dead tuples, bloat estimatesTable metrics
Indexessize, usage, bloat estimates, unused, redundant, and invalid indexesIndex metrics
Database and clustertransactions, checkpoints, WAL, replication, xmin horizon, wraparound, settingsDatabase- and cluster-level metrics

Full list: Metrics reference.

Find the dashboard for your task​

TaskDashboard
Triage an incident; see the whole node on one page01. Single node performance overview
Find the queries that take the most time, I/O, or WAL02. Query performance analysis (top-N)
Study one query over time03. Single queryid analysis
See what active sessions wait for, and which queries wait04. Wait event analysis (Active Session History)
Check WAL generation, archiving lag, and WAL retained by slots05. WAL, backups, DR
Check replication lag and slots06. Replication
Check autovacuum, the xmin horizon, and wraparound risk07. Autovacuum and xmin horizon
Compare tables: size, activity, dead tuples, bloat08. Aggregated table analysis
Study one table09. Single table analysis
Find unused, redundant, invalid, or bloated indexes10. Aggregated index analysis
Study one index11. Single index analysis
Check SLRU caches, including multixact12. SLRU cache stats
Find who blocks whom13. Lock contention
Break down I/O by backend type14. I/O statistics (pg_stat_io)
Check the monitoring stack itselfSelf-monitoring

Overview of all dashboards: Dashboard overview.

Use it with an AI agent​

  • Agent skill. The postgresai skill deploys monitoring and reports the problems it finds, worst first. For Claude Code: claude plugin marketplace add postgres-ai/postgresai, then claude plugin install pgai@postgresai.
  • Metrics from a shell. npx pgai@latest promql '<expression>' runs a PromQL query on a monitoring instance and prints the result. See promql in the CLI reference.
  • Issues. The MCP server and the CLI give an agent the issues and action items from PostgresAI Console. See How to install MCP and How to work with issues.
  • Checkup reports. npx pgai@latest checkup --json <connection string> prints a health report as JSON. See checkup.

Data privacy: metadata only​

PostgresAI monitoring collects database metadata. It does not read table data. It does not collect query parameter values, with one exception that you can turn off.

What is collected​

  • Database statistics from system views (pg_stat_*)
  • Normalized query texts from pg_stat_statements, with parameter values replaced by $1, $2, and so on
  • Wait event information from pg_stat_activity
  • Table and index statistics: sizes, access patterns, bloat estimates

One exception, on by default: the health check includes the first 500 characters of the query that holds the xmin horizon, as written, so it can contain literal values. The setting postgresai.capture_query_preview=off disables it.

What is NOT collected​

  • Table data
  • Query parameter values, except in the query preview above
  • Connection credentials
  • Application data

Verify collected metrics​

Every metric is a SQL query in a public file. Read the definitions:

Verify database permissions​

The monitoring user has read-only access to metadata. To print the exact SQL that creates the monitoring role, without running it:

npx pgai@latest prepare-db --print-sql

The output shows every grant statement.

More: Monitoring security, Monitoring telemetry, Permission errors.

Supported Postgres versions​

PostgresAI full monitoring, express-mode checkups, and PostgresAI Console checkup analysis support PostgreSQL 14 through PostgreSQL 19.

It works with self-managed Postgres, Kubernetes deployments, and managed services such as Amazon RDS, Google Cloud SQL, Azure Database, Supabase, and TigerData.

PostgreSQL 19 is currently a pre-release (RC1). Use it for compatibility testing rather than production workloads until PostgreSQL 19 reaches general availability. PostgresAI preserves the pre-release version label in checkup reports, selects PostgreSQL 19-compatible metric SQL, and does not report a PostgreSQL 19 pre-release server as being behind the latest stable major release.

On PostgreSQL 19, the full monitoring collector uses the native pg_get_multixact_stats() function instead of scanning pg_multixact files. The monitoring role needs pg_read_all_stats privileges (included by pg_monitor) for the function to return values; otherwise the metric is reported as unavailable without interrupting other collection.

PostgresAI Console's separate PostgreSQL cluster-provisioning workflow depends on the PostgreSQL versions supported by its automation provider. Monitoring and checkup compatibility does not make a pre-release version available for provisioning automatically.

Configure​

Troubleshoot​

PostgresAI Console​

With a PostgresAI Console account, monitoring also gives you:

  • Checkup reports on a schedule, with findings and recommendations.
  • Issues and action plans, which you or your agent can work through.
  • Shared access for PostgresAI consulting. Consulting customers can give the PostgresAI team access to the same monitoring.

Both the express checkup and the full monitoring stack also work without a Console account.