跳转到主要内容

设计归档

设计记录解释 PG Exporter 的架构、备选方案与取舍。每篇注明状态、源码边界和最后核验日期。

快照直方图已随 v1.4.0 发布。复制采集器修正与目标状态约定已随 v1.5.0 发布。Composite 模式、缓存 pgBackRest 指标和 PostgreSQL 日志指标已在开发分支实现，尚未进入稳定版 v1.6.0。独立可观测性产品提案已被取代。

稳定版操作方法见使用手册，已发布变更见发布归档。

保留集群进度与准确的关系标识 DesignPostgreSQLCompatibility
SQL 采集的总时限与客户端取消 DesignReliability
容器信任根与发布检查 DesignSecurityCompatibility
目标身份与一致的健康检查响应 DesignPostgreSQLReliability
复制采集器的身份、状态与权限修正 DesignPostgreSQLCompatibilityPrometheus
把 PostgreSQL CSV 日志转成持久指标 设计PostgreSQL日志Prometheus可靠性
把 pgBackRest 指标移出抓取路径 设计pgBackRestPrometheus可靠性
我们最终没有做的 PostgreSQL 可观测性产品 设计产品PostgreSQL可观测性
一个端点，多种来源：Composite Exporter 契约 设计架构PrometheusPgBouncerPatroni
快照直方图是 Gauge，不是 Counter 设计HistogramPrometheusPostgreSQL

  • 保留集群进度与准确的关系标识

    冯若航 发布于 设计 1141 字 3 分钟

    冯若航designDesignPostgreSQLCompatibility

    保留集群进度与准确的关系标识

    状态： 已实现，纳入 v1.6.0。 决策／最后核验： 2026-11-09。 范围： main 上的 v1.6.0，源码 6bee809，解决 #115，涵盖 PostgreSQL 12+ 的 vacuum、建索引与 cluster 进度，未随 v1.5.0 发布。 交付： 源码已提交并推送为 6bee809，本地验证与 Test Release 通过。带版本号的压缩包、RPM／DEB 与校验和已为草稿构建；公开标签、镜像发布、部署与生产验证仍是独立关卡。 决策 进度视图报告整个实例的任务， …

    状态： 已实现，纳入 v1.6.0。 决策／最后核验： 2026-11-09。 范围： main 上的 v1.6.0，源码 6bee809，解决 #115，涵盖 PostgreSQL 12+ 的 vacuum、建索引与 cluster 进度，未随 v1.5.0 发布。 交付： 源码已提交并推送为 6bee809，本地验证与 Test Release 通过。带版本号的压缩包、RPM／DEB 与校验和已为草稿构建；公开标签、镜像发布、部署与生产验证仍是独立关卡。 决策 进度视图报告整个实例的任务， …

  • SQL 采集的总时限与客户端取消

    冯若航 发布于 设计 2415 字 5 分钟

    冯若航designDesignReliability

    SQL 采集的总时限与客户端取消

    状态： 已实现，纳入 v1.6.0。 决策／最后核验： 2026-11-09。 范围： main 上的 v1.6.0，源码 6bee809，解决 #116，未随 v1.5.0 发布。 交付： 源码已提交并推送为 6bee809，本地验证与 Test Release 通过。带版本号的压缩包、RPM／DEB 与校验和已为草稿构建；公开标签、镜像发布、部署与生产验证仍是独立关卡。 决策 此前查询从 context.Background() 派生 context，指标客户端断开后工作仍可能继续，后续 …

    状态： 已实现，纳入 v1.6.0。 决策／最后核验： 2026-11-09。 范围： main 上的 v1.6.0，源码 6bee809，解决 #116，未随 v1.5.0 发布。 交付： 源码已提交并推送为 6bee809，本地验证与 Test Release 通过。带版本号的压缩包、RPM／DEB 与校验和已为草稿构建；公开标签、镜像发布、部署与生产验证仍是独立关卡。 决策 此前查询从 context.Background() 派生 context，指标客户端断开后工作仍可能继续，后续 …

  • 容器信任根与发布检查

    冯若航 发布于 设计 1242 字 3 分钟

    冯若航designDesignSecurityCompatibility

    容器信任根与发布检查

    状态： 已实现，纳入 v1.6.0。 决策日期／最后核验： 2026-11-08／2026-11-09。 范围： 基于 v1.5.0 源码 1891254 的容器与发布验证改动，吸收 68c95ba 的打包修正。不修改 exporter 运行时代码或数据库驱动。 交付： 源码 370b9fa 已纳入 v1.6.0 的 6bee809 并推送。两条 Docker 构建路径、amd64／arm64 GoReleaser 镜像、三个 DEB 架构、Go 测试、静态检查和文档构建均已验证。CI 与草稿 …

    状态： 已实现，纳入 v1.6.0。 决策日期／最后核验： 2026-11-08／2026-11-09。 范围： 基于 v1.5.0 源码 1891254 的容器与发布验证改动，吸收 68c95ba 的打包修正。不修改 exporter 运行时代码或数据库驱动。 交付： 源码 370b9fa 已纳入 v1.6.0 的 6bee809 并推送。两条 Docker 构建路径、amd64／arm64 GoReleaser 镜像、三个 DEB 架构、Go 测试、静态检查和文档构建均已验证。CI 与草稿 …

  • 目标身份与一致的健康检查响应

    冯若航 发布于 设计 2726 字 6 分钟

    冯若航designDesignPostgreSQLReliability

    目标身份与一致的健康检查响应

    状态： 原始契约已随 v1.5.0 发布；2026-11-09 健康修订已纳入 v1.6.0。 决策／最后核验日期： 原始决策为 2026-10-23；健康修订与本地验证为 2026-11-09。 范围： v1.5.0，源码 1891254（修复基线 9b378cb），涵盖连接串与数据库身份、由元数据驱动的采集器选择、HTTP 健康状态快照、YAML 时间配置及指标路由校验。 交付： 源码已提交并推送，v1.5.0 标签指向 …

    状态： 原始契约已随 v1.5.0 发布；2026-11-09 健康修订已纳入 v1.6.0。 决策／最后核验日期： 原始决策为 2026-10-23；健康修订与本地验证为 2026-11-09。 范围： v1.5.0，源码 1891254（修复基线 9b378cb），涵盖连接串与数据库身份、由元数据驱动的采集器选择、HTTP 健康状态快照、YAML 时间配置及指标路由校验。 交付： 源码已提交并推送，v1.5.0 标签指向 …

  • 复制采集器的身份、状态与权限修正

    冯若航 发布于 设计 3292 字 7 分钟

    冯若航designDesignPostgreSQLCompatibilityPrometheus

    复制采集器的身份、状态与权限修正

    状态： 已随 v1.5.0 发布。 决策日期 / 最近核验： 2026-10-22 / 2026-10-23。 范围： pg_exporter main 提交 d97ba38fc8390984df994b2f9ea58b43ecfc8b89 中的 Collector 修正，基于 72f00a4fa4e6eb7524174f2122b3fe1e1d608db4；PostgreSQL REL_19_RC1 对应 0b8bff042a997fe50fcd1c4c83b9ef1cc9ed8a89，另作 …

    状态： 已随 v1.5.0 发布。 决策日期 / 最近核验： 2026-10-22 / 2026-10-23。 范围： pg_exporter main 提交 d97ba38fc8390984df994b2f9ea58b43ecfc8b89 中的 Collector 修正，基于 72f00a4fa4e6eb7524174f2122b3fe1e1d608db4；PostgreSQL REL_19_RC1 对应 0b8bff042a997fe50fcd1c4c83b9ef1cc9ed8a89，另作 …

  • 把 PostgreSQL CSV 日志转成持久指标

    冯若航 发布于 设计 2652 字 6 分钟

    冯若航design设计PostgreSQL日志Prometheus可靠性

    把 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 指标移出抓取路径

    冯若航 发布于 设计 1410 字 3 分钟

    冯若航design设计pgBackRestPrometheus可靠性

    把 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 可观测性产品

    冯若航 发布于 设计 1113 字 3 分钟

    冯若航design设计产品PostgreSQL可观测性

    我们最终没有做的 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 契约

    冯若航 发布于 设计 1704 字 4 分钟

    冯若航design设计架构PrometheusPgBouncerPatroni

    一个端点，多种来源：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

    冯若航 发布于 设计 1379 字 3 分钟

    冯若航design设计HistogramPrometheusPostgreSQL

    快照直方图是 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 …

最后修改 2026-11-09