HTTP API

pg_exporter 默认在 :9630 提供指标、健康检查和管理端点。本页适用于稳定版 v1.5.0。用 --web.listen-address 设置监听地址，详见命令参考。

表中列出各端点的常用方法，只有 /reload 会明确拒绝其他方法。未匹配路径会交给根页面处理，配置探针时请使用表中的路径。

指标端点

GET /metrics

每次请求都会采集主目标及自动发现数据库的指标。采集器缓存有效时，直接返回缓存结果。

curl -fsS http://127.0.0.1:9630/metrics

响应示例：

# HELP pg_up last scrape was able to connect to the server: 1 for yes, 0 for no
# TYPE pg_up gauge
pg_up 1
# HELP pg_version server version number
# TYPE pg_version gauge
pg_version 180000
# HELP pg_in_recovery server is in recovery mode? 1 for yes 0 for no
# TYPE pg_in_recovery gauge
pg_in_recovery 0

数据库故障时，端点仍可能返回 HTTP 200，正文中 pg_up 为 0。检查 HTTP 状态时也要检查指标。普通采集器出错后，本轮不输出该采集器的结果，其他采集器继续执行。致命采集器出错后，停止该数据库的后续采集。HTTP 500 表示指标汇总或编码失败，例如指标定义冲突。

自监控指标

PostgreSQL 的内置指标前缀默认为 pg，PgBouncer 默认为 pgbouncer。--namespace 可以修改此类前缀，但不会改变 YAML 中定义的指标名。

这些序列也会附加配置的固定标签。数据库和采集器级别的累计计数以 Gauge 暴露。服务器重新规划时会重置采集器统计，配置重载也会触发这一过程。数据库连接对象重建时会重置该数据库的统计。

--disable-intro 会隐藏表中所有内置指标，包括 pg_up。YAML 指标、Go/进程指标和 HTTP 健康检查仍然可用。

健康检查

GET /up

/up 返回主连接目标的缓存健康状态。exporter 每秒探测一次目标，抓取完成后也会更新状态。HTTP 健康请求只读取缓存，不执行 SQL。

curl -i http://127.0.0.1:9630/up

/health、/liveness、/readiness 和 /read 使用同一处理器，检查的是数据库目标，而非 exporter 进程本身。在 Kubernetes 中，如果希望数据库故障只影响就绪状态、不重启 exporter，可使用 TCP 存活探针和 HTTP 就绪探针：

livenessProbe:
  tcpSocket: { port: 9630 }
  initialDelaySeconds: 5
  periodSeconds: 10
readinessProbe:
  httpGet: { path: /readiness, port: 9630 }
  initialDelaySeconds: 5
  periodSeconds: 5

流量路由

角色检查使用主连接 PostgreSQL 目标的 pg_is_in_recovery()。它们判断角色和连通性，不检查应用权限或事务只读设置。

响应正文为状态名称。在 PgBouncer 模式下，SHOW VERSION 探测成功会被映射为 primary，并不代表连接池后端 PostgreSQL 的角色。按角色路由时，应使用直接连接 PostgreSQL 的 exporter。

每个健康响应从同一个原子状态快照生成 HTTP 状态码与正文，修复并发状态变化时可能出现的矛盾响应；状态仍然来自缓存。指标路径校验还会确认请求在当前 HTTP mux 下确实进入指标处理器。为兼容旧版 mux，优先使用 /metrics 这样的未转义路径。

GET /primary

别名：/leader、/master、/read-write、/rw。

GET /replica

别名：/standby、/slave、/read-only、/ro。

GET /read

/up 的别名，主库和从库均可返回成功。

HAProxy 示例

在每个 PostgreSQL 实例旁运行 exporter。客户端流量发送到 5432 端口，健康检查发送到 9630 端口：

backend pg_primary
  mode tcp
  option httpchk GET /primary
  http-check expect status 200
  server pg1 10.0.0.1:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg2 10.0.0.2:5432 check port 9630 inter 3000 fall 2 rise 2

backend pg_replicas
  mode tcp
  balance roundrobin
  option httpchk GET /replica
  http-check expect status 200
  server pg1 10.0.0.1:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg2 10.0.0.2:5432 check port 9630 inter 3000 fall 2 rise 2

将 /replica 换为 /read，即可让读流量使用任意可用角色。

运维端点

GET /reload / POST /reload

用 POST 重载当前选择的配置文件或目录：

curl -fsS -X POST http://127.0.0.1:9630/reload

重载会替换采集器定义，清除其缓存和查询统计，使旧计划失效。重载不会执行新 SQL。空 YAML 文件属于有效配置，会将计划替换为零个配置采集器，内置指标仍保留；单文件重载被拒绝时保留旧定义。完成后抓取 /metrics，检查采集器错误。目录加载可以跳过无效文件并加载其他有效文件，应检查日志中的 skip config 警告。

Unix 上还可以发送 SIGHUP 或 SIGUSR1 重载。SIGTERM 会结束进程，不等待活跃 HTTP 请求完成。修改连接 URL、固定标签、Tag 或监听地址需要重启进程。通过防火墙、反向代理或 --web.config.file 限制管理访问，详见安全指南。

GET /explain

返回主连接选中的采集器的纯文本定义，包括 SQL、标签、TTL、超时和指标映射。首次规划前和刚完成重载时，输出为空。先执行一次抓取：

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

此端点不执行 PostgreSQL EXPLAIN 或谓词查询，不列出被排除的分支，也不包含自动发现数据库的计划。分支排除原因见调试日志。查看其他数据库的计划时，用 pg_exporter --explain --fail-fast --url=... 直接连接该数据库。

GET /stat

返回主连接选中的采集器的纯文本统计表：

curl -fsS http://127.0.0.1:9630/stat

name                     total      hit        error      skip       metric     ttl/s  duration/ms
pg                       12         0          0          0          15         1      4.231000
pg_db                    12         11         0          0          28         0      0.153000

total 是调用次数，hit 是缓存命中次数，error 是报错次数，skip 是谓词跳过次数。metric 是当前样本数，ttl/s 是取整后的剩余缓存秒数，duration/ms 是最近一次实际执行耗时。比较所有自动发现数据库时，使用 pg_exporter_query_* 指标。

GET /version

返回版本、提交、分支、Go 版本、构建日期、操作系统和架构：

curl -fsS http://127.0.0.1:9630/version

验证部署时，用此端点确认正在运行的二进制版本。