Design Records
Design records explain PG Exporter’s architecture, alternatives, and tradeoffs. Each record states its status, source boundary, and last verification date.
Snapshot Histograms shipped in v1.4.0. Replication collector corrections and target state contracts shipped in v1.5.0. Composite mode, cached pgBackRest metrics, and PostgreSQL log metrics are implemented in the development branch and are not in stable v1.6.0. The separate observability-product proposal was superseded.
Use the manuals for stable-release procedures and the release archive for shipped changes.
Bounded SQL Scrapes and Client Cancellation
v1.6.0: bounded waiting for two scrapers, request cancellation, and the existing failure-cache policy.
Cluster Progress with Safe Relation Labels
v1.6.0: keep cluster-wide progress and use numeric OIDs for user relations in other databases.
Container Trust Roots and Release Checks
v1.6.0: include CA roots and the license in both scratch images, and exercise TLS and DEB artifacts in release validation.
Target Identity and Consistent Health Responses
v1.5.0 target-state guarantees, with the v1.6.0 amendment separating health probes from collection.
Correcting Replication Collector Identity and Semantics
Minimal corrections to subscription identity, receiver states, origin permissions, and relation counts
Turning PostgreSQL CSV Logs into Durable Metrics
Read complete CSV records, persist cursors and aggregates, and publish bounded PostgreSQL log metrics
Caching pgBackRest Metrics Outside the Scrape Path
Run pgBackRest in a bounded background worker and serve the latest valid metrics snapshot
The PostgreSQL Observability Product We Chose Not to Build
Why a separate incident workbench became a CSV log collector inside PG Exporter
One Endpoint, Several Sources: The Composite Exporter Contract
Combine PostgreSQL and optional metric sources with fixed ownership and independent failure handling
Snapshot Histograms Are Gauges, Not Counters
Why SQL snapshot distributions expose bucket, count, and sum as Gauge series
Bounded SQL Scrapes and Client Cancellation
v1.6.0: bounded waiting for two scrapers, request cancellation, and the existing failure-cache policy.
Cluster Progress with Safe Relation Labels
v1.6.0: keep cluster-wide progress and use numeric OIDs for user relations in other databases.
Container Trust Roots and Release Checks
v1.6.0: include CA roots and the license in both scratch images, and exercise TLS and DEB artifacts in release validation.
Target Identity and Consistent Health Responses
v1.5.0 target-state guarantees, with the v1.6.0 amendment separating health probes from collection.
Correcting Replication Collector Identity and Semantics
Minimal corrections to subscription identity, receiver states, origin permissions, and relation counts
Turning PostgreSQL CSV Logs into Durable Metrics
Read complete CSV records, persist cursors and aggregates, and publish bounded PostgreSQL log metrics
Caching pgBackRest Metrics Outside the Scrape Path
Run pgBackRest in a bounded background worker and serve the latest valid metrics snapshot
The PostgreSQL Observability Product We Chose Not to Build
Why a separate incident workbench became a CSV log collector inside PG Exporter
One Endpoint, Several Sources: The Composite Exporter Contract
Combine PostgreSQL and optional metric sources with fixed ownership and independent failure handling
Snapshot Histograms Are Gauges, Not Counters
Why SQL snapshot distributions expose bucket, count, and sum as Gauge series
-
Bounded SQL Scrapes and Client Cancellation
Status: Implemented in v1.6.0. Decision / last verification: 2026-11-09. Scope: v1.6.0 at source 6bee809 on main, addressing #116. Not shipped in v1.5.0. Delivery: Source committed and pushed as 6bee809; local validation and Test Release passed. …
Status: Implemented in v1.6.0. Decision / last verification: 2026-11-09. Scope: v1.6.0 at source 6bee809 on main, addressing #116. Not shipped in v1.5.0. Delivery: Source committed and pushed as 6bee809; local validation and Test Release passed. …
-
Cluster Progress with Safe Relation Labels
Status: Implemented in v1.6.0. Decision / last verification: 2026-11-09. Scope: v1.6.0 at source 6bee809 on main, #115; PostgreSQL 12+ vacuum, index creation, and cluster progress. Not shipped in v1.5.0. Delivery: Source committed and pushed as …
Status: Implemented in v1.6.0. Decision / last verification: 2026-11-09. Scope: v1.6.0 at source 6bee809 on main, #115; PostgreSQL 12+ vacuum, index creation, and cluster progress. Not shipped in v1.5.0. Delivery: Source committed and pushed as …
-
Container Trust Roots and Release Checks
Status: Implemented in v1.6.0. Decision date / last verification: 2026-11-08 / 2026-11-09. Scope: Container and release-validation changes based on v1.5.0 source 1891254, incorporating the packaging correction from 68c95ba. No exporter runtime or …
Status: Implemented in v1.6.0. Decision date / last verification: 2026-11-08 / 2026-11-09. Scope: Container and release-validation changes based on v1.5.0 source 1891254, incorporating the packaging correction from 68c95ba. No exporter runtime or …
-
Target Identity and Consistent Health Responses
Status: Original contract shipped in v1.5.0; the 2026-11-09 health amendment is implemented in v1.6.0. Decision / last verification: Original decision 2026-10-23; health amendment and local verification 2026-11-09. Scope: v1.5.0 at source 1891254 …
Status: Original contract shipped in v1.5.0; the 2026-11-09 health amendment is implemented in v1.6.0. Decision / last verification: Original decision 2026-10-23; health amendment and local verification 2026-11-09. Scope: v1.5.0 at source 1891254 …
-
Correcting Replication Collector Identity and Semantics
Status: Shipped in v1.5.0. Decision date / last verified: 2026-10-22 / 2026-10-23. Scope: Collector corrections in pg_exporter main commit d97ba38fc8390984df994b2f9ea58b43ecfc8b89, based on 72f00a4fa4e6eb7524174f2122b3fe1e1d608db4; PostgreSQL …
Status: Shipped in v1.5.0. Decision date / last verified: 2026-10-22 / 2026-10-23. Scope: Collector corrections in pg_exporter main commit d97ba38fc8390984df994b2f9ea58b43ecfc8b89, based on 72f00a4fa4e6eb7524174f2122b3fe1e1d608db4; PostgreSQL …
-
Turning PostgreSQL CSV Logs into Durable Metrics
PostgreSQL logs record events that SQL snapshots can miss: deadlocks, authentication failures, canceled autovacuum workers, checkpoints, temporary-file removals, and client disconnects. They can also report statement duration, according to the …
PostgreSQL logs record events that SQL snapshots can miss: deadlocks, authentication failures, canceled autovacuum workers, checkpoints, temporary-file removals, and client disconnects. They can also report statement duration, according to the …
-
Caching pgBackRest Metrics Outside the Scrape Path
pgbackrest info --output=json reports backup state. The command can contact remote repositories and wait for storage. Running it during a Prometheus request would add that delay to database monitoring. Status: Implemented but unreleased. Decision …
pgbackrest info --output=json reports backup state. The command can contact remote repositories and wait for storage. Running it during a Prometheus request would add that delay to database monitoring. Status: Implemented but unreleased. Decision …
-
The PostgreSQL Observability Product We Chose Not to Build
We first considered a local PostgreSQL incident workbench. It would read structured logs, reconstruct session timelines, provide interactive filters and a terminal interface, and later run as an agent. Status: Superseded on 2026-08-24 by PostgreSQL …
We first considered a local PostgreSQL incident workbench. It would read structured logs, reconstruct session timelines, provide interactive filters and a terminal interface, and later run as an agent. Status: Superseded on 2026-08-24 by PostgreSQL …
-
One Endpoint, Several Sources: The Composite Exporter Contract
Composite mode combines PostgreSQL, PgBouncer, Patroni, pgBackRest, and PostgreSQL log metrics in one /metrics endpoint. It reduces the number of processes and scrape targets for a database node. PostgreSQL remains the primary source; each optional …
Composite mode combines PostgreSQL, PgBouncer, Patroni, pgBackRest, and PostgreSQL log metrics in one /metrics endpoint. It reduces the number of processes and scrape targets for a database node. PostgreSQL remains the primary source; each optional …
-
Snapshot Histograms Are Gauges, Not Counters
A scalar metric cannot describe the distribution of a changing population. One 30-minute transaction and one hundred 18-second transactions have the same total age, but different counts, maxima, and operational effects. Status: Shipped in v1.4.0. …
A scalar metric cannot describe the distribution of a changing population. One 30-minute transaction and one hundred 18-second transactions have the same total age, but different counts, maxima, and operational effects. Status: Shipped in v1.4.0. …