内置采集器

PG Exporter v1.5.0 在 config/ 中提供 58 个 YAML 文件（57 个采集器文件和 1 个配置参考文件），make conf 按文件名顺序将它们合并为默认的 pg_exporter.yml。

文件名前缀只负责排序，并不是指标名。一个文件可以为同一指标命名空间定义多个版本或角色分支。PG Exporter 在首次抓取时根据目标实例信息选择符合条件的分支；对真实目标访问 GET /explain，即可查看最终执行计划。

按指标名称跨版本分支去重，v1.5.0 定义了 59 个采集器命名空间、460 个指标名，其中包含默认禁用的采集器和 2 个 HISTOGRAM 定义，尚未展开直方图。一次抓取的实际序列数取决于选中的分支、结果行、标签和桶数。

升级 PostgreSQL 或替换采集器配置前，请核对指标兼容性与迁移对照表。其中区分 v1.5.0 的标签／状态修正、PG19 的新增指标与语义变化、较早 PostgreSQL 版本已移除的指标，并提供避免告警因时序缺失而静默的检查方法。

编号分区

完整清单

启用前先看计划

规划器根据目标类型、服务器版本、恢复角色、数据库、扩展、模式、用户名和标签筛选分支。谓词查询在之后刷新采集结果时执行。先完成一次抓取，再查看主连接的当前计划：

curl -fsS http://127.0.0.1:9630/metrics >/dev/null
curl -fsS http://127.0.0.1:9630/explain

/explain 返回选中的采集器的纯文本说明。用 --log.level=debug 查看分支被排除的原因。

pg_origin、pg_shmem、两个膨胀采集器、TimescaleDB 采集器和 pg_heartbeat 均设置了 skip: true。准备好所需权限和对象后，再改为 skip: false。心跳采集器只负责读取，心跳表由独立任务维护。

复制源权限

pg_origin 保持默认关闭。在采用标准目录 ACL 的 PostgreSQL 14+ 上，由管理员在 Exporter 的 主连接数据库 中执行以下授权，将 monitor 替换为实际监控角色：

GRANT SELECT ON pg_catalog.pg_replication_origin_status TO monitor;
GRANT EXECUTE ON FUNCTION
  pg_catalog.pg_show_replication_origin_status() TO monitor;

之后在实际加载的配置中显式将此采集器设为 skip: false，重载或重启 Exporter，并核对查询错误和预期的 origin 指标。只有 pg_monitor 成员身份并不足够。PostgreSQL 13 及更早版本还会在函数内部检查超级用户身份，上述授权无法让普通监控角色直接调用，应保持此可选采集器关闭。Exporter 不会自动授予权限。

发布与订阅计数

pg_pubrel_count 统计 pg_get_publication_tables() 返回的表条目，即使在 PG19 上也不包含序列。空发布和仅包含序列的发布 不会产生时序，而不是显式输出零。

pg_subrel_count 按订阅和同步状态汇总 pg_subscription_rel 中的条目。PG19 上包含表和序列。表状态为 i（初始化）、d（复制数据）、f（表数据复制完成）、s（已同步）和 r（就绪）；PG19 序列使用 i 或 r。

不能用发布端与订阅端数量相等来判断复制健康：两者统计的集合不同，发布重叠、分区处理、刷新与同步进度也会影响数量。

订阅身份与接收器状态

v1.5.0 配置修正了订阅身份与接收器状态。替换旧采集器配置时，请核对以下升级要求：

• 全部 pg_sub_* 样本增加表示订阅归属数据库的 datname 标签，与 subname 一起区分跨库同名订阅。保留原有 pg_sub_id gauge。新增标签会产生新时序，部署前应检查依赖标签匹配的 PromQL 连接与聚合。
• PG10–13 部署新配置前，管理员须在每个用作 Exporter 主连接数据库 的库内执行 GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor;。仅在订阅所在数据库授权并不足够。该授权不会开放 subconninfo。PG14+ 在标准目录 ACL 下不需要额外授权。缺少此前提时，订阅查询会失败且指标缺失；HTTP 200 不能单独证明抓取成功。
• 当前与 legacy 配置的 pg_recv_state 均使用下表。编码 1–3 保留；PG9.6–18 不存在 connecting 状态。没有 receiver 行时仍不输出样本，不填零，也不伪造 stopped 状态。
• Legacy receiver 查询使用 PG9.6 兼容的标量 substring() 提取 host 和 port。PG9.6 仍会对非超级用户隐藏 receiver 详情：只有 PID 可见，采集器输出状态 -1。这项 SQL 修正不改变数据库权限。

基数与开销

每对象和每查询采集器是主要的基数来源。在大规模环境中启用前重点检查：

• pg_table、pg_index、pg_func、pg_seq 会为每个对象产生一组或多组时序。
• pg_query 从 pg_stat_statements 中按调用次数选择最多 128 组语句。查询 ID 会随时间变化。
• pg_table_size、pg_table_bloat、pg_index_bloat 在关系很多时可能成本较高。
• 等待事件采样依赖扩展，并可能产生随负载变化的维度。

用 ttl 控制高开销 SQL 的执行频率，按实测耗时设置 timeout。抓取超时需要容纳所有采集器和自动发现数据库的完整采集过程。变更前后比较 pg_exporter_scrape_duration 和时序数量。

定制采集器

先复制完整的配置目录，再将本地定义放入排序靠后的文件，如 9990-local.yml。覆盖已有分支时，使用相同的顶层键并提供完整定义；目录加载会替换整个分支。新分支使用唯一键，同一指标族的版本范围应互不重叠。

显式选择该目录并验证：

pg_exporter --config=/path/to/collectors --dry-run
# 在一个终端中运行服务
PG_EXPORTER_CONFIG=/path/to/collectors pg_exporter

# 在另一个终端中先抓取，再查看计划
curl -fsS http://127.0.0.1:9630/metrics >/dev/null
curl -fsS http://127.0.0.1:9630/explain

采集器模式、查询到指标的映射、标签、谓词、缓存、超时与直方图规则详见采集器配置。