# Design Records

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

---

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

---

Design records explain why PG Exporter works the way it does. Each article separates the decision, implementation, release, package, deployment, and production-verification gates so an accepted design is never mistaken for a shipped feature.

Use the [manuals](/docs/) for current product behavior and the [release archive](/release/) for shipped versions. Use this section for the reasoning, alternatives, invariants, and evidence behind those outcomes.

---

Section pages:

- [Turning PostgreSQL CSV Logs into Durable Metrics](/design/postgres-log-metrics/): The product boundary, durable-state protocol, bounded metric contract, and failure semantics for PostgreSQL CSV log metrics in PG Exporter
- [Caching pgBackRest Metrics Outside the Scrape Path](/design/cached-pgbackrest-metrics/): Why PG Exporter executes pgBackRest in a bounded background worker and serves an immutable last-good snapshot
- [The PostgreSQL Observability Product We Chose Not to Build](/design/observability-product-pivot/): Why a local-first PostgreSQL incident workbench was explored, then replaced by a much smaller CSV-log metrics feature inside PG Exporter
- [One Endpoint, Several Sources: The Composite Exporter Contract](/design/composite-exporter/): How PG Exporter combines PostgreSQL, PgBouncer, Patroni, and cached components without weakening the primary PostgreSQL scrape
- [Snapshot Histograms Are Gauges, Not Counters](/design/snapshot-histograms/): Why PG Exporter rebuilds SQL distributions on every query and exposes their buckets, count, and sum as gauge series