postgres_exporter 0.20.1 介绍与选型指南

目标：说清 postgres_exporter 是什么、截至查询日官方最新稳定版本是哪个、核心架构与指标采集机制怎样，以及在什么场景该选它、什么场景应转向同类方案（pgexporter、pgMonitor）。本文为认知篇（A1）：不做本地安装实测，全部版本号、特性与量化数据均来自官方来源联网查证，关键论断随文标注来源与查询日期（2026-10-28）；安装、配置与命令的逐条实测见本专栏部署/配置/命令三篇。

一、信息基准

1.1 查询与版本基准

• 查询日期：2026-10-28。
• 基准版本：postgres_exporter v0.20.1。依据：GitHub releases/latest 实查 tag_name: v0.20.1、published_at: 2026-07-08T02:06:53Z，发布标题为 "0.20.1 / 2026-07-07"；Release 说明仅一条修复项：[BUGFIX] stat_replication: fix "slot_name does not exist" by joining pg_replication_slots（PR #1313）。
• 本地二进制自证：官方 linux-amd64 发行包解压后执行 postgres_exporter --version，回显 version 0.20.1 (branch: HEAD, revision: 867fbcac31cd18c143e244190ea9168cca069827)，go version: go1.26.4，build date: 20260708-01:46:52（本地实测，详见本专栏 B1/D1 两篇）。
• 规范名定夺：GitHub 组织为 prometheus-community、仓库为 postgres_exporter，全小写、单词间带下划线。检索时常见的 postgres-exporter（连字符写法）仅出现在发行包资产文件名与 Grafana 面板命名等场景，本文正文统一使用规范拼写 postgres_exporter。
• 警示：本组件与 2026 年活跃开发的 C 语言项目 pgexporter（pgexporter/pgexporter 仓）是完全不同的两个项目，名字仅一词之差。选型时务必先确认仓库名，避免混淆；两者对比见第五节。

1.2 官方来源清单

💡 GitHub API 对匿名请求限流严格，本文星数同时以 shields.io JSON 徽章接口取证（2026-10-28 实查），数据与仓库页一致。

二、软件概述

2.1 postgres_exporter 是什么

postgres_exporter 是 prometheus-community 维护的 PostgreSQL Prometheus 指标导出器，仓库描述一句话：A PostgreSQL metric exporter for Prometheus。它以一个数据库账号连入 PostgreSQL 实例，周期性执行针对 pg_stat_*、pg_statio_* 等统计视图的内置查询，把结果加工为 Prometheus 文本格式的 /metrics 指标流，供 Prometheus、VictoriaMetrics 等时序库抓取，再经 Grafana 等面板可视化与告警。

形态上，postgres_exporter 是一个 Go 语言实现的静态单二进制常驻进程：官方 Release 为每个平台发布一个 tar.gz（内含二进制、LICENSE、NOTICE 三个文件，无任何运行时依赖），以 systemd 服务方式长期运行，监听 HTTP 端口（默认 :9187）等待抓取。README 声明的 CI 测试 PostgreSQL 版本覆盖 13、14、15、16、17、18（来源：v0.20.1 README，查询日期 2026-10-28），本文实测则运行于 PostgreSQL 16.15 之上（详见 B1）。

它同时具备三类能力，构成完整的采集面：

💡 技术拓展：多目标（multi-target）模式是 Prometheus 官方倡导的 exporter 形态——exporter 不长期持有目标连接，而是由 Prometheus 抓取 /probe 端点时通过 ?target= 参数指明要探测的实例。适合 SaaS 托管库、无法在每个实例旁落 exporter 的场景；常规自建库仍建议一实例一 exporter（来源：Prometheus 官方指南 "multi-target exporter pattern" 链接于 v0.20.1 README）。

2.2 版本格局与发布节奏

近年 Release 时间线（GitHub Releases 实查，查询日期 2026-10-28）：

v0.20.0 破坏性变更要点（Release 原文实查，2026-10-28）：这是近两年最重要的版本，升级评估必读——

1. collector 更名：replication_slot → replication_slots，旗标 --collector.replication_slot/--no-collector.replication_slot 相应失效。
2. 旗标与变量删除：--disable-settings-metrics 与 PG_EXPORTER_DISABLE_SETTINGS_METRICS 被移除，改用 --no-collector.settings。
3. 指标更名：复制槽指标前缀 pg_replication_slot_ → pg_replication_slots_（如 pg_replication_slot_safe_wal_size_bytes → pg_replication_slots_safe_wal_size_bytes），告警规则与看板需同步。
4. 五类指标转正为独立 collector：settings、stat_activity、stat_archiver、stat_replication、replication_slots 不再出自旧默认指标映射，不再受 --metric-prefix 影响、不再携带 constantLabels、也不再被 --disable-default-metrics 关闭——要停采只能显式 --no-collector.<name>。本文 C1 对其中的失效项做了逐条实测验证（结论：PG_EXPORTER_DISABLE_DEFAULT_METRICS=true 与 PG_EXPORTER_METRIC_PREFIX 在 0.20.1 默认指标上已实际无效）。

三、架构与工作原理

3.1 采集链路

postgres_exporter 的工作方式可以概括为「拉」而非「推」：

Prometheus（抓取周期）
   │  GET /metrics
   ▼
postgres_exporter（HTTP 端口 :9187，或自定义）
   │  ① 读取 DATA_SOURCE_NAME / 拆分型环境变量建立连接池（lib/pq 驱动）
   │  ② 逐个执行已启用 collector 的内置 SQL（pg_stat_activity、pg_locks、
   │     pg_stat_bgwriter、pg_replication_slots、pg_settings…）
   │  ③ 按服务器 semver（blang/semver 探测，如 16.15.0）裁剪查询
   ▼
PostgreSQL 实例（要求账号具备 pg_monitor 等预置角色）

几个值得展开的实现细节（均可在本专栏 C1/D1 实测复现）：

• 版本自适应：首次抓取时探测服务器语义版本并打印 Semantic version changed ... to=16.15.0 日志，据此选择兼容 SQL。实测日志（0.20.1，目标 PostgreSQL 16.15）：level=INFO source=postgres_exporter.go:537 msg="Semantic version changed" server=10.89.74.10:5432 from=0.0.0 to=16.15.0。
• collector 注册表与自观测：每次抓取输出 pg_scrape_collector_success{collector="<名>"} 与 pg_scrape_collector_duration_seconds，15 个默认启用的 collector 一目了然；另有 pg_up、pg_exporter_last_scrape_duration_seconds、pg_exporter_last_scrape_error、pg_exporter_scrapes_total、pg_exporter_build_info 等自观测指标。默认一轮抓取在本文实测环境产出 547 条 pg_* 指标、约 9.2 万字节文本。
• 超时熔断：PG_EXPORTER_COLLECTION_TIMEOUT（默认 1m）限制单轮采集总时长，超时即断开连接，防止慢查询堆积耗尽数据库连接池（v0.19.0 引入）。实测该值设为 0 时 exporter 仍能启动监听，但数据库 collector 全部不注册，/metrics 只剩 29 条自观测指标——升级排障时容易误判为"配置生效了但没数据"，见 C1 实录。
• 日志脱敏：连接串中的密码在错误日志中自动替换为 PASSWORD_REMOVED，实测确认。

3.2 权限模型

采集账号不需要超级用户：PostgreSQL ≥ 10 可授予内置角色 pg_monitor（或更小的 pg_read_all_stats）。要注意 pg_monitor 只覆盖统计视图读取，自定义 queries.yaml 里的业务表查询仍需显式 GRANT SELECT——本文实测中，未授权业务表时抓取报 pq: permission denied for table orders、pg_exporter_last_scrape_error 置 1，授权后恢复（完整实录见 C1）。wal collector 因读取 pg_ls_waldir() 还额外要求相应函数权限，实测未授权该函数时仅单个 collector 失败、pg_up 仍为 1，这是排障时区分"整库连不上"与"单采集器失败"的关键观测点。

四、许可与治理

• 许可：Apache License 2.0（GitHub API license.spdx_id: Apache-2.0；发行包内 LICENSE 文件同为 Apache 2.0 文本，本地实查）。
• 治理：prometheus-community 官方维护，属 Prometheus 官方生态的数据库导出器之一；仓库 2015-08-24 创建，至查询日（2026-10-27 最新 push）持续活跃 11 年。
• 规模（GitHub API + shields.io，2026-10-28）：星 3644（shields.io 显示 3.6k）、fork 843、开放 issue 192。
• 语言栈：Go（go 1.25.0 起步编译要求）；旗标解析用 kingpin/v2，版本探测用 blang/semver，数据库驱动为经典 lib/pq——这决定了它默认 sslmode=require，对未启用 TLS 的实例必须显式 ?sslmode=disable，是新手最常踩的第一坑（实测回显 pq: SSL is not enabled on the server，见 B1/C1）。

五、竞品量化对比

PostgreSQL 监控选型常见三条路：postgres_exporter（Prometheus 生态标准件）、pgexporter（新兴 C 语言高性能导出器）、pgMonitor（CrunchyData 的监控配置集，非独立 exporter）。量化对比如下（除注明外均为 2026-10-28 实查）：

选型结论：

1. 已用 Prometheus 栈：postgres_exporter 是默认正确答案——生态成熟度（Grafana 官方面板 ID 9628 等）、社区规模、文档覆盖都无可替代，且 Go 静态二进制落地成本最低。
2. 追求极致性能与低依赖、可接受编译安装：可评估 pgexporter（C 语言、事件驱动），尤其与管理多实例的集中式部署契合；两者同机共存亦无冲突（监听端口与采集逻辑互不干扰）。延伸阅读见 pgexporter 专栏：《pgexporter 0.8.0 介绍与选型指南》。
3. 使用 CrunchyDB 发行版：pgMonitor 提供现成规则集，但其采集层仍落在 postgres_exporter 上，本质是"配置集 + 本文主角"的组合。
4. 自定义业务指标强需求：postgres_exporter 的 queries.yaml（虽已标 DEPRECATED，实测行为稳定）上手最快；若要更通用的任意 SQL 数据源采集，可另评估 sql_exporter。

六、适用与不适用场景

适用：

• Prometheus/VictoriaMetrics + Grafana 技术栈下的 PostgreSQL 健康监控（连接数、事务/缓存命中率、WAL 速率、复制延迟、长事务、锁等待）。
• 多实例集中采集：常规一实例一进程，或以 /probe 多目标模式集中部署。
• 需要在不改造应用的前提下补充业务侧指标（queries.yaml 自定义 SQL）。

不适用/需补充：

• 非 Prometheus 生态（如 Zabbix 原生模板场景）。
• 需要 OS 层主机指标时它只管数据库，需另配 node_exporter。
• 数据库体量大、单实例连接预算紧张时，务必配置 PG_EXPORTER_COLLECTION_TIMEOUT 并收敛默认 collector（本文 C1 给出实测基线：默认 15 个 collector 一轮 547 条指标、抓取约 6ms 起步）。

七、参考与延伸

• 本专栏系列：安装部署指南（B1）、《配置参数详解（C1）》、《常用 CLI 命令与工具详解（D1）》。
• 站内延伸：《pgexporter 0.8.0 介绍与选型指南》、《PostgreSQL 18.6 介绍与选型指南》。
• 上游：prometheus-community/postgres_exporter v0.20.1 Release（2026-07-08）；README（flags/environment variables 章节）；v0.20.0 Release 的 BREAKING CHANGES 原文。
• 数据取证：GitHub API（repo/releases/latest/contents）、shields.io JSON 徽章，查询日期 2026-10-28。