开发指南

PG Exporter 将 SQL 和指标定义放在 YAML 中，由 Go 运行时加载定义、采集结果并提供 HTTP 服务。修改功能时，先确定行为由哪一层负责。

用户手册以稳定版 v1.5.0 为准。开发提交 c0ba58a 还包含尚未发布的 Composite、Patroni、pgBackRest 和 PostgreSQL 日志功能，其约定与状态见设计归档。

仓库结构

工具链

v1.5.0 标签声明 Go 1.27.3。按所构建版本的要求选择工具链。构建稳定标签：

git clone --branch v1.5.0 https://github.com/pgsty/pg_exporter.git
cd pg_exporter
go mod download
make build
./pg_exporter --version

make build 和 GoReleaser 都会注入版本、分支、提交和构建日期。发布产物关闭 CGO。分支构建可能保留默认发布版本号，因此识别二进制时需要同时检查提交号。

修改代码时，从选定的源版本建立工作分支。编辑前阅读 AGENTS.md，并检查 git status --short --branch。

改动前后运行测试

go mod tidy -diff
go test -race -count=1 ./...
GODEBUG=httpmuxgo121=1 go test -count=1 ./...
go vet ./...

配置测试覆盖 PostgreSQL 与 PgBouncer 分支选择、旧版采集器、生成文件一致性、指标名、标签、谓词和快照直方图。运行时测试覆盖并发抓取、重载和 HTTP 处理器。SQL 兼容性还需要在每个受影响数据库版本上，以监控角色执行查询来验证。

修改运行时时，还应交叉构建六个发布目标：Linux amd64/arm64/ppc64le、Darwin amd64/arm64、Windows amd64。已有辅助命令：

make goreleaser-build

此命令会在需要时安装 GoReleaser，并重建 dist/ 中的快照产物。二进制、软件包和发布压缩包不应加入 Git。

修改或新增采集器

1. 选择数字分组与唯一的顶层分支名。
2. 多个版本/角色分支需要输出同一指标族时，用 name 固定指标命名空间。
3. SQL 使用显式结果列清单。
4. 尽可能精确地添加 min_version / max_version、角色标签、事实标签与谓词。
5. 在 metrics 下准确声明每个返回列一次。
6. 根据运维开销与失败影响选择 ttl、timeout、fatal、skip。
7. 运行配置测试，重建合并文件并检查 Diff。
8. 以监控角色在每个相关服务器版本与角色上测试查询。
9. 公共指标变化时更新内置采集器和相关手册，版本发布时再补充发布说明。

请阅读本次修改所基于版本中的 config/0000-doc.yml。当前配置手册解释稳定版格式。

公共接口或架构决策写入伴生仓库的双语设计归档，说明源代码版本、决策、备选方案和交付状态。标签和产物发布前，将新行为标为未发布。小型代码修复补充测试和相关手册即可，无需新建设计文章。

列规则

• LABEL 变为 Prometheus 标签，应避免无边界或敏感值。
• GAUGE 用于可双向变化的值。
• COUNTER 用于源端单调递增值（服务器重启/统计重置仍会归零）。
• HISTOGRAM 从 SQL 行构建快照分布；其 _bucket、_count、_sum 序列是可下降的 Gauge，不能应用 rate() 或 increase()。
• DISCARD 忽略结果列，不对外导出。
• rename、default、scale 会改变输出名称/值语义，需要兼容性审查。

采集器包含直方图时，le 是保留标签。指标名与标签名在加载配置时完成校验，非法名称会在抓取前失败。

重建配置

make conf     # config/*.yml -> pg_exporter.yml
make conf9    # legacy/config/*.yml -> legacy/pg_exporter.yml

git diff -- pg_exporter.yml legacy/pg_exporter.yml

这两个生成的 YAML 文件已由 Git 跟踪。CI 会检查它们与有序源文件是否一致。修改配置片段后重新生成 YAML，并将两者一起纳入改动。

本地验证采集器

# 只验证语法/Schema，不需要目标
./pg_exporter --config=./config --dry-run

# 生成目标特定计划并退出
PG_EXPORTER_URL='postgres://monitor@localhost/postgres' \
  ./pg_exporter --config=./config --explain --fail-fast

# 运行并查看规划、耗时与错误
PG_EXPORTER_URL='postgres://monitor@localhost/postgres' \
  ./pg_exporter --config=./config --log.level=debug
# 在另一个终端中执行
curl -fsS localhost:9630/metrics >/dev/null
curl -fsS localhost:9630/explain
curl -fsS localhost:9630/stat

--explain 只选择采集器，不执行 SQL。通过指标端点测试结果和权限，既测试有数据结果，也测试零行结果。缺少配置声明的 LABEL 或 HISTOGRAM 列时，无论是否有结果行，都会拒绝整个采集器结果。

缓存或可选组件还应测试禁用路径、故障隔离、重载和关闭。日志持久化状态还需覆盖重启、轮转、截断、半条记录和状态文件权限。

发布流水线

GoReleaser 会生成：

• Linux、macOS、Windows 压缩包；
• RPM 与 DEB 软件包；
• SHA256 checksums.txt；
• amd64/arm64 Docker 镜像与多架构 Manifest；
• 对应标签的 GitHub Release。

打标签前，对齐 exporter.Version、Makefile 版本、软件包元数据和发布文档。发布工作流完成后，核验压缩包和软件包校验和、容器清单、二进制构建提交。随后更新本站 params.version、下载校验和、落地页版本数据、手册及相关设计记录。

本地快照构建用于检查打包，不会发布版本。带标签产物通过发布工作流交付；部署后另行验证实际安装的版本。

文档工作流

在伴生仓库 exp.pgsty.com 中编辑本站文档。同步修改中英文页面后运行：

make check

该命令执行严格告警构建，并检查 Markdown 和内部链接。还应查看两种语言的渲染结果，重点检查命令、表格和窄屏溢出。

导入脚本可从 Pigsty 手册更新 install、deploy、config、api 和发布历史。先生成到临时目录，避免覆盖本站已有编辑：

preview_dir=$(mktemp -d)
python3 bin/sync_pg_exporter_content.py \
  --pigsty-io ../pigsty.io \
  --pigsty-cc ../pigsty.cc \
  --output "$preview_dir"

对照 content/ 检查导入结果，只应用相关变更。本站扩展指南和设计归档在本仓库直接维护。

PG Exporter 源码贡献使用 Apache 2.0，本站原创文档使用 CC BY 4.0。软件改动提交到 pgsty/pg_exporter，文档改动提交到 pgsty/exp.pgsty.com。