pg_diag collects PostgreSQL catalog statistics and Linux host metrics, then packs them into a portable artifact: a machine-readable report.json, a human-friendly report.html, and a report.log of the run itself. All SQL is read-only, and it works against PostgreSQL 10–18. This guide takes you from zero to a finished report.

1. Install

You need Python 3.10 or newer. Install from PyPI:

python -m pip install pg-diag

2. Give it a read-only user

Create a dedicated role and grant it the built-in pg_monitor role. It is the recommended least-privilege baseline for activity and statistics visibility: 

CREATE ROLE diag LOGIN PASSWORD 'strong-password';
GRANT pg_monitor TO diag;

A passwordless option is a ~/.pgpass entry—pg_diag supports --passfile and the PGPASSFILE environment variable.

3. Run a one-shot collection

pg-diag one-shot \
  --dsn "postgresql://diag@127.0.0.1:5432/appdb" \
  --collection-mode remote-db-only \
  --out reports/appdb_one_shot

The remote-db-only mode collects only database statistics—no OS access required. When you also want host metrics (CPU, memory, disk, network), run pg_diag on the database host itself or point it at the host over SSH.

4. Read the report

A successful run writes three files into --out:

reports/appdb_one_shot/report.json
reports/appdb_one_shot/report.html
reports/appdb_one_shot/report.log

Open report.html in a browser—it is self-contained and works offline. Keep report.json for automation: it is schema-versioned and records the content-pack checksum. Review diagnostic data before sharing it with another system or an LLM.

Narrowing the scope

Once the full report works, trim it to what you need. This collects only selected sections and emits pure JSON: 

pg-diag one-shot \
  --dsn "postgresql://diag@127.0.0.1:5432/appdb" \
  --collection-mode remote-db-only \
  --tags='[Configuration,Security,Locks,Replication]' \
  --output-format=json \
  --strip-meta \
  --out reports/appdb_scoped

For time-series charts instead of a single snapshot, look at the pg-diag snapshots mode in the project README.