# Design Records

> Architecture decisions, rejected alternatives, and implementation contracts for PG Exporter

---

LLMS index: [llms.txt](/llms.txt)

---

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](/design/replication-collector-contracts/) and [target state contracts](/design/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](/docs/) for stable-release procedures and the [release archive](/release/) for shipped changes.

---

Section pages:

- [Cluster Progress with Safe Relation Labels](/design/progress-database-scope/)
- [Bounded SQL Scrapes and Client Cancellation](/design/scrape-lifetime/)
- [Container Trust Roots and Release Checks](/design/container-trust/)
- [Target Identity and Consistent Health Responses](/design/target-state-contracts/)
- [Correcting Replication Collector Identity and Semantics](/design/replication-collector-contracts/): Minimal corrections to subscription identity, receiver states, origin permissions, and relation counts
- [Turning PostgreSQL CSV Logs into Durable Metrics](/design/postgres-log-metrics/): Read complete CSV records, persist cursors and aggregates, and publish bounded PostgreSQL log metrics
- [Caching pgBackRest Metrics Outside the Scrape Path](/design/cached-pgbackrest-metrics/): Run pgBackRest in a bounded background worker and serve the latest valid metrics snapshot
- [The PostgreSQL Observability Product We Chose Not to Build](/design/observability-product-pivot/): Why a separate incident workbench became a CSV log collector inside PG Exporter
- [One Endpoint, Several Sources: The Composite Exporter Contract](/design/composite-exporter/): Combine PostgreSQL and optional metric sources with fixed ownership and independent failure handling
- [Snapshot Histograms Are Gauges, Not Counters](/design/snapshot-histograms/): Why SQL snapshot distributions expose bucket, count, and sum as Gauge series