# HTTP API > 指标、健康检查、角色路由、重载、解释、统计与版本端点 --- LLMS index: [llms.txt](/llms.txt) --- `pg_exporter` 在监听端口（默认 `:9630`）上暴露四类 HTTP 端点：指标、健康检查、流量路由与运维管理。全部端点如下： | 端点 | 方法 | 描述 | |----------------------------|----------|---------------------------------------------| | [`/metrics`](#get-metrics) | GET | Prometheus 指标端点（路径可经 `--web.telemetry-path` 修改） | | [`/up`](#健康检查) | GET | 存活检查；别名 `/health`、`/liveness`、`/readiness`、`/read` | | [`/primary`](#流量路由) | GET | 主库检查；别名 `/leader`、`/master`、`/read-write`、`/rw` | | [`/replica`](#流量路由) | GET | 从库检查；别名 `/standby`、`/slave`、`/read-only`、`/ro` | | [`/reload`](#运维端点) | GET/POST | 热重载采集器配置 | | [`/explain`](#运维端点) | GET | 展示各采集器的规划裁决结果 | | [`/stat`](#运维端点) | GET | 各采集器的运行统计（命中/错误/耗时） | | `/version` | GET | 版本与构建信息（文本） | | `/` | GET | 落地页，链接到指标端点 | {.full-width} 健康与路由端点的判定基于后台探测缓存的角色状态（`primary` / `replica` / `down` / `starting` / `unknown`），不会在每次 HTTP 请求时同步查询数据库——探针风暴不会穿透到数据库。 -------- ## 指标端点 ### GET /metrics 暴露所有采集指标的主端点，格式为 Prometheus 格式。 #### 请求 ```bash curl http://localhost:9630/metrics ``` #### 响应 ```prometheus # 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.1",branch="main",revision="",builddate="",goversion="go1.26.5",goos="linux",goarch="amd64"} 1 # ... 更多指标 ``` #### 响应格式 指标遵循 Prometheus 暴露格式： ```text # HELP # TYPE {="",...} ``` #### 自监控指标 除 YAML 采集器定义的业务指标外，`/metrics` 还暴露 exporter 自身的运行指标（可用 `--disable-intro` 关闭 `pg_exporter_*` 部分；前缀随 `--namespace` 变化，pgBouncer 模式下为 `pgbouncer_`）： | 指标 | 标签 | 描述 | |------|------|------| | `pg_up` | — | 能连上目标库为 1，否则为 0 | | `pg_version` | — | `server_version_num` 格式的服务器版本号 | | `pg_in_recovery` | — | 处于恢复模式（从库）为 1 | | `pg_exporter_build_info` | version, revision, ... | 恒为 1，构建信息在标签中 | | `pg_exporter_up` | — | exporter 存活即为 1 | | `pg_exporter_uptime` | — | exporter 启动以来的秒数 | | `pg_exporter_scrape_total_count` / `_error_count` | — | 累计抓取次数 / 失败次数 | | `pg_exporter_scrape_duration` | — | 最近一次抓取耗时（秒） | | `pg_exporter_last_scrape_time` | — | 最近一次抓取的时间戳 | | `pg_exporter_server_scrape_*` | datname | 每个目标库的抓取耗时与成败计数 | | `pg_exporter_query_scrape_duration` | datname, query | 每个采集器的最近执行耗时 | | `pg_exporter_query_scrape_total_count` / `_error_count` | datname, query | 每个采集器的执行 / 失败计数 | | `pg_exporter_query_scrape_hit_count` / `_metric_count` | datname, query | 每个采集器返回的行数 / 产出的指标数 | | `pg_exporter_query_scrape_predicate_skip_count` | datname, query | 因谓词不满足而跳过的次数 | | `pg_exporter_query_cache_ttl` | datname, query | 采集器结果缓存的 TTL | {.full-width} 用 `pg_exporter_query_scrape_duration` 与 `_error_count` 可以直接定位慢采集器与故障采集器，等价于 `/stat` 的机器可读版本。 -------- ## 健康检查 健康检查端点提供多种方式来监控 PG Exporter 和目标数据库的状态。 ### GET /up 简单的存活检查（基于后台探针缓存状态，不会在每次 HTTP 请求时主动探测数据库）。 #### 响应码 | 状态码 | 状态 | 描述 | |--------|------|------| | 200 | OK | 目标可用（primary/replica） | | 503 | Service Unavailable | 目标不可用（down/starting/unknown） | {.full-width} #### 示例 ```bash # 检查服务是否正常 curl -I http://localhost:9630/up HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 ``` ### GET /health `/up` 的别名，行为相同。 ```bash curl http://localhost:9630/health ``` ### GET /liveness 与 GET /readiness 为 Kubernetes 探针习惯提供的路径别名，行为与 `/up` 完全一致（同一处理器）： ```yaml 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）实例。 #### 响应码 | 状态码 | 状态 | 描述 | |-----|---------------------|-------------------------------| | 200 | OK | 服务器是主库且接受写入 | | 404 | Not Found | 服务器不是主库（是从库） | | 503 | Service Unavailable | 服务器不可用（down/starting/unknown） | {.full-width} #### 别名 - `/leader` - `/master` - `/read-write` - `/rw` #### 示例 ```bash # 检查服务器是否为主库 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）实例。 #### 响应码 | 状态码 | 状态 | 描述 | |-----|---------------------|-------------------------------| | 200 | OK | 服务器是从库且处于恢复状态 | | 404 | Not Found | 服务器不是从库（是主库） | | 503 | Service Unavailable | 服务器不可用（down/starting/unknown） | {.full-width} #### 别名 - `/standby` - `/read-only` - `/ro` `/slave` 仍兼容，但建议优先使用 `/replica`。 #### 示例 ```bash # 检查服务器是否为从库 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 检查服务器是否可以处理读流量（主库和从库都可以）。 #### 响应码 | 状态码 | 状态 | 描述 | |-----|---------------------|-------------------------------| | 200 | OK | 服务器正常运行且可以处理读请求 | | 503 | Service Unavailable | 服务器不可用（down/starting/unknown） | {.full-width} #### 示例 ```bash # 检查服务器是否可以处理读请求 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 在不重启导出器的情况下重新加载配置。 #### 请求 ```bash # 推荐 POST curl -X POST http://localhost:9630/reload # 兼容 GET curl http://localhost:9630/reload ``` #### 响应 ```text server reloaded ``` #### 响应码 | 状态码 | 状态 | 描述 | |-----|-----------------------|-----------------------------------| | 200 | OK | 配置重新加载成功 | | 500 | Internal Server Error | 重新加载失败（返回 `fail to reload: ...`） | | 405 | Method Not Allowed | 非 GET/POST 方法（`Allow: GET, POST`） | {.full-width} #### 使用场景 - 更新采集器定义 - 更改查询参数 - 修改缓存 TTL 值 - 添加或移除采集器 ### GET /explain 显示所有已配置采集器的查询执行规划信息。 #### 请求 ```bash curl http://localhost:9630/explain ``` #### 响应 ```text ## # 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 显示运行时统计信息，包括采集器执行时间和成功/失败计数。 #### 请求 ```bash curl http://localhost:9630/stat ``` #### 响应 ```text 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 配置示例 ```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 等方案。