设计归档
设计记录解释 PG Exporter 的架构、备选方案与取舍。每篇注明状态、源码边界和最后核验日期。
快照直方图已随 v1.4.0 发布。Composite 模式、缓存 pgBackRest 指标和 PostgreSQL 日志指标已在开发分支实现，尚未进入稳定版 v1.4.1。独立可观测性产品提案已被取代。
把 PostgreSQL CSV 日志转成持久指标
读取完整 CSV 记录，持久化游标与聚合值，发布有界 PostgreSQL 日志指标
把 pgBackRest 指标移出抓取路径
在有界后台任务中执行 pgBackRest，并提供最后一份有效指标快照
我们最终没有做的 PostgreSQL 可观测性产品
为什么独立事故工作台最终变为 PG Exporter 内的 CSV 日志采集器
一个端点，多种来源：Composite Exporter 契约
通过固定所有权和独立故障处理，合并 PostgreSQL 与可选来源的指标
快照直方图是 Gauge，不是 Counter
为什么 SQL 快照分布将桶、计数与总和输出为 Gauge 序列
-
把 PostgreSQL CSV 日志转成持久指标
PostgreSQL 日志会记录 SQL 快照可能错过的事件：死锁、认证失败、自动清理取消、检查点、临时文件删除和客户端断连。根据服务端日志策略，还可以记录语句耗时。 状态： 已实现，未发布。 决策日期： 2026-08-24。 最后核验： 2026-10-13。 范围： 源码提交 c0ba58a 的 PostgreSQL 14+ CSV 日志采集器，默认关闭；稳定版 v1.4.1 尚未包含。 取代： 独立可观测性产品提案。 交付进度： 本地测试通过；未合入 main 或发布标签；软件包、部署与 …
PostgreSQL 日志会记录 SQL 快照可能错过的事件：死锁、认证失败、自动清理取消、检查点、临时文件删除和客户端断连。根据服务端日志策略，还可以记录语句耗时。 状态： 已实现，未发布。 决策日期： 2026-08-24。 最后核验： 2026-10-13。 范围： 源码提交 c0ba58a 的 PostgreSQL 14+ CSV 日志采集器，默认关闭；稳定版 v1.4.1 尚未包含。 取代： 独立可观测性产品提案。 交付进度： 本地测试通过；未合入 main 或发布标签；软件包、部署与 …
-
把 pgBackRest 指标移出抓取路径
pgbackrest info --output=json 提供备份状态。命令可能访问远程仓库并等待存储响应。若在 Prometheus 请求中执行，数据库监控也要承担这段延迟。 状态： 已实现，未发布。 决策日期： 2026-08-23。 最后核验： 2026-10-13。 范围： 源码提交 c0ba58a 的可选 --pgbackrest 组件；稳定版 v1.4.1 尚未包含。 交付进度： 本地测试通过；未合入 main 或发布标签；软件包、部署与生产运行未核验。 因此，PG …
pgbackrest info --output=json 提供备份状态。命令可能访问远程仓库并等待存储响应。若在 Prometheus 请求中执行，数据库监控也要承担这段延迟。 状态： 已实现，未发布。 决策日期： 2026-08-23。 最后核验： 2026-10-13。 范围： 源码提交 c0ba58a 的可选 --pgbackrest 组件；稳定版 v1.4.1 尚未包含。 交付进度： 本地测试通过；未合入 main 或发布标签；软件包、部署与生产运行未核验。 因此，PG …
-
我们最终没有做的 PostgreSQL 可观测性产品
我们最初考虑做一个本地 PostgreSQL 事故工作台：读取结构化日志，重建会话时间线，提供交互过滤与终端界面，后续再作为 Agent 运行。 状态： 已于 2026-08-24 被 PostgreSQL 日志指标方案取代。 决策日期： 2026-08-13 开始研究；2026-08-24 调整范围。 最后核验： 2026-10-13。 范围： 独立 PostgreSQL 事故工作台与 Agent 提案。 交付进度： 止于提案，未实现、发布或部署。 眼前需求更小：从 PostgreSQL 日志 …
我们最初考虑做一个本地 PostgreSQL 事故工作台：读取结构化日志，重建会话时间线，提供交互过滤与终端界面，后续再作为 Agent 运行。 状态： 已于 2026-08-24 被 PostgreSQL 日志指标方案取代。 决策日期： 2026-08-13 开始研究；2026-08-24 调整范围。 最后核验： 2026-10-13。 范围： 独立 PostgreSQL 事故工作台与 Agent 提案。 交付进度： 止于提案，未实现、发布或部署。 眼前需求更小：从 PostgreSQL 日志 …
-
一个端点，多种来源：Composite Exporter 契约
Composite 模式把 PostgreSQL、PgBouncer、Patroni、pgBackRest 和 PostgreSQL 日志指标合并到同一个 /metrics 端点，减少数据库节点上的进程和抓取目标。PostgreSQL 是主数据源；各可选来源独立报告故障和健康状态。 状态： 已实现，未发布。 决策日期： 2026-08-11；2026-08-23 与 2026-08-24 增加缓存组件。 最后核验： 2026-10-13。 范围： 源码提交 c0ba58a 的 Composite …
Composite 模式把 PostgreSQL、PgBouncer、Patroni、pgBackRest 和 PostgreSQL 日志指标合并到同一个 /metrics 端点，减少数据库节点上的进程和抓取目标。PostgreSQL 是主数据源；各可选来源独立报告故障和健康状态。 状态： 已实现，未发布。 决策日期： 2026-08-11；2026-08-23 与 2026-08-24 增加缓存组件。 最后核验： 2026-10-13。 范围： 源码提交 c0ba58a 的 Composite …
-
快照直方图是 Gauge，不是 Counter
一个标量指标无法描述变化中的总体分布。一个 30 分钟事务与一百个 18 秒事务的总年龄相同，但数量、最大年龄和运维影响不同。 状态： 已随 v1.4.0 发布。 决策日期： 2026-07-11；2026-07-17 修订。 最后核验： 2026-10-13。 范围： 稳定版 v1.4.1 的 HISTOGRAM 列与 pg_xact_age 采集器，并对照开发提交 c0ba58a 核验。 交付进度： 已实现、合并、打标签并发布软件包。针对性本地测试已通过；部署与生产运行未核验。 PG …
一个标量指标无法描述变化中的总体分布。一个 30 分钟事务与一百个 18 秒事务的总年龄相同，但数量、最大年龄和运维影响不同。 状态： 已随 v1.4.0 发布。 决策日期： 2026-07-11；2026-07-17 修订。 最后核验： 2026-10-13。 范围： 稳定版 v1.4.1 的 HISTOGRAM 列与 pg_xact_age 采集器，并对照开发提交 c0ba58a 核验。 交付进度： 已实现、合并、打标签并发布软件包。针对性本地测试已通过；部署与生产运行未核验。 PG …