API 参考

pg_exporter 在监听端口（默认 :9630）上暴露四类 HTTP 端点：指标、健康检查、流量路由与运维管理。全部端点如下：

健康与路由端点的判定基于后台探测缓存的角色状态（primary / replica / down / starting / unknown），不会在每次 HTTP 请求时同步查询数据库——探针风暴不会穿透到数据库。

指标端点

GET /metrics

暴露所有采集指标的主端点，格式为 Prometheus 格式。

请求

curl http://localhost: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 140000

# HELP pg_in_recovery server is in recovery mode? 1 for yes 0 for no
# TYPE pg_in_recovery gauge
pg_in_recovery 0

# HELP pg_exporter_build_info A metric with a constant '1' value labeled with version, revision, branch, goversion, builddate, goos, and goarch from which pg_exporter was built.
# TYPE pg_exporter_build_info gauge
pg_exporter_build_info{version="v1.4.0",branch="main",revision="<git-sha>",builddate="<build-date>",goversion="go1.26.5",goos="linux",goarch="amd64"} 1

# ... 更多指标

响应格式

指标遵循 Prometheus 暴露格式：

# HELP <metric_name> <description>
# TYPE <metric_name> <type>
<metric_name>{<label_name>="<label_value>",...} <value> <timestamp>

自监控指标

除 YAML 采集器定义的业务指标外，/metrics 还暴露 exporter 自身的运行指标（可用 --disable-intro 关闭 pg_exporter_* 部分；前缀随 --namespace 变化，pgBouncer 模式下为 pgbouncer_）：

用 pg_exporter_query_scrape_duration 与 _error_count 可以直接定位慢采集器与故障采集器，等价于 /stat 的机器可读版本。

健康检查

健康检查端点提供多种方式来监控 PG Exporter 和目标数据库的状态。

GET /up

简单的存活检查（基于后台探针缓存状态，不会在每次 HTTP 请求时主动探测数据库）。

响应码

示例

# 检查服务是否正常
curl -I http://localhost:9630/up

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

GET /health

/up 的别名，行为相同。

curl http://localhost:9630/health

GET /liveness 与 GET /readiness

为 Kubernetes 探针习惯提供的路径别名，行为与 /up 完全一致（同一处理器）：

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

注意二者语义相同：目标数据库不可达时都会返回 503。若不希望"数据库宕机导致 exporter Pod 被重启"，liveness 探针可以改用 TCP 探测监听端口。

流量路由

这些端点专为负载均衡器和代理设计，根据服务器角色路由流量。

GET /primary

检查服务器是否为主库（primary）实例。

响应码

别名

• /leader
• /master
• /read-write
• /rw

示例

# 检查服务器是否为主库
curl -I http://localhost:9630/primary

# 在 HAProxy 配置中使用
backend pg_primary
  option httpchk GET /primary
  server pg1 10.0.0.1:5432 check port 9630
  server pg2 10.0.0.2:5432 check port 9630

GET /replica

检查服务器是否为从库（standby）实例。

响应码

别名

• /standby
• /read-only
• /ro

/slave 仍兼容，但建议优先使用 /replica。

示例

# 检查服务器是否为从库
curl -I http://localhost:9630/replica

# 在负载均衡器配置中使用
backend pg_replicas
  option httpchk GET /replica
  server pg2 10.0.0.2:5432 check port 9630
  server pg3 10.0.0.3:5432 check port 9630

GET /read

检查服务器是否可以处理读流量（主库和从库都可以）。

响应码

示例

# 检查服务器是否可以处理读请求
curl -I http://localhost:9630/read

# 将读流量路由到任何可用服务器
backend pg_read
  option httpchk GET /read
  server pg1 10.0.0.1:5432 check port 9630
  server pg2 10.0.0.2:5432 check port 9630
  server pg3 10.0.0.3:5432 check port 9630

运维端点

GET /reload / POST /reload

在不重启导出器的情况下重新加载配置。

请求

# 推荐 POST
curl -X POST http://localhost:9630/reload

# 兼容 GET
curl http://localhost:9630/reload

响应

server reloaded

响应码

使用场景

• 更新采集器定义
• 更改查询参数
• 修改缓存 TTL 值
• 添加或移除采集器

GET /explain

显示所有已配置采集器的查询执行规划信息。

请求

curl http://localhost:9630/explain

响应

##
# SYNOPSIS
#       pg.pg_primary_only_*
#
# DESCRIPTION
#       PostgreSQL basic information (on primary)
#
# OPTIONS
#       Tags       [cluster, primary]
#       TTL        1
#       Priority   110
#       Timeout    100ms
#       Fatal      true
#       Version    100000 ~ higher
#       Source     pg_exporter.yml

...

GET /stat

显示运行时统计信息，包括采集器执行时间和成功/失败计数。

请求

curl http://localhost: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         10     0.153000
pg_activity              12         0          1          0          8          0      7.842000
...

此端点对于识别慢速或有问题的采集器非常有用。

在负载均衡器中使用

HAProxy 配置示例

# 主库后端 - 用于写流量
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 backup

# 从库后端 - 用于读流量
backend pg_replicas
  mode tcp
  balance roundrobin
  option httpchk GET /replica
  http-check expect status 200
  server pg2 10.0.0.2:5432 check port 9630 inter 3000 fall 2 rise 2
  server pg3 10.0.0.3:5432 check port 9630 inter 3000 fall 2 rise 2

# 读后端 - 用于任何可以处理读请求的服务器
backend pg_read
  mode tcp
  balance leastconn
  option httpchk GET /read
  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
  server pg3 10.0.0.3:5432 check port 9630 inter 3000 fall 2 rise 2

关于 Nginx

Nginx 开源版不支持基于旁路端口的主动 HTTP 健康检查（health_check 指令是 NGINX Plus 功能），且代理 PostgreSQL 流量需要 stream 模块而非 http 代理。按角色路由 PostgreSQL 流量请优先使用上面的 HAProxy 方案，或 Patroni + vip-manager 等方案。