pg_exporter 1.5.0 介绍与选型指南

目标：全面认知 pg_exporter——Go 编写、YAML 声明式驱动的 PostgreSQL/PgBouncer Prometheus 指标采集器，厘清它与 postgres_exporter、pgexporter 两个"同名姊妹"项目的本质差异，并给出可落地的选型结论。本文所有版本、星数、兼容矩阵、发布节奏均来自官方仓库与发布通道联网溯源（来源与查询日期逐处标注），认知篇不做本地实测。

一、环境信息

本文为 A1 认知篇，全部结论来自以下官方渠道的联网溯源，未做本地实测：

• 溯源对象：pg_exporter 官方仓库，原址 Vonng/pg_exporter，现已迁入 Pigsty 官方组织 pgsty/pg_exporter（README 所有徽章与 Release 链接均指向该组织，查询日期 2026-10-31）
• 基准版本：v1.5.0（GitHub Releases 最新稳定版，releases.atom 实查首个条目 PG Exporter v1.5.0；README 版本徽章同值；官方 Docker 镜像 pgsty/pg_exporter:1.5.0 标签实查 org.opencontainers.image.version=1.5.0、镜像构建时间 2026-10-23T01:33:50Z，查询日期 2026-10-31）
• 构建信息：官方镜像内执行 --version 徽章口径与 Release 构建产物一致——pg_exporter v1.5.0 (built with go1.27.3 on linux/amd64)（GoReleaser 产物元数据，查询日期 2026-10-31）
• 社区热度：GitHub Stars 366、Forks 61（shields.io 实查 img.shields.io/github/stars/Vonng/pg_exporter.json 与 github/forks 同名接口，查询日期 2026-10-31；仓库迁移后旧址自动重定向到 pgsty/pg_exporter，星数同值）
• 许可协议：Apache-2.0（README License 徽章与镜像 label org.opencontainers.image.licenses 双重确认，查询日期 2026-10-31）
• 关联阅读：本文为 PostgreSQL 采集器三部曲之三，姊妹项目文档已先行交付——《postgres_exporter 0.20.1 介绍与选型指南》（prometheus-community 出品，Go）、《pgexporter 0.8.0 介绍与选型指南》（C 语言）。三者名字高度相似但实体完全不同，第七章有逐维量化对比。

💡 技术拓展：PostgreSQL 的 Prometheus 指标导出器不止本文主角一家。业界常见选项对比——

项目	出品方	语言	配置模型	一句话定位
postgres_exporter	prometheus-community	Go	默认 collector + queries.yaml 自定义	事实标准，Prometheus 官方生态默认选择
pg_exporter（本文）	Vonng / Pigsty	Go	YAML 声明式采集器（SQL 即配置）	指标定义完全声明化，深度可定制
pgexporter	pgexporter.org 社区	C	TOML 多 server 配置	原生 C 实现的 PG 官方外围工具
pgSCV	weaponry	Go	内置 collector 集	同时覆盖 PostgreSQL 与系统层指标

本文主角是 pg_exporter：与 postgres_exporter 同为 Go 实现，但把"定义哪些指标"这件事完全交给了 YAML 配置文件——代码里只有执行引擎，指标本体全部是配置（官方 README 原话："this project contains more lines of YAML than go"，即 YAML 行数多于 Go 代码行数）。

二、软件概述

pg_exporter 是一个面向 PostgreSQL 与 PgBouncer 的 Prometheus 指标导出器（exporter），以常驻 HTTP 服务方式运行，等待 Prometheus 服务器周期性抓取 /metrics 端点，把数据库内部状态翻译成 Prometheus 指标文本（来源：官方仓库 README 项目副标题 "Advanced PostgreSQL & Pgbouncer metrics exporter for Prometheus"，查询日期 2026-10-31）。

它的官方自述强调三个关键词：declarative config（声明式配置）、dynamic planning（动态规划）、customizable collectors（可定制采集器）。官方给出的能力口径是：随附的默认配置定义了 460 个独立指标，横跨 96 条采集器分支（collector branch）与 59 个命名空间（namespace）（来源：README 首页，查询日期 2026-10-31；实际暴露的时序数量取决于 PostgreSQL 版本、启用的采集器、数据库与对象数量及标签基数）。

pg_exporter 由 Ruohang Feng（网名 Vonng，rh@vonng.com） 开发，他是 PostgreSQL 一键部署发行版 Pigsty 的作者；pg_exporter 正是 Pigsty 的监控数据底座——Pigsty 官方演示站 demo.pigsty.io 的监控大盘即基于它构建（来源：README "Check demo.pigsty.io for live demo, which is built upon this exporter by Pigsty"，查询日期 2026-10-31）。这意味着它的默认指标集经过了 12000+ 核、6 年以上真实生产环境的长期锤炼（README 原文 "Battle-tested in real-world environments across 12K+ cores for 6+ years"）。

项目在 2026 年已从个人仓库 Vonng/pg_exporter 迁入 pgsty 组织（README 徽章与 Docker Hub 镜像 pgsty/pg_exporter 均为新址），发布通道同步提供：

• GitHub Releases：tarball / RPM / DEB 三种发行包（GoReleaser 构建，覆盖 amd64/arm64/ppc64le；v1.5.0 checksums.txt 实查共 12 个资产文件，查询日期 2026-10-31）
• Docker Hub：官方多架构镜像 pgsty/pg_exporter（amd64/arm64，由 GoReleaser 与其他发布物一起构建；README "Docker" 一节明示 "You can find pre-built amd64/arm64 docker images here"，查询日期 2026-10-31）
• Pigsty Infra Repo：Pigsty 自建的 YUM/APT 软件源（README "RPM / DEB / Tarball available in the GitHub release page, and Pigsty's YUM / APT Infra Repo"，查询日期 2026-10-31）

一个值得认知的量化事实：v1.5.0 的 linux-amd64 tarball 仅 5.67 MB，解压后的二进制约 14.3 MB，为静态链接、无任何运行时依赖的单一可执行文件（tarball 资产 pg_exporter-1.5.0.linux-amd64.tar.gz 实测下载后 sha256sum 与官方 checksums.txt 记录值 e372f6defb844b4bfbe3286b40dba3d4aae2ce72c4bed9980e3b9a56507aef56 一致，查询日期 2026-10-31）。这继承了 Go 生态"单二进制交付"的一贯优点：拷贝即用，对目标主机零侵入。

三、核心架构

pg_exporter 的架构可以概括为「一个执行引擎 + 一堆 YAML 定义的采集器 + 一组规划器」。以下结构描述依据官方 README 与随附配置文件的溯源（查询日期 2026-10-31）。

3.1 数据流全景

一次完整的指标抓取链路是：

PostgreSQL / PgBouncer 实例
        ↑ SQL 查询（pg_exporter 以监控账号连接）
pg_exporter 常驻进程（默认监听 :9630）
   ① 配置加载：读取 YAML（单文件或目录合并）
   ② 动态规划：按版本/标签/数据库把采集器分支装到对应 server 对象上
   ③ 抓取执行：Prometheus 拉取 /metrics 时按计划逐条执行 SQL（带 TTL 缓存）
   ④ 结果翻译：行/列 → Prometheus 指标（LABEL/GAUGE/COUNTER/HISTOGRAM）
        ↓ HTTP 文本
Prometheus 服务器（抓取与存储）

• ① 配置加载：默认配置检索优先级为 --config 命令行参数 → PG_EXPORTER_CONFIG 环境变量 → 当前目录 pg_exporter.yml → /etc/pg_exporter.yml → /etc/pg_exporter/（目录）。若给的是目录，目录内所有 YAML 按字母序合并（来源：README 随附 pg_exporter.yml 头部注释 "Config File" 一节，查询日期 2026-10-31）。
• ② 动态规划（dynamic planning）：这是 pg_exporter 区别于同类的核心设计。每个采集器分支带有标签（tags）与版本边界（min_version/max_version），规划器据此决定某条 SQL 是否"安装"到某个数据库 server 上——例如带 primary 标签的分支只在主库执行、带 dbname:dbtest 标签的分支只对名为 dbtest 的数据库安装、带 extension:timescaledb 标签的分支只在装了该扩展的库执行。本文引用的 README 配置文档明确列出这些语义（查询日期 2026-10-31）。
• ③ 抓取执行：每条采集器查询支持独立配置 TTL 缓存（ttl，秒）与超时（timeout，秒，超时查询会被取消），还可声明 fatal（失败即中止整个 scrape）或 skip（规划阶段直接不装）。
• ④ 结果翻译：查询返回的每一列按 usage 声明翻译——LABEL（列值变标签）、GAUGE（仪表量）、COUNTER（计数器）、HISTOGRAM（聚合为快照分布，官方有一份专门的 SQL Histogram 契约设计文档）、DISCARD（忽略）。指标全名 = <namespace>_<column>，namespace 可被采集器的 name 字段覆盖。

3.2 关键对象模型

• Target（目标）：由连接 URL 指定，默认回退到 postgresql:///?sslmode=disable；若 URL 未显式写 sslmode，pg_exporter 会自动注入 sslmode=disable——这是面向"exporter 与数据库同机部署"的有意设计，避免回环 TLS 开销；远程目标需显式声明 sslmode=require/verify-ca/verify-full（来源：README "Connection URL Defaults" 一节，查询日期 2026-10-31）。
• Server（数据库级采集对象）：开启 --auto-discovery（默认开启）时，pg_exporter 自动发现目标实例上所有可连接数据库并为每个库生成独立的 Server 规划，排除项由 --exclude-database（默认 template0,template1,postgres）控制。
• Collector Branch（采集器分支）：同一 namespace 下可以有多条按条件互斥的分支（如 pg 命名空间的"主库分支"与"从库分支"），规划器保证每个 namespace 至多选中一条分支执行。官方仓库 config/ 目录维护了 58 个采集器定义文件，由 make conf 合并为单一 pg_exporter.yml（来源：README Collectors 一节，查询日期 2026-10-31）。
• 自监控指标：内置 pg_up、pg_version、pg_in_recovery、pg_exporter_build_info 等，以及一整套 pg_exporter_* 前缀的自我观测指标（每条查询的抓取次数/命中缓存次数/错误次数/耗时/TTL），可用 --disable-intro 关闭（来源：README Quick Start 与 Usage，查询日期 2026-10-31）。

四、功能特性

以下特性清单逐条溯源自官方 README（查询日期 2026-10-31），并补充含义解读：

1. 高度可定制（Highly Customizable）：几乎所有指标都由声明式 YAML 配置定义。新增一个监控指标 = 往 YAML 里加一段「SQL + 列 usage 声明」，无需改代码、无需重新编译。
2. 版本覆盖面（Version Coverage）：常规配置验证覆盖 PostgreSQL 10–18 与 19 RC1；旧配置包（legacy config bundle）覆盖 PostgreSQL 9.1–9.6；PgBouncer 验证至 1.26.1。这是三个"同名姊妹"中对旧版本覆盖最广的一家。
3. 细粒度控制（Fine-grained Control）：每条采集器查询可独立配置超时、缓存 TTL、跳过条件（skip/tags）与致命性（fatal）。
4. 动态规划（Dynamic Planning）：基于条件定义多查询分支——不同 PostgreSQL 版本自动选中不同 SQL（如 pg_sub 订阅统计的 PG19 分支覆盖表/序列同步错误与逻辑复制冲突计数）。
5. 自监控（Self-monitoring）：暴露关于 pg_exporter 自身丰富指标（缓存命中率、每查询耗时、错误计数等），对采集器本身的健康度完全可观测。
6. 生产就绪（Production-Ready）：在 12000+ 核的真实环境中锤炼 6 年以上（Pigsty 用户群背书）。
7. 自动发现（Auto-discovery）：自动发现并监控同一实例内的多个数据库，无需为每个库手工配置。
8. 健康检查 API（Health Check APIs）：完整的 HTTP 端点族——存活检查（/up、/health、/liveness、/readiness）与流量路由检查（/primary、/replica、/read 等十余个），可直接用于负载均衡/服务发现的健康探测。
9. 扩展支持（Extension Support）：对 timescaledb、citus、pg_stat_statements、pg_wait_sampling 等扩展提供专用采集器。
10. 本地优先的 URL 行为（Local-first URL behavior）：为同机部署优化，URL 缺省时回退本机默认连接串并自动 sslmode=disable。

v1.5.0 的更新要点（来源：README v1.5.0 小节，查询日期 2026-10-31）：基于 Go 1.27.3 构建并更新了 Prometheus、HTTP/2、压缩与 YAML 依赖；修正了复制指标的身份与状态映射、畸形连接 URL 的防护；修复了数据库发现、并发健康响应、元数据重规划、时长校验与自定义指标路由等问题；为 pg_sub_* 指标新增 datname 标签，并补充 PostgreSQL 10–13 的监控授权说明。

五、快速开始（最小可用示例）

以下流程溯源自官方 README 的 Quick Start 与 Usage（查询日期 2026-10-31），是最小可运行路径：一个监控账号 + 一条环境变量 + 一次启动。

第 1 步：准备监控账号。在目标 PostgreSQL 上创建监控用户并授予 pg_monitor 系统角色（只读监控权限，非超级用户）：

CREATE USER dbuser_monitor WITH PASSWORD 'q1w2e3r4';
GRANT pg_monitor TO dbuser_monitor;
GRANT USAGE ON SCHEMA pg_catalog TO dbuser_monitor;

pg_monitor 是 PostgreSQL 内置的预置角色，聚合了 pg_read_all_stats 等观测类权限，官方 README 的 v1.5.0 更新说明特别提醒了 PostgreSQL 10–13 需要的监控授权事项（老版本还需显式授权部分函数）。

第 2 步：获取并运行 pg_exporter。官方 Quick Start 给出的最小启动方式是：

PG_EXPORTER_URL='postgres://dbuser_monitor:q1w2e3r4@localhost:5432/postgres' pg_exporter
curl http://localhost:9630/metrics   # 访问指标

即通过 PG_EXPORTER_URL 传入目标连接串，启动后指标端点固定在 :9630/metrics（注意：不是 postgres_exporter 惯用的 9187 端口）。二进制可通过 GitHub Release 页下载（tarball/RPM/DEB），也可使用官方镜像 pgsty/pg_exporter:1.5.0；RPM/DEB 包安装后的文件布局为：/usr/bin/pg_exporter（二进制）、/etc/pg_exporter.yml（默认配置）、/usr/lib/systemd/system/pg_exporter.service（systemd 单元）、/etc/default/pg_exporter（服务环境变量），开箱即可 systemctl enable --now pg_exporter（来源：README Deployment 一节，查询日期 2026-10-31）。

第 3 步：验证内置指标。启动后无需任何配置即可拿到内置指标：pg_up（是否存活）、pg_version（服务器版本号）、pg_in_recovery（是否恢复中）、pg_exporter_build_info（构建信息）与 pg_exporter_* 自监控指标；其余全部指标由 pg_exporter.yml 配置文件定义（README 原话 "All other metrics are defined in the pg_exporter.yml config file"）。不传连接串时回退默认 URL postgresql:///?sslmode=disable 并按同机假设自动禁用 SSL。

💡 技术拓展：exporter 的部署拓扑有「同机部署」与「中心化远程采集」两种常见形态——

形态	做法	取舍
同机部署（local-first）	exporter 与数据库同主机，URL 走 localhost	pg_exporter 默认优化方向：免 TLS、低开销；每台数据库机一个 agent
中心化远程采集	少量 exporter 集中部署，URL 指向远端库	集中管理但需显式配置 sslmode 并放开数据库远连权限

pg_exporter 的默认行为（隐式本机回退 + 自动 sslmode=disable）表明其首选形态是前者；需要远程采集时应在 URL 中显式声明 sslmode。完整部署步骤见 《pg_exporter 1.5.0 Docker Compose 部署指南》。

六、适用场景与限制

6.1 适用场景

结合官方特性与 Pigsty 生产背景，pg_exporter 适合以下场景（溯源 + 解读，查询日期 2026-10-31）：

1. Pigsty 用户 / 想要 Pigsty 同款监控大盘：pg_exporter 是 Pigsty 监控体系的原生底座，配合其 Grafana 大盘可直接获得现成的 PostgreSQL 可视化。
2. 需要深度自定义指标的场景：业务想监控"订单表行数、队列积压深度"这类业务级指标时，pg_exporter 只需加一段 YAML（SQL + 列声明），而 postgres_exporter 的自定义查询在表达力与调度控制（版本分支、数据库限定、TTL 缓存）上明显更粗。
3. 多数据库实例/多版本混合机群：auto-discovery 自动纳管同实例多库；动态规划按版本自动切换 SQL 分支，PG 10–18 混跑的机群共用一份配置。
4. 主从架构的流量路由：十余个健康检查端点（/primary、/replica、/read 等）可直接挂到 HAProxy/负载均衡健康探测上，实现读写分离自动摘除故障节点。
5. 旧版本 PostgreSQL 存量环境：legacy 配置包覆盖 PG 9.1–9.6，是同类中唯一明确支持如此老版本的（对仍运行 PG 9.x 的遗留系统尤为关键）。

6.2 已知限制与注意点

1. 默认端口与同类不同：v1.x 监听 :9630，从 postgres_exporter 迁移而来时注意 Prometheus 抓取目标与防火墙规则都要改端口（来源：README Usage 表 --web.listen-address=:9630，查询日期 2026-10-31）。
2. 默认配置指标量大，需按需裁剪：官方默认配置含 460 个指标、96 条分支；数据库基数大时高基数标签（如按 datname 拆分的指标）会放大时序数量，官方 README 亦提示"实际时序数量取决于版本、启用采集器、数据库与对象数量"。
3. Debian/Ubuntu 生态的现成度：RPM/DEB 包通过 GitHub Release 与 Pigsty Infra Repo 分发，未进主流发行版仓库；systemd 服务以 prometheus 用户运行（unit 文件 User=prometheus），部署时需准备该用户或自行调整。
4. 远程采集需显式 sslmode：默认注入 sslmode=disable 是同机优化，跨网络场景若忘记显式声明 sslmode 会静默走明文，需在安全上留意（README Connection URL Defaults 明示该行为）。
5. 社区规模有限：366 Stars / 61 Forks 属于小众精品型项目；但其生产背书来自 Pigsty 用户群（12K+ 核、6 年实战）而非 GitHub 热度，评估时不应只看星数。

七、同类选型对比

PostgreSQL 监控选型中最容易混淆的就是本章三个"同名姊妹"：pg_exporter（本文）、postgres_exporter、pgexporter。三者名字仅差一个下划线或后缀，实体完全无关。下表为逐维量化对比（pg_exporter 数据溯源自官方 README/Releases/shields.io，查询日期 2026-10-31；postgres_exporter 与 pgexporter 数据取自平台已交付的姊妹篇文档，来源与查询日期见对应篇目）：

关键差异解读（如何选）：

• 三者是"三选一"而非"一起用"：它们都是 PostgreSQL 的 Prometheus exporter，功能定位重叠，同时部署两套只会重复采集浪费资源（pgSCV 那种覆盖系统层的除外）。
• 指标定制深度上 pg_exporter 明显领先：postgres_exporter 的 queries.yaml 只能"加自定义 SQL"，而 pg_exporter 的每条采集器都带版本边界、标签调度（primary/standby/dbname/extension）、TTL 缓存、超时、fatal 语义与谓词查询，相当于把「监控 SQL 的调度框架」做成了配置项——这正是其 README 把 "dynamic planning" 列为核心卖点的原因。
• 生态与社区热度上 postgres_exporter 占优：3.6k Stars、prometheus-community 官方维护，是 Prometheus 文档里的默认答案；选它不会错，但要深度定制时上限低。
• pgexporter 走差异化路线：C 语言原生实现、多 server 汇聚/透传与 Web 控制台是独有卖点，适合偏好"一个采集器管多套库"的场景。
• 一句话结论：已有 Prometheus 官方体系、需求以"开箱即用"为主 → 选 postgres_exporter；追求指标深度定制/Pigsty 大盘/多版本机群统一纳管 → 选本文的 pg_exporter；需要 C 原生实现与 Web 控制台 → 选 pgexporter。

版本节奏量化（pg_exporter 近期 Release 时间线，来源：GitHub releases.atom 实查，查询日期 2026-10-31）：v1.2.0 → v1.2.1 → v1.2.2 → v1.3.0（主题为 PG19 支持）→ v1.4.0 → v1.4.1 → v1.5.0（2026-10-23 构建），主干持续活跃（仓库最近提交月份为 2026 年 10 月，shields.io last-commit 徽章实查），2026 年内已连续发布 7 个版本，迭代节奏健康。

八、参考链接

1. pg_exporter 官方仓库（现址）：https://github.com/pgsty/pg_exporter （原址 Vonng/pg_exporter 自动重定向；README、releases.atom、LICENSE 均取自此，查询日期 2026-10-31）
2. 官方 Release 页（v1.5.0 及 checksums.txt）：https://github.com/pgsty/pg_exporter/releases （查询日期 2026-10-31）
3. 官方 Docker 镜像：https://hub.docker.com/r/pgsty/pg_exporter （镜像 label 实查 version=1.5.0、license=Apache-2.0、source 仓库地址，查询日期 2026-10-31）
4. Pigsty 官方文档站（pg_exporter 文档页 exp.pgsty.com 与 Pigsty Infra Repo 说明）：https://exp.pgsty.com 与 https://pigsty.io/docs/repo/infra （查询日期 2026-10-31）
5. Pigsty 在线演示（基于 pg_exporter 的监控大盘）：https://demo.pigsty.io/ui/ （README 引用，查询日期 2026-10-31）
6. 星数/提交活跃度取证徽章：img.shields.io（stars=366、forks=61、last-commit=2026-10，查询日期 2026-10-31）
7. 站内姊妹篇：《postgres_exporter 0.20.1 介绍与选型指南》、《pgexporter 0.8.0 介绍与选型指南》
8. 站内后续篇目：部署实操见 《pg_exporter 1.5.0 Docker Compose 部署指南》；配置体系逐项拆解见 《pg_exporter 1.5.0 配置参数详解》；命令行工具全解见 《pg_exporter 1.5.0 常用 CLI 命令与工具详解》