这是本节的多页打印视图。点击此处打印.

PG Exporter 1.4 中文文档

高级 PostgreSQL 与 PgBouncer 监控指标导出器

1: 快速上手
2: 安装指南
3: 配置参考
4: API 参考
5: 部署指南
6: 发布注记

为 Prometheus / Victoria 打造的极致 PostgreSQL 监控体验：超过 600+ 监控指标、声明式配置 与 动态规划 能力。

功能特性

特性	描述
全指标覆盖	600+ 指标覆盖 PostgreSQL（10-19+）与 pgBouncer（1.8-1.25+）的几乎全部统计视图
声明式采集	每个指标都来自 YAML 采集器定义——SQL 查询加执行条件，可自由增删改，无需改代码
动态规划	按目标的版本、主从角色、已装扩展与标签自动裁决每个采集器是否执行、执行哪个分支
自动发现	自动发现实例内的所有数据库并分别采集，指标以 `datname` 标签区分
健康检查	`/up`、`/primary`、`/replica` 等端点可直接充当负载均衡器探针，实现主从流量路由
智能缓存	采集器级 TTL 缓存把抓取频率与查询频率解耦，探针与抓取风暴不会穿透到数据库
快照直方图	`HISTOGRAM` 列类型将 SQL 快照聚合为经典 Prometheus 直方图分布
扩展感知	原生支持 pg_stat_statements、pg_wait_sampling、citus、timescaledb
生产就绪	在真实环境中经过 6 年以上、12K+ 核心的实战检验

版本信息

当前稳定版本：v1.4.0
默认配置支持：PostgreSQL 10-19+
Legacy 配置支持：PostgreSQL 9.1-9.6（使用 legacy/ 配置包）
PgBouncer 支持：1.8-1.25+

完整版本历史见发布注记。

设计逻辑

pg_exporter 的核心设计取向是「本地优先 + 可声明 + 可演进」：

本地优先连接：未显式指定 URL 时默认使用 postgresql:///?sslmode=disable，适配同机部署场景
声明式采集：指标由 YAML 采集器定义驱动，行为可通过 ttl、timeout、tags、fatal 精细控制
动态规划：运行时依据版本、角色、扩展与标签自动选择合适的采集器分支
可持续运行：默认非阻塞启动，目标不可达时也可先启动 HTTP 端点，待数据库恢复后自动恢复采集
热重载能力：支持 POST/GET /reload 与 SIGHUP 信号重载（非 Windows 额外支持 SIGUSR1）
健康探针分离：健康端点基于后台探测缓存，避免每次探针请求都阻塞数据库
管理面可收敛：/reload、/explain、/stat 会暴露配置与运行态信息，生产环境建议结合 --web.config.file 启用认证/TLS，或仅在内网暴露

快速安装

PG Exporter 提供多种 安装方式，适配各种基础设施：

docker run -d --name pg_exporter -p 9630:9630 -e PG_EXPORTER_URL="postgres://user:pass@host:5432/postgres" pgsty/pg_exporter:latest

# 基于 RPM 的系统
sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
enabled = 1
gpgcheck = 0
module_hotfixes=1
EOF

sudo yum makecache;
sudo yum install -y pg_exporter

sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [trusted=yes] https://repo.pigsty.io/apt/infra generic main
EOF

sudo apt update;
sudo apt install -y pg-exporter

VERSION=$(curl -fsSL https://api.github.com/repos/pgsty/pg_exporter/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')
wget "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/pg_exporter-${VERSION}.linux-amd64.tar.gz"
tar -xf "pg_exporter-${VERSION}.linux-amd64.tar.gz"
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter" /usr/bin/
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter.yml" /etc/pg_exporter.yml

# 从源码构建
git clone https://github.com/pgsty/pg_exporter.git
cd pg_exporter
make build

快速开始

几分钟内即可启动 PG Exporter，参见快速上手：

# 最小可用启动（本地优先默认 URL）
pg_exporter

# 或显式指定目标
PG_EXPORTER_URL='postgres://user:pass@localhost:5432/postgres' pg_exporter

# 访问指标
curl http://localhost:9630/metrics

# 在线重载配置（推荐 POST）
curl -X POST http://localhost:9630/reload

在线演示

通过在线演示环境体验 PG Exporter 的实际效果：https://g.pgsty.com

演示展示了由 PG Exporter 监控的真实 PostgreSQL 集群，包含：

使用 Grafana 的实时指标可视化
多个 PostgreSQL 版本和配置
扩展特定的指标和监控
由 Pigsty 驱动的完整可观测性堆栈

社区与支持

GitHub：源代码、问题反馈与贡献
讨论区：提问与分享经验
Pigsty：包含 PG Exporter 的完整 PostgreSQL 发行版

开源协议

PG Exporter 是基于 Apache License 2.0 许可的开源软件。

1 - 快速上手

十分钟内启动 pg_exporter，并在 Prometheus 中看到 PostgreSQL 指标

本页是一条最短路径：安装 pg_exporter，连上一个 PostgreSQL 实例，确认指标产出，接入 Prometheus。

你需要准备的东西只有两样：一个可访问的 PostgreSQL 10-19+（或 pgBouncer 1.8+）实例，以及在其中创建用户的权限。更老的 PostgreSQL 9.1-9.6 实例请参阅兼容性说明。

第 1 步：安装

Linux amd64 可以直接下载二进制（其他平台与 RPM/DEB/Docker 安装方式见安装指南）：

VERSION=$(curl -fsSL https://api.github.com/repos/pgsty/pg_exporter/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')
wget "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/pg_exporter-${VERSION}.linux-amd64.tar.gz"
tar -xf "pg_exporter-${VERSION}.linux-amd64.tar.gz"
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter" /usr/bin/
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter.yml" /etc/pg_exporter.yml

装好后确认版本：

pg_exporter --version
# pg_exporter v1.4.0 (built with go1.26.5 on linux/amd64)

第 2 步：创建监控用户

在目标 PostgreSQL 上创建一个专用监控用户。PostgreSQL 10+ 内置的 pg_monitor 角色已覆盖默认采集器所需的全部读取权限：

CREATE USER monitor WITH PASSWORD 'S3cret';
GRANT pg_monitor TO monitor;

如果你只是在本机以 postgres 等超级用户试用，可以跳过这一步。

第 3 步：启动并验证

先用 --dry-run 确认配置能正确解析，再正式启动：

export PG_EXPORTER_URL='postgres://monitor:S3cret@localhost:5432/postgres'

pg_exporter --dry-run     # 打印解析后的采集器配置，随即退出
pg_exporter               # 正式启动，默认监听 :9630

如果完全不指定 URL，pg_exporter 会回退到本地优先的默认连接串 postgresql:///?sslmode=disable，适合与 PostgreSQL 同机部署的场景。完整的 URL 来源优先级（--url > PG_EXPORTER_URL > PGURL > PG_EXPORTER_URL_FILE > 默认值）见部署指南。

另开一个终端拉取指标：

curl -s http://localhost:9630/metrics | grep -E '^pg_(up|version|in_recovery) '

你应当看到三个最核心的内置指标：

pg_up 1              # 能连上目标库为 1，否则为 0
pg_version 170000    # server_version_num 格式的版本号
pg_in_recovery 0     # 从库为 1，主库为 0

pg_up 为 1 说明链路已通，其余 600+ 指标（pg_db_*、pg_table_*、pg_wal_*……）都来自 pg_exporter.yml 中的声明式采集器定义。如果 pg_up 为 0，用 pg_exporter --log.level=debug 重启并观察连接错误。

第 4 步：接入 Prometheus

在 prometheus.yml 中添加抓取目标：

scrape_configs:
  - job_name: 'postgresql'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9630']

采集器自带按 ttl 的结果缓存（例如多数实时采集器 ttl: 10）：只要 TTL 小于抓取间隔，每轮抓取都能拿到新数据，同时避免高频抓取压垮数据库。这也是为什么不建议把 scrape_interval 设得比常用 TTL 更短。

到这里就完成了。Grafana 侧可以直接复用 Pigsty 的 PostgreSQL 仪表盘，或到在线演示看实际效果。

常见问题排查

症状	排查方法
`pg_up 0`，连接失败	`pg_exporter --log.level=debug` 查看具体报错；确认 URL、`pg_hba.conf` 与网络可达性
部分指标缺失	`curl localhost:9630/explain` 查看每个采集器的规划结果（版本门槛、标签、谓词是否命中）
某个采集器持续报错	`curl localhost:9630/stat` 查看各采集器的错误计数与耗时
抓取缓慢	在 `/stat` 中找出慢采集器，调大其 `ttl` 或在配置中 `skip: true`

/stat、/explain、/reload 属于管理端点，生产环境建议配合 --web.config.file 启用认证/TLS，或仅在内网开放，详见 API 参考。

下一步

监控 pgBouncer、启用自动发现、配置 systemd/Docker/Kubernetes 生产部署：部署指南
理解与定制采集器（GAUGE/COUNTER/HISTOGRAM、TTL、标签、版本门槛）：配置参考
健康检查与主从流量路由端点（/up、/primary、/replica）：API 参考

2 - 安装指南

如何下载和安装 PG Exporter

pg_exporter 可以通过 Pigsty、YUM/APT 仓库、GitHub 发布包（RPM/DEB/Tarball）、Docker 镜像或源码构建安装，按你的基础设施任选一种即可。

Pigsty

最简单的使用 pg_exporter 的方式是使用 Pigsty，这是一个完整的 PostgreSQL 发行版，内置了基于 pg_exporter、Prometheus 和 Grafana 的可观测性最佳实践。您甚至不需要了解 pg_exporter 的任何细节，它会直接为您提供所有指标和仪表盘面板。

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty;

发布版本

您也可以直接从 GitHub 发布页面下载 pg_exporter 软件包（RPM/DEB/Tarball）：

v1.4.0 发布文件：

类型	文件
DEB (amd64)	pg-exporter_1.4.0-1_amd64.deb
DEB (arm64)	pg-exporter_1.4.0-1_arm64.deb
DEB (ppc64le)	pg-exporter_1.4.0-1_ppc64le.deb
RPM (aarch64)	pg_exporter-1.4.0-1.aarch64.rpm
RPM (x86_64)	pg_exporter-1.4.0-1.x86_64.rpm
RPM (ppc64le)	pg_exporter-1.4.0-1.ppc64le.rpm
Tarball (Linux amd64)	pg_exporter-1.4.0.linux-amd64.tar.gz
Tarball (Linux arm64)	pg_exporter-1.4.0.linux-arm64.tar.gz
Tarball (Linux ppc64le)	pg_exporter-1.4.0.linux-ppc64le.tar.gz
Tarball (macOS amd64)	pg_exporter-1.4.0.darwin-amd64.tar.gz
Tarball (macOS arm64)	pg_exporter-1.4.0.darwin-arm64.tar.gz
Tarball (Windows amd64)	pg_exporter-1.4.0.windows-amd64.tar.gz

您可以直接使用操作系统的包管理器（rpm/dpkg）安装，或者将二进制文件放入 $PATH 中。当前归档文件还会附带 pg_exporter.yml、package/pg_exporter.default、package/pg_exporter.service 与 LICENSE，便于按 tarball 手工部署。

完整 SHA256 校验信息见发布页面中的 checksums.txt；具体版本的校验和也会在发布注记中归档。

软件仓库

pg_exporter 软件包也可以在 pigsty-infra 仓库中获取。您可以将该仓库添加到系统中，然后使用操作系统包管理器安装：

YUM

适用于 RHEL、RockyLinux、CentOS、Alma Linux、OracleLinux 等 EL 系发行版：

sudo tee /etc/yum.repos.d/pigsty-infra.repo > /dev/null <<-'EOF'
[pigsty-infra]
name=Pigsty Infra for $basearch
baseurl=https://repo.pigsty.io/yum/infra/$basearch
enabled = 1
gpgcheck = 0
module_hotfixes=1
EOF

sudo yum makecache;
sudo yum install -y pg_exporter

APT

适用于 Debian、Ubuntu 及兼容的 Linux 发行版：

sudo tee /etc/apt/sources.list.d/pigsty-infra.list > /dev/null <<EOF
deb [trusted=yes] https://repo.pigsty.io/apt/infra generic main
EOF

sudo apt update;
sudo apt install -y pg-exporter

Docker

我们在 Docker Hub 上提供了 amd64 和 arm64 架构的预构建镜像：pgsty/pg_exporter。

# 基本用法
docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://user:password@host:5432/postgres" \
  pgsty/pg_exporter:latest

# 使用自定义配置
docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -v /path/to/pg_exporter.yml:/etc/pg_exporter.yml:ro \
  -e PG_EXPORTER_CONFIG="/etc/pg_exporter.yml" \
  -e PG_EXPORTER_URL="postgres://user:password@host:5432/postgres" \
  pgsty/pg_exporter:latest

# 启用自动发现
docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://user:password@host:5432/postgres" \
  -e PG_EXPORTER_AUTO_DISCOVERY="true" \
  -e PG_EXPORTER_EXCLUDE_DATABASE="template0,template1" \
  pgsty/pg_exporter:latest

注意

当前 Docker 镜像基于 scratch。如果您使用 sslmode=verify-ca 或 verify-full 连接远程 PostgreSQL，请显式挂载 CA 证书（例如 sslrootcert 或系统 CA bundle），否则 TLS 校验可能无法完成。

兼容性

当前默认配置支持 PostgreSQL 10-19+。对于 EOL 旧版本 PostgreSQL，可以使用仓库内置的 legacy/ 配置包进行兼容监控。

PostgreSQL 版本	支持状态
10 ~ 19+	✅ 完全支持（默认配置）
9.1 ~ 9.6	⚠️ 使用 `legacy/pg_exporter.yml`
9.0 及更早	❌ 不支持

启用 Legacy 配置示例：

make conf9
PG_EXPORTER_CONFIG=legacy/pg_exporter.yml pg_exporter

pg_exporter 支持 pgBouncer 1.8+（v1.8 是第一个支持 SHOW 命令的版本）。

pgBouncer 版本	支持状态
1.8.x ~ 1.25+	✅ 完全支持
1.8.x 之前	⚠️ 无指标

3 - 配置参考

PG Exporter 的配置选项与采集器定义

pg_exporter 的所有业务指标都由 YAML 采集器（Collector）定义驱动：每个采集器就是一条 SQL 查询，外加它的执行条件（版本、角色、标签、谓词）与运行控制（缓存、超时）。本页是采集器定义的完整参考。

配置可以是单个 YAML 文件（如默认的 pg_exporter.yml），也可以是包含多个 YAML 文件的目录——官方默认配置包正是由 config/ 目录下 58 个定义文件合并而来。

配置加载

PG Exporter 按以下顺序搜索配置：

命令行参数：--config=/path/to/config
环境变量：PG_EXPORTER_CONFIG=/path/to/config
当前目录：./pg_exporter.yml
系统配置文件：/etc/pg_exporter.yml
系统配置目录：/etc/pg_exporter/

目录模式说明：

仅加载该目录下的 .yml / .yaml 文件（非递归）
按文件名字典序合并；同名采集器以后加载者覆盖先前定义
如果目录中有 YAML 文件但全部解析失败，导出器会直接返回错误而不是静默忽略

采集器结构

每个采集器是 YAML 配置中的一个顶级对象，具有唯一名称和多种属性：

collector_branch_name:           # 此采集器的唯一标识符
  name: metric_namespace         # 指标前缀（默认为分支名称）
  desc: "采集器描述"             # 人类可读的描述
  query: |                       # 要执行的 SQL 查询
    SELECT column1, column2
    FROM table

  # 执行控制
  ttl: 10                        # 缓存生存时间（秒）
  timeout: 0.1                   # 查询超时（秒）
  fatal: false                   # 如果为 true，失败将导致整个抓取失败
  skip: false                    # 如果为 true，禁用此采集器

  # 版本兼容性
  min_version: 100000            # 最小 PostgreSQL 版本（包含）
  max_version: 999999            # 最大 PostgreSQL 版本（不包含）

  # 执行标签
  tags: [cluster, primary]       # 执行条件

  # 谓词查询（可选）
  predicate_queries:
    - name: "check_function"
      predicate_query: |
        SELECT EXISTS (...)

  # 指标定义
  metrics:
    - column_name:
        usage: GAUGE             # GAUGE、COUNTER、HISTOGRAM、LABEL 或 DISCARD
        rename: metric_name      # 可选：重命名指标
        description: "帮助文本"   # 指标描述
        default: 0               # NULL 时的默认值
        scale: 1000              # 值的缩放因子
        bucket: [1, 10, 100]     # HISTOGRAM 列的桶上界（严格递增，自动追加 +Inf）

配置校验约束：

每个 metrics 列表项必须且只能定义一个列映射
每个采集器至少要有一个 GAUGE / COUNTER / HISTOGRAM 列
usage 仅支持 GAUGE / COUNTER / HISTOGRAM / LABEL / DISCARD
HISTOGRAM 列必须定义 bucket：有限、严格递增的桶上界列表，+Inf 桶自动追加
指标名、标签名会在加载阶段进行 Prometheus 规则校验，非法配置会直接报错
常量标签会在加载阶段检查冲突；它们不能与查询标签重名，也不能与内置动态标签 datname / query 冲突；配置了 HISTOGRAM 采集器时，le 为保留标签，不能用作常量标签
如果使用单行内联 metrics 写法，description 建议始终使用双引号包裹，避免 YAML 歧义

核心配置元素

采集器分支名称

顶级键在整个配置中唯一标识一个采集器：

pg_stat_database:  # 必须唯一
  name: pg_db      # 实际的指标命名空间

查询定义

检索指标的 SQL 查询：

query: |
  SELECT
    datname,
    numbackends,
    xact_commit,
    xact_rollback,
    blks_read,
    blks_hit
  FROM pg_stat_database
  WHERE datname NOT IN ('template0', 'template1')

指标类型

查询结果中的每一列必须映射到一个指标类型：

用途	描述	示例
`GAUGE`	可上下波动的瞬时值	当前连接数
`COUNTER`	只增不减的累计值	总事务数
`HISTOGRAM`	快照直方图，派生 `_bucket` / `_count` / `_sum` 序列	事务年龄分布
`LABEL`	用作 Prometheus 标签	数据库名称
`DISCARD`	忽略此列	内部值

直方图列（HISTOGRAM）

v1.4.0 引入 HISTOGRAM 列类型：查询返回的每一行都作为一次观测，按标签组聚合为经典 Prometheus 直方图快照，派生 <name>_bucket（含 le 标签与 +Inf 桶）、<name>_count、 <name>_sum 三族序列：

pg_xact_age:
  name: pg_xact_age
  desc: "开放事务年龄分布直方图"
  query: |
    SELECT datname,
           greatest(0, extract(epoch FROM now() - xact_start)) AS seconds
    FROM pg_stat_activity
    WHERE pid <> pg_backend_pid() AND backend_type = 'client backend'
      AND datname IS NOT NULL AND xact_start IS NOT NULL;
  ttl: 10
  tags: [cluster]
  metrics:
    - datname: {usage: LABEL, description: "数据库名称"}
    - seconds:
        usage: HISTOGRAM
        bucket: [1, 3, 10, 30, 100, 300, 1000, 3000, 10000, 30000, 100000]
        description: "开放事务年龄快照（秒）"

使用注意：

这是快照直方图：每次抓取重建整个分布，桶计数可增可减，语义上更接近 Gauge。 histogram_quantile() 可以直接使用，但对 _count / _sum 使用 rate() / increase() 没有意义
SQL NULL 默认忽略不计入观测；显式配置 default 时按默认值计入
scale 在分桶前应用于观测值；与标量列一致，时间戳与布尔值不受 scale 影响
默认配置包中的 pg_xact_age 采集器即为参考实现

缓存控制（TTL）

ttl 参数控制结果缓存：

# 快速查询 - 最小缓存
pg_stat_activity:
  ttl: 1  # 缓存 1 秒

# 昂贵查询 - 较长缓存
pg_table_bloat:
  ttl: 3600  # 缓存 1 小时

最佳实践：

将 TTL 设置为小于您的抓取间隔
对昂贵的查询使用较长的 TTL
TTL 为 0 表示禁用缓存

超时控制

防止查询运行时间过长：

timeout: 0.1   # 默认 100ms
timeout: 1.0   # 复杂查询使用 1 秒
timeout: -1    # 禁用超时（不推荐）

版本兼容性

控制哪些 PostgreSQL 版本可以运行此采集器：

min_version: 100000  # PostgreSQL 10.0+
max_version: 140000  # 低于 PostgreSQL 14.0

版本号使用 PostgreSQL 内部 server_version_num 规则：

100000 表示 10.0
130200 表示 13.2
160100 表示 16.1
190000 表示 19.0
90600 表示 9.6（Legacy 配置场景）

执行模型

理解一个采集器从定义到产出指标的完整路径，有助于回答"为什么这个指标没出来"：

规划（建立连接或热重载时）：对每个采集器分支依次检查——目标类型（PostgreSQL / pgBouncer）、min_version / max_version 版本门槛、tags 与服务器角色及 exporter 标签的匹配、skip 开关。未通过的分支不会安装到该目标上。curl localhost:9630/explain 展示的正是这一步的裁决结果。
抓取（每次 /metrics 请求）：对已安装的采集器——缓存在 ttl 内则直接返回缓存结果；否则先执行 predicate_queries（任一返回假则本轮跳过，pg_exporter_query_scrape_predicate_skip_count 计数），再在 timeout 限制下执行主查询，结果转为指标并写入缓存。
失败语义：普通采集器失败只影响自身（pg_exporter_query_scrape_error_count 上升，本轮缺失该组指标）；标记 fatal: true 的采集器失败会使整次服务器抓取被判定为失败。

标签系统

标签控制采集器的执行时机和位置：

内置标签

标签	描述
`cluster`	每个 PostgreSQL 集群执行一次
`primary` / `master`	仅在主服务器上执行
`standby` / `replica`	仅在从服务器上执行
`pgbouncer`	仅用于 pgBouncer 连接

前缀标签

前缀	示例	描述
`dbname:`	`dbname:postgres`	仅在特定数据库上执行
`username:`	`username:monitor`	仅使用特定用户时执行
`extension:`	`extension:pg_stat_statements`	仅当扩展已安装时执行
`schema:`	`schema:public`	仅当模式存在时执行
`not:`	`not:slow`	当导出器没有该标签时执行

自定义标签

向导出器传递自定义标签：

pg_exporter --tag="production,critical"

然后在配置中使用：

expensive_metrics:
  tags: [critical]  # 仅在有 'critical' 标签时运行

谓词查询

在执行主查询之前进行条件检查：

predicate_queries:
  - name: "检查 pg_stat_statements"
    predicate_query: |
      SELECT EXISTS (
        SELECT 1 FROM pg_extension
        WHERE extname = 'pg_stat_statements'
      )

只有当所有谓词返回 true 时，主查询才会执行。

指标定义

基本定义

metrics:
  - numbackends:
      usage: GAUGE
      description: "已连接的后端进程数"

高级选项

metrics:
  - checkpoint_write_time:
      usage: COUNTER
      rename: write_time        # 重命名指标
      scale: 0.001              # 将毫秒转换为秒
      default: 0                # NULL 时使用 0
      description: "检查点写入时间（秒）"

采集器组织

PG Exporter 自带预先组织好的采集器：

范围	类别	描述
0xx	文档	示例和文档
1xx	基础	服务器信息、设置、元数据
2xx	复制	复制、槽位、接收器
3xx	持久化	I/O、检查点、WAL
4xx	活动	连接、锁、查询
5xx	进度	Vacuum、索引创建进度
6xx	数据库	每数据库统计
7xx	对象	表、索引、函数
8xx	可选	昂贵/可选指标
9xx	pgBouncer	连接池指标
10xx+	扩展	扩展特定指标

实际示例

简单的 Gauge 采集器

pg_connections:
  desc: "当前数据库连接"
  query: |
    SELECT
      count(*) as total,
      count(*) FILTER (WHERE state = 'active') as active,
      count(*) FILTER (WHERE state = 'idle') as idle,
      count(*) FILTER (WHERE state = 'idle in transaction') as idle_in_transaction
    FROM pg_stat_activity
    WHERE pid != pg_backend_pid()
  ttl: 1
  metrics:
    - total: {usage: GAUGE, description: "总连接数"}
    - active: {usage: GAUGE, description: "活跃连接数"}
    - idle: {usage: GAUGE, description: "空闲连接数"}
    - idle_in_transaction: {usage: GAUGE, description: "事务中空闲连接数"}

带标签的 Counter

pg_table_stats:
  desc: "表统计信息"
  query: |
    SELECT
      schemaname,
      tablename,
      n_tup_ins,
      n_tup_upd,
      n_tup_del,
      n_live_tup,
      n_dead_tup
    FROM pg_stat_user_tables
  ttl: 10
  metrics:
    - schemaname: {usage: LABEL}
    - tablename: {usage: LABEL}
    - n_tup_ins: {usage: COUNTER, description: "插入的元组数"}
    - n_tup_upd: {usage: COUNTER, description: "更新的元组数"}
    - n_tup_del: {usage: COUNTER, description: "删除的元组数"}
    - n_live_tup: {usage: GAUGE, description: "活跃元组数"}
    - n_dead_tup: {usage: GAUGE, description: "死亡元组数"}

版本特定采集器

pg_wal_stats:
  desc: "WAL 统计信息（PG 14+）"
  min_version: 140000
  query: |
    SELECT
      wal_records,
      wal_bytes,
      wal_buffers_full,
      wal_write_time,
      wal_sync_time
    FROM pg_stat_wal
  ttl: 10
  tags: [cluster]
  metrics:
    - wal_records: {usage: COUNTER}
    - wal_bytes: {usage: COUNTER}
    - wal_buffers_full: {usage: COUNTER}
    - wal_write_time: {usage: COUNTER, scale: 0.001}
    - wal_sync_time: {usage: COUNTER, scale: 0.001}

扩展依赖采集器

pg_stat_statements_metrics:
  desc: "查询性能统计"
  tags: [extension:pg_stat_statements]
  query: |
    SELECT
      sum(calls) as total_calls,
      sum(total_exec_time) as total_time,
      sum(mean_exec_time * calls) / sum(calls) as mean_time
    FROM pg_stat_statements
  ttl: 60
  metrics:
    - total_calls: {usage: COUNTER}
    - total_time: {usage: COUNTER, scale: 0.001}
    - mean_time: {usage: GAUGE, scale: 0.001}

自定义采集器

创建自己的指标

# /etc/pg_exporter/custom_metrics.yml
app_metrics:
  desc: "应用特定指标"
  query: |
    SELECT
      (SELECT count(*) FROM users WHERE active = true) as active_users,
      (SELECT count(*) FROM orders WHERE created_at > NOW() - '1 hour'::interval) as recent_orders,
      (SELECT avg(processing_time) FROM jobs WHERE completed_at > NOW() - '5 minutes'::interval) as avg_job_time
  ttl: 30
  metrics:
    - active_users: {usage: GAUGE, description: "当前活跃用户数"}
    - recent_orders: {usage: GAUGE, description: "最近一小时的订单数"}
    - avg_job_time: {usage: GAUGE, description: "平均作业处理时间"}

测试您的采集器：

pg_exporter --explain --config=/etc/pg_exporter/

条件指标

使用谓词查询实现条件指标：

partition_metrics:
  desc: "分区表指标"
  predicate_queries:
    - name: "检查是否使用了分区"
      predicate_query: |
        SELECT EXISTS (
          SELECT 1 FROM pg_class
          WHERE relkind = 'p' LIMIT 1
        )
  query: |
    SELECT
      parent.relname as parent_table,
      count(*) as partition_count,
      sum(pg_relation_size(child.oid)) as total_size
    FROM pg_inherits
    JOIN pg_class parent ON parent.oid = pg_inherits.inhparent
    JOIN pg_class child ON child.oid = pg_inherits.inhrelid
    WHERE parent.relkind = 'p'
    GROUP BY parent.relname
  ttl: 300
  metrics:
    - parent_table: {usage: LABEL}
    - partition_count: {usage: GAUGE}
    - total_size: {usage: GAUGE}

性能优化

查询优化技巧

使用适当的 TTL 值：
- 快速查询：1-10 秒
- 中等查询：10-60 秒
- 昂贵查询：300-3600 秒
设置合理的超时：
- 默认：100ms
- 复杂查询：500ms-1s
- 生产环境中不要禁用超时

使用集群级标签：

tags: [cluster]  # 每集群运行一次，而不是每数据库

禁用昂贵的采集器：

pg_table_bloat:
  skip: true  # 如果不需要则禁用

监控采集器性能

检查采集器执行统计：

# 查看采集器统计（命中/错误/跳过计数与耗时）
curl http://localhost:9630/stat

# 按 datname/query 维度查看每个采集器的耗时与错误
curl -s http://localhost:9630/metrics | grep -E 'pg_exporter_query_scrape_(duration|error_count)'

配置故障排查

验证配置

# 干运行 - 显示解析后的配置
pg_exporter --dry-run

# 解释 - 显示计划的查询
pg_exporter --explain

常见问题

问题	解决方案
指标缺失	检查标签和版本兼容性
抓取缓慢	增加 TTL、添加超时、禁用昂贵查询
内存使用高	减少结果集大小，使用 LIMIT
权限错误	验证监控用户的查询权限

调试日志

启用调试日志进行故障排查：

pg_exporter --log.level=debug

4 - API 参考

PG Exporter 的 HTTP API 端点参考

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

端点	方法	描述
`/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	落地页，链接到指标端点

健康与路由端点的判定基于后台探测缓存的角色状态（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_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

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

健康检查

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

GET /up

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

响应码

状态码	状态	描述
200	OK	目标可用（primary/replica）
503	Service Unavailable	目标不可用（down/starting/unknown）

示例

# 检查服务是否正常
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）实例。

响应码

状态码	状态	描述
200	OK	服务器是主库且接受写入
404	Not Found	服务器不是主库（是从库）
503	Service Unavailable	服务器不可用（down/starting/unknown）

别名

/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）实例。

响应码

状态码	状态	描述
200	OK	服务器是从库且处于恢复状态
404	Not Found	服务器不是从库（是主库）
503	Service Unavailable	服务器不可用（down/starting/unknown）

别名

/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

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

响应码

状态码	状态	描述
200	OK	服务器正常运行且可以处理读请求
503	Service Unavailable	服务器不可用（down/starting/unknown）

示例

# 检查服务器是否可以处理读请求
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

响应码

状态码	状态	描述
200	OK	配置重新加载成功
500	Internal Server Error	重新加载失败（返回 `fail to reload: ...`）
405	Method Not Allowed	非 GET/POST 方法（`Allow: GET, POST`）

使用场景

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

注意

重载会刷新采集器配置和查询计划；如需修改进程级参数（例如监听地址、CLI 参数），仍需重启导出器。

安全建议

/reload、/explain、/stat 都属于管理端点。若 exporter 不仅在本机或可信内网使用，建议通过 --web.config.file 启用认证/TLS，或在反向代理 / 防火墙层限制访问。

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 等方案。

5 - 部署指南

生产环境部署：连接与凭据、systemd / Docker / Kubernetes、自动发现与告警

本页覆盖把 pg_exporter 放进生产环境要做的事：进程参数与环境变量、监控用户与凭据管理、systemd / Docker / Kubernetes 三种部署形态、pgBouncer 与自动发现，以及 Prometheus 侧的抓取与告警配置。

进程级配置有两个来源，优先级从高到低：

命令行参数（--url、--config 等）
环境变量（每个参数都有对应的 PG_EXPORTER_* 变量）

指标采集行为则完全由 YAML 采集器定义驱动（默认 /etc/pg_exporter.yml，亦可指向配置目录），详见配置参考。

命令行参数

pg_exporter \
  --url="postgres://monitor:S3cret@localhost:5432/postgres" \
  --config="/etc/pg_exporter.yml" \
  --web.listen-address=":9630" \
  --auto-discovery \
  --log.level="info"

pg_exporter --help 的完整参数列表：

Flags:
  -h, --[no-]help                显示上下文相关帮助（也可尝试 --help-long 和 --help-man）。
  -u, --url=URL                  postgres 目标 URL
  -c, --config=CONFIG            配置目录或文件路径
      --web.listen-address=:9630 ...
                                 暴露指标和 Web 界面的地址。可重复指定多个地址。示例：`:9100` 或 `[::1]:9100` 用于 http，`vsock://:9100` 用于 vsock
      --web.config.file=""       可启用 TLS 或认证的配置文件路径。参见：https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md
  -l, --label=""                 常量标签：逗号分隔的 label=value 项 ($PG_EXPORTER_LABEL)
  -t, --tag=""                   标签，逗号分隔的服务器标签 ($PG_EXPORTER_TAG)
  -C, --[no-]disable-cache       强制不使用缓存 ($PG_EXPORTER_DISABLE_CACHE)
  -m, --[no-]disable-intro       禁用内部/导出器自监控指标（仅暴露查询指标）($PG_EXPORTER_DISABLE_INTRO)
  -a, --[no-]auto-discovery      自动抓取目标服务器上的所有数据库 ($PG_EXPORTER_AUTO_DISCOVERY)
  -x, --exclude-database="template0,template1,postgres"
                                 启用自动发现时排除的数据库 ($PG_EXPORTER_EXCLUDE_DATABASE)
  -i, --include-database=""      启用自动发现时包含的数据库 ($PG_EXPORTER_INCLUDE_DATABASE)
  -n, --namespace=""             内置指标的前缀，默认为 (pg|pgbouncer) ($PG_EXPORTER_NAMESPACE)
  -f, --[no-]fail-fast           启动时立即失败而不是等待 ($PG_EXPORTER_FAIL_FAST)
  -T, --connect-timeout=100      连接超时（毫秒），默认 100 ($PG_EXPORTER_CONNECT_TIMEOUT)
  -P, --web.telemetry-path="/metrics"
                                 暴露指标的 URL 路径 ($PG_EXPORTER_TELEMETRY_PATH)
  -D, --[no-]dry-run             干运行并打印原始配置
  -E, --[no-]explain             解释服务器计划的查询
      --log.level="info"         日志级别：debug|info|warn|error
      --log.format="logfmt"      日志格式：logfmt|json
      --[no-]version             显示应用程序版本

两点部署相关的行为说明：

启动策略：默认非阻塞启动——目标库暂时不可达时，HTTP 端点照常拉起，后台持续探测直到恢复；如果希望"连不上就失败退出"（例如交由 systemd/编排器重启决策），设置 --fail-fast。
telemetry path 校验：自 v1.4.0 起，--web.telemetry-path 在启动时严格校验，空路径、与内置端点冲突、或 //metrics 这类永远无法命中的非规范路径会直接报错退出。

连接 URL 的来源

连接串按以下优先级解析，取第一个非空值：

--url / -u 命令行参数
PG_EXPORTER_URL 环境变量
PGURL 环境变量
PG_EXPORTER_URL_FILE 指向文件的内容（适合容器 Secret 挂载）
默认值 postgresql:///?sslmode=disable（本地优先，适配同机部署）

URL 中未指定 sslmode 时会自动补 sslmode=disable。另外，PGSERVICE / PGSERVICEFILE 等 libpq 服务文件环境变量会在启动时被清除并记录日志——服务文件可能覆盖显式指定的连接目标，pg_exporter 要求"日志里宣告的 URL 就是实际连接的 URL"。

监控用户与凭据

创建监控用户

CREATE ROLE monitor WITH LOGIN PASSWORD 'S3cret' CONNECTION LIMIT 5;
GRANT pg_monitor TO monitor;   -- PostgreSQL 10+ 内置监控角色，覆盖默认采集器全部所需权限

CONNECTION LIMIT 建议保留：exporter 正常只占用一至数个连接（自动发现时每库一个），限流可以防止配置错误时耗尽连接。

使用 .pgpass 管理密码

把密码从 URL 中拿掉，交给 libpq 的 .pgpass 机制：

# 以运行 exporter 的操作系统用户身份创建
echo "localhost:5432:*:monitor:S3cret" > ~/.pgpass
chmod 600 ~/.pgpass

# URL 中不再携带密码
PG_EXPORTER_URL='postgres://monitor@localhost:5432/postgres'

RPM/DEB 包安装场景

包安装的服务以 prometheus 系统用户运行。自 v1.4.0 起该用户的 HOME 指向 /var/lib/prometheus（libpq 查找 ~/.pgpass 的位置），但安装包不会创建这个目录。使用 .pgpass 前请先执行： install -d -o prometheus -g prometheus /var/lib/prometheus

数据库连接 TLS

PG_EXPORTER_URL='postgres://monitor:S3cret@db.example.com:5432/postgres?sslmode=verify-full&sslrootcert=/etc/pki/ca.crt'

HTTP 端口侧的保护

/metrics 之外，/reload、/explain、/stat 属于管理端点：能访问该端口的任何人都可以读取配置与运行态信息、触发重载。如果 exporter 暴露在共享网络中，请通过 --web.config.file（exporter-toolkit web 配置）启用 TLS/Basic Auth，或在防火墙/反向代理层限制来源。

Systemd 部署（RPM/DEB 包）

RPM/DEB 包已内置服务单元与环境文件，安装后仅需修改环境文件并启动：

# /usr/lib/systemd/system/pg_exporter.service
[Unit]
Description=Prometheus exporter for PostgreSQL/Pgbouncer server metrics
Documentation=https://pigsty.io/docs/pg_exporter
After=network.target

[Service]
EnvironmentFile=-/etc/default/pg_exporter
User=prometheus
ExecStart=/usr/bin/pg_exporter $PG_EXPORTER_OPTS
Restart=on-failure

[Install]
WantedBy=multi-user.target

环境文件 /etc/default/pg_exporter（包默认值）：

PG_EXPORTER_URL='postgres://:5432/postgres?sslmode=disable'
PG_EXPORTER_CONFIG=/etc/pg_exporter.yml
PG_EXPORTER_LABEL=""
PG_EXPORTER_TAG=""
PG_EXPORTER_DISABLE_CACHE=false
PG_EXPORTER_AUTO_DISCOVERY=true
PG_EXPORTER_EXCLUDE_DATABASE="template0,template1,postgres"
PG_EXPORTER_INCLUDE_DATABASE=""
PG_EXPORTER_NAMESPACE="pg"
PG_EXPORTER_FAIL_FAST=false
PG_EXPORTER_CONNECT_TIMEOUT=100
PG_EXPORTER_TELEMETRY_PATH="/metrics"
PG_EXPORTER_OPTS='--log.level=info'

所有命令行参数都有对应环境变量，需要时（如 PG_EXPORTER_DISABLE_INTRO）直接在此追加即可。该文件以 noreplace 方式打包，升级不会覆盖你的修改。

常用管理命令：

sudo systemctl enable --now pg_exporter    # 启动并设置开机自启
sudo systemctl status pg_exporter          # 查看状态
journalctl -u pg_exporter -f               # 跟踪日志
curl -X POST localhost:9630/reload         # 热重载采集器配置（无需重启）

Docker 部署

docker run -d \
  --name pg_exporter \
  --restart unless-stopped \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://monitor:S3cret@host:5432/postgres" \
  pgsty/pg_exporter:latest

Docker Compose：

services:
  pg_exporter:
    image: pgsty/pg_exporter:latest
    container_name: pg_exporter
    restart: unless-stopped
    ports:
      - "9630:9630"
    environment:
      - PG_EXPORTER_URL=postgres://monitor:S3cret@postgres:5432/postgres
    volumes:
      - ./pg_exporter.yml:/etc/pg_exporter.yml:ro   # 可选：自定义采集器配置
    depends_on:
      - postgres

注意

官方镜像基于 scratch，不含系统 CA 证书。若以 sslmode=verify-ca / verify-full 连接远程 PostgreSQL，请显式挂载 CA 证书并通过 sslrootcert 指定，否则 TLS 校验无法完成。

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pg-exporter
  labels: { app: pg-exporter }
spec:
  replicas: 1
  selector:
    matchLabels: { app: pg-exporter }
  template:
    metadata:
      labels: { app: pg-exporter }
    spec:
      containers:
      - name: pg-exporter
        image: pgsty/pg_exporter:latest
        ports:
        - containerPort: 9630
        env:
        - name: PG_EXPORTER_URL
          valueFrom:
            secretKeyRef:
              name: pg-credentials
              key: connection-url
        livenessProbe:
          httpGet: { path: /liveness, port: 9630 }
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet: { path: /readiness, port: 9630 }
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests: { cpu: 100m, memory: 128Mi }
          limits: { cpu: 200m, memory: 256Mi }
---
apiVersion: v1
kind: Service
metadata:
  name: pg-exporter
  labels: { app: pg-exporter }
spec:
  ports:
  - { port: 9630, targetPort: 9630, name: metrics }
  selector: { app: pg-exporter }

也可以用 PG_EXPORTER_URL_FILE 指向 Secret 挂载出的文件，避免把连接串放进环境变量。

自动发现

自动发现（默认启用）让一个 exporter 实例监控目标 PostgreSQL 中的所有数据库：

pg_exporter --auto-discovery \
  --exclude-database="template0,template1,postgres" \  # 默认排除清单
  --include-database=""                                # 设置后改为白名单模式

行为规则：

集群级采集器（tags: [cluster]）只在主连接上执行一次
数据库级采集器在每个被发现的库上分别执行，指标带 datname 标签区分
新建/删除的数据库会在后续规划周期被自动纳入/移除

监控 pgBouncer

将 URL 的数据库名设为 pgbouncer 即可切换到 pgBouncer 模式（以此触发自动检测）：

PG_EXPORTER_URL='postgres://stats_user:S3cret@localhost:6432/pgbouncer' pg_exporter

pgBouncer 模式下，exporter 使用 pgbouncer 指标前缀，只执行 pgBouncer 专属采集器（SHOW STATS / SHOW POOLS 等）。通常的做法是为 PostgreSQL 和 pgBouncer 各跑一个 exporter 实例（不同端口）。

Prometheus 抓取与告警

抓取配置

scrape_configs:
  - job_name: 'postgresql'
    scrape_interval: 15s
    static_configs:
      - targets: ['pg-1:9630', 'pg-2:9630', 'pg-3:9630']

Kubernetes 服务发现：

scrape_configs:
  - job_name: 'postgresql'
    kubernetes_sd_configs:
      - role: pod
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app]
        regex: pg-exporter
        action: keep
      - source_labels: [__meta_kubernetes_pod_ip]
        target_label: __address__
        replacement: ${1}:9630

抓取间隔建议不小于常用采集器的 ttl（默认配置多为 10 秒）：TTL 缓存保证了更高频的抓取只会拿到缓存结果，徒增开销。

告警规则

以下规则全部基于真实存在的指标：

groups:
  - name: pg_exporter
    rules:
      # 导出器进程失联
      - alert: PgExporterDown
        expr: up{job="postgresql"} == 0
        for: 1m
        labels: { severity: critical }
        annotations:
          summary: "pg_exporter 宕机 ({{ $labels.instance }})"

      # 导出器存活但连不上数据库
      - alert: PostgreSQLDown
        expr: pg_up == 0
        for: 1m
        labels: { severity: critical }
        annotations:
          summary: "PostgreSQL 连接失败 ({{ $labels.instance }})"

      # 整体抓取耗时异常（单位：秒）
      - alert: PgExporterSlowScrape
        expr: pg_exporter_scrape_duration > 10
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "pg_exporter 抓取缓慢 ({{ $labels.instance }})"

      # 某个采集器持续报错（按 datname/query 定位）
      - alert: PgExporterQueryError
        expr: increase(pg_exporter_query_scrape_error_count[10m]) > 0
        for: 10m
        labels: { severity: warning }
        annotations:
          summary: "采集器 {{ $labels.query }} 在 {{ $labels.datname }} 上持续报错"

基于角色的流量路由

/primary、/replica、/read 等健康检查端点可以直接充当 HAProxy 等负载均衡器的健康检查探针，实现主从读写分离。端点语义与完整的 HAProxy 配置示例见 API 参考。

注意：Nginx 开源版不支持基于旁路端口的主动 HTTP 健康检查（health_check 为 NGINX Plus 功能），按角色路由 PostgreSQL 流量请优先使用 HAProxy，或 Patroni + vip-manager 等方案。

6 - 发布注记

PG Exporter 版本发布历史

pg_exporter 的最新稳定版本是 v1.4.0

版本	日期	摘要	GitHub
v1.4.0	2026-07-18	快照直方图支持，新增 pg_xact_age 采集器，HTTP 路由加固	v1.4.0
v1.3.0	2026-06-24	PostgreSQL 19 支持，新增 PG19 采集器与分支	v1.3.0
v1.2.2	2026-04-14	例行更新到 Go 1.26.2，无功能改动	v1.2.2
v1.2.1	2026-03-21	配置样式统一，Go 1.26.1 更新	v1.2.1
v1.2.0	2026-02-12	热重载与非阻塞启动，新增 PG9.1-9.6 legacy 支持	v1.2.0
v1.1.2	2026-01-16	修复 pg_timeline 配置问题，使用最新依赖构建	v1.1.2
v1.1.1	2025-12-30	新增 pg_timeline 采集器，pg_sub_16 分支，Bug 修复	v1.1.1
v1.1.0	2025-12-15	更新默认指标采集器，升级到 Go 1.25.5	v1.1.0
v1.0.3	2025-11-20	例行更新到 1.25.4，修复不支持的 libpq 环境变量	v1.0.3
v1.0.2	2025-08-14	使用 goreleaser 构建更多操作系统架构	v1.0.2
v1.0.1	2025-07-17	DockerHub 镜像，Go 1.24.5，禁用 pg_tsdb_hypertable	v1.0.1
v1.0.0	2025-05-06	PostgreSQL 18 支持，新增 WAL/检查点/I/O 指标	v1.0.0
v0.9.0	2025-04-26	TimescaleDB、Citus、pg_wait_sampling 采集器	v0.9.0
v0.8.1	2025-02-14	依赖更新，Docker 镜像标签	v0.8.1
v0.8.0	2025-02-14	PgBouncer 1.24 支持，Go 1.24，日志重构	v0.8.0
v0.7.1	2024-12-29	例行更新，支持 Reader 配置	v0.7.1
v0.7.0	2024-08-13	PostgreSQL 17 支持，谓词查询功能	v0.7.0
v0.6.0	2023-10-18	PostgreSQL 16 支持，ARM64 包，安全修复	v0.6.0
v0.5.0	2022-04-27	RPM/DEB 构建，列缩放，指标增强	v0.5.0
v0.4.1	2022-03-08	采集器更新，connect-timeout 参数	v0.4.1
v0.4.0	2021-07-12	PostgreSQL 14 支持，自动发现功能	v0.4.0
v0.3.2	2021-02-01	Shadow DSN 修复，文档更新	v0.3.2
v0.3.1	2020-12-04	旧版 PostgreSQL 配置修复	v0.3.1
v0.3.0	2020-10-29	PostgreSQL 13 支持，REST API，虚拟服务器	v0.3.0
v0.2.0	2020-03-21	YUM 包，配置重载支持	v0.2.0
v0.1.2	2020-02-20	动态配置重载，批量模式	v0.1.2
v0.1.1	2020-01-10	启动挂起 Bug 修复	v0.1.1
v0.1.0	2020-01-08	首个稳定版本	v0.1.0
v0.0.4	2019-12-20	生产环境测试版本	v0.0.4
v0.0.3	2019-12-14	生产环境测试	v0.0.3
v0.0.2	2019-12-09	早期测试版本	v0.0.2
v0.0.1	2019-12-06	初始版本，支持 PgBouncer 模式	v0.0.1

v1.4.0

v1.4.0 引入快照直方图（Snapshot Histogram）指标类型与新的 pg_xact_age 事务年龄采集器，并对 HTTP 路由、打包与构建链进行了一轮系统性加固。

新功能：

新增 HISTOGRAM 列类型：SQL 查询快照可按标签组直接聚合为经典 Prometheus 直方图，派生 _bucket / _count / _sum 三族序列；桶边界在配置加载阶段严格校验（有限、严格递增，自动追加 +Inf），le 成为保留标签，热重载安全
新增 pg_xact_age 采集器：以直方图暴露开放事务年龄（pg_xact_age_seconds）与事务中空闲年龄（pg_xact_age_idle_seconds）的分布，集群级采集，仅统计客户端后端，TTL 10 秒
默认配置包从 57 个定义文件增加到 58 个；pg_xact_age 编号 0450，原 pg_lock / pg_lock_stat / pg_query 顺延为 0460 / 0470 / 0480（内容不变）

修复与改进：

HTTP 路由注册隔离到私有 ServeMux，不再使用全局 DefaultServeMux，杜绝第三方库注册的端点被意外暴露
--web.telemetry-path 启动时严格校验：空路径、不以 / 开头、含 ? # { }、与内置端点冲突、以及 //metrics 这类注册后永远无法命中的非规范路径，一律启动即报错退出
落地页对 telemetry path 进行 HTML 转义
--fail-fast 预检失败退出时正确关闭主连接池
RPM / DEB 打包修复（#105）：prometheus 系统用户 HOME 指向 /var/lib/prometheus（libpq 查找 ~/.pgpass 的惯例位置），打包默认连接串补上 /postgres 数据库名，避免回退到以用户名命名的库
版本串统一为 v 前缀：官方发布二进制的 --version 输出、/version 端点与 pg_exporter_build_info{version=...} 标签现在为 v1.4.0（此前 GoReleaser 产物为无前缀的 1.3.0）；产物文件名、包版本号与 Docker 镜像 tag 命名规则不变
直方图值转换与标量路径语义对齐：时间戳与布尔列不应用 scale 缩放
修正 GoReleaser 内嵌包元数据：支持范围描述更新为 PostgreSQL 9.x - 19+ 与 pgBouncer 1.8 - 1.25+
make docker 恢复 GOPROXY / GOSUMDB 构建参数透传

工程与构建：

构建链更新到 Go 1.26.5、exporter-toolkit v0.17.1、prometheus/common v0.70.0
新增常规 CI 验证工作流：模块 tidy 校验、生成配置漂移校验（make conf 结果与 config/*.yml 强一致）、race 测试与六平台交叉编译
Docker 构建工具链整合：移除 docker/ 目录脚本与 make docker-release，多架构发布镜像统一由 GoReleaser 构建
配置覆盖测试泛化：测试不再假设特定采集器必然存在于配置目录中，便于裁剪自定义配置包

升级提示：

若此前使用了非规范的 telemetry path（如 //metrics），升级后进程将拒绝启动——此前虽能启动，但指标端点实际上不可达
解析 pg_exporter_build_info 的 version 标签或 --version 输出的自动化脚本，需要适配 v 前缀
配置了 HISTOGRAM 采集器时，le 不可再用作常量标签

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.4.0/checksums.txt

9874191591567ede87ae1d5820f06e781f27c664a7f4a6365211f9e042fd8199  checksums.txt
c6af4ae62e13f518539a6d0b3ce86ff9f7acdb567a4f0f86c6f47563574da724  pg-exporter_1.4.0-1_amd64.deb
ff0360f61982ed627d1b1f93281a0ba66da9d077672f0c214e19522df01e40d6  pg-exporter_1.4.0-1_arm64.deb
4fbadd4e9d918c9bc8e63975378e49375b0ff897d6b8a0f78799538b13dd68a1  pg-exporter_1.4.0-1_ppc64le.deb
5ce106d27fffa77c39fea9bf7cbc60f4328df3d926fef025bfdd082eb6d743fd  pg_exporter-1.4.0-1.aarch64.rpm
870b434e802e0039f10e1e3583c28a1fd83db4363a4608e1fab7f375f6d30600  pg_exporter-1.4.0-1.ppc64le.rpm
c550d16ce3f9276948a4d44174e11716fc5e85e31e8788ea106a57cfbabd8488  pg_exporter-1.4.0-1.x86_64.rpm
11a34e531ac5d6d378b91e768f575525389141a6860afabd0cc9f2d853f06749  pg_exporter-1.4.0.darwin-amd64.tar.gz
49d8d3a5932602f433c4ef681ed12007da1cbc11b5ee0f9d7b4dc2d0dff8e26e  pg_exporter-1.4.0.darwin-arm64.tar.gz
113dfe70d4f780a456c05ca6b731f96c1013bf35ecb87d75c443fe2bac7e333b  pg_exporter-1.4.0.linux-amd64.tar.gz
68b4630ab39943658a8aff135990896a5ccf56c8a992e5982d572c78ef822e18  pg_exporter-1.4.0.linux-arm64.tar.gz
72710625e5658c941b48f7becba9a86491852cea5469240328292838d9ed0979  pg_exporter-1.4.0.linux-ppc64le.tar.gz
14a0cf6ffa04c7e54c1d5aa5b37fe4bea1429c1d1e7cce89e9dd805c4a29db0b  pg_exporter-1.4.0.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.4.0

v1.3.0

v1.3.0 提供对 PostgreSQL 19 新指标的支持，同时刷新默认采集器包、构建链和配置覆盖测试。

变更摘要：

默认支持范围从 PostgreSQL 10-18+ 扩展到 10-19+
默认配置包包含 57 个 config/*.yml 定义文件
构建依赖更新到 Go 1.26.4、lib/pq v1.12.3、Prometheus client v1.23.2、exporter-toolkit v0.16.0。
pg_recovery_state：在恢复节点上采集 pg_stat_recovery，暴露提升触发、回放 LSN、时间线、恢复事务时间与暂停状态。
pg_lock_stat：采集 PG19 pg_stat_lock，按 locktype 暴露等待次数、等待时间和 fast-path 溢出次数。
pg_vacuum_score：采集 pg_stat_autovacuum_scores 当前数据库摘要，暴露最大 autovacuum 分数和候选表数量。
pg_wal_19：在 PG19 上暴露 wal_fpi_bytes，指标名为 pg_wal_fpi_bytes。
pg_sub_19：基于 pg_stat_subscription_stats 适配序列同步与逻辑复制冲突统计，继续提供兼容旧仪表盘的 sync_error_count。
pg_recv：PG13+ WAL receiver 分支识别 PG19 connecting 状态。
pg_slot：识别 PG19 replication slot idle_timeout 失效原因。
pg_db_confl：改为显式列清单，避免未来视图新增列被意外导出。
pg_backup、pg_vacuuming、pg_clustering 继续复用现有稳定分支，避免为低价值 PG19 字段改变已有指标面。

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.3.0/checksums.txt

c88c4ad7cde10531d75ec98fa536b2e7f531639f55c3b3c9866ee76934a4e2b2  checksums.txt
dfc6d517300687a382557e6d77af1ecb513bdde2e961d01ca46efa008ae15569  pg-exporter_1.3.0-1_amd64.deb
3d2ff642d0bb3657b28eb7c4b30bacc8ef9e4cbd057c870e6ec6817b47ac8092  pg-exporter_1.3.0-1_arm64.deb
4cfe043eb193780515a1e00ab93250dd44ca0728b35cb037ed165c70c89b6b5a  pg-exporter_1.3.0-1_ppc64le.deb
3ae4f8c554242ae52c4ba0fa07a9d95b702f72938ce55e8456dd97242cc46faf  pg_exporter-1.3.0-1.aarch64.rpm
71a0023383170b4ef3c243d9bf08d530b819fa891fa784e87c74b2a55cb426ec  pg_exporter-1.3.0-1.ppc64le.rpm
316a97ccb2df9a02de99dda33826857ec32bbd6fd874ffb950625bc064d62496  pg_exporter-1.3.0-1.x86_64.rpm
4ab312f27f0ded7f0ff5591866a86311d13041fef3a015e92f44fcf4a2284ccd  pg_exporter-1.3.0.darwin-amd64.tar.gz
2b20eb7b46c0790a8524f1c00a22ab57739bd60fd89ee947f6c2ba14e6a0d6bb  pg_exporter-1.3.0.darwin-arm64.tar.gz
7a2a8ce818f30260d1e7267d0b9e1fd5b3cbd569d55ad184fc9d6fb3801f3ad7  pg_exporter-1.3.0.linux-amd64.tar.gz
696619d19efbcf33f4afbae9748e72897289d2b7f772509cd6d465c9e818066d  pg_exporter-1.3.0.linux-arm64.tar.gz
0c16ac4a912f328be90e973b5123a272c2747759be9f56bacb5542653226475e  pg_exporter-1.3.0.linux-ppc64le.tar.gz
aa3724f4e8aeb732de18b7cb416283cbc2e94b9f511ec4b94e703792e8e8b10d  pg_exporter-1.3.0.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.3.0

v1.2.2

v1.2.2 是一次例行维护发布，仅将发布构建链更新到 Go 1.26.2，未引入新的采集器、配置语义或运行时行为变更。

变更摘要：

刷新构建链：发布流程更新到 Go 1.26.2
无功能改动：未调整采集器、默认配置、指标定义或运行时行为

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.2.2/checksums.txt

273dfd45ac367f71044998d19171ee27d7deb094ec9410d4b31aef7caacfdcc6  pg-exporter_1.2.2-1_amd64.deb
5e83c8448ee6350bec96ab95550df439a129c6700e5c9c7d0f9411aa9c2e7f40  pg-exporter_1.2.2-1_arm64.deb
97bb804bd1018c111708df9118561421d2cc51bd47d031b6d1f12cf1c988a3b2  pg-exporter_1.2.2-1_ppc64le.deb
b2f76799b21aba02b6bf5b6e71bf7ae2cf4487ad8817d53aad92f1d710c00120  pg_exporter-1.2.2-1.aarch64.rpm
f0ab38907bc87a9634c22911d8a0501634d58ce34020c0952dd49281a06787e6  pg_exporter-1.2.2-1.ppc64le.rpm
2000593d9d6732f3e03a43e291bc4e2368d2ecea125a2744dc533a030f51c800  pg_exporter-1.2.2-1.x86_64.rpm
e8a71704eb6957beaebd8ecaf83479e44db4a09bd9dc95c32f7b617f141b0386  pg_exporter-1.2.2.darwin-amd64.tar.gz
e648d9444f9a5f3ee49b82bcbbb459eefd73307c789f24f0d5238dbe1bcfec9c  pg_exporter-1.2.2.darwin-arm64.tar.gz
f278aba93d09b2a47aeef66898e770cacfdbc046eab0ba02de29f7c0261d9ede  pg_exporter-1.2.2.linux-amd64.tar.gz
bbeef56452643b8eb6bf9bb5baf113ab2c38177c06f8e1d008e63cce82260801  pg_exporter-1.2.2.linux-arm64.tar.gz
ad2385278ec6060fef2f7db7873c025f56f5c55048b51815cb4195486ca9dbe2  pg_exporter-1.2.2.linux-ppc64le.tar.gz
2ac53298058f09c5569464f918396f13d3a9efebec00296d89497e97ea74caf4  pg_exporter-1.2.2.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.2.2

v1.2.1

v1.2.1 是一次轻量维护版本，重点放在发布工程、配置包一致性与文档/元数据刷新上，不引入新的采集器语义或运行时行为变更。

变更摘要：

刷新构建链：发布流程与 Docker 构建基础镜像升级到 Go 1.26.1
统一配置样式：将当前配置与 Legacy 配置中的内联 description 统一改为双引号写法，并重新生成合并后的 pg_exporter.yml / legacy/pg_exporter.yml
增加配置一致性测试：新增 split/merged config 等价性校验，以及内联指标描述风格检查，减少配置漂移风险
刷新打包元数据：RPM / DEB 描述中的支持范围更新为 PostgreSQL 9.x - 18+ 与 pgBouncer 1.8 - 1.25+，并更新 Pigsty 文档入口链接

校验和

2cbe7a78a0dde8a6155a543232af883de6623531c9f6ea0951ddc30dc7514649  pg-exporter_1.2.1-1_amd64.deb
e70e09974ad52ba607b176b63c300610e37f44fe67d249aa9ef364bd58352585  pg-exporter_1.2.1-1_arm64.deb
4e6c7fae85e7fe2e62c3d66c388b5f3db57b5e95e85f43ce648d21b792d83d87  pg-exporter_1.2.1-1_ppc64le.deb
30103629e8c5c1ee5589addadb37fcb07b43179c8a19f80c016a0ed8d7ac2a47  pg_exporter-1.2.1-1.aarch64.rpm
01b4dd32b20bca8612f71f0edf3557dfa92fc85f669d3260f627d34ce102b517  pg_exporter-1.2.1-1.ppc64le.rpm
5afb4f14aa71b256cdfc93d6cc6da8a7052427d6f1c1b71900bf2593b196de50  pg_exporter-1.2.1-1.x86_64.rpm
45e71c6017beffabf2873841d374b5de40eb499dd768d6db1208d7cc6295bcf5  pg_exporter-1.2.1.darwin-amd64.tar.gz
d3035cc6a023fe1bad5443a7c1d5c8189b3d807d165f131f88566b5c35476259  pg_exporter-1.2.1.darwin-arm64.tar.gz
14d3f83de4377e5363611d2ae4eef9470a85d7518784c06b8a8c0f63b6e0a340  pg_exporter-1.2.1.linux-amd64.tar.gz
71082081e7aaf1cf15c941c310d03da49cf9971205274aad7dae21a126bc4fe1  pg_exporter-1.2.1.linux-arm64.tar.gz
cba30919b8d2945be199a4a346eb2891c88fd7a1d6c3482c1006442f4f6109e7  pg_exporter-1.2.1.linux-ppc64le.tar.gz
6fe528a242f0bbd3b89cd8b2697f48905b5c4b1398abfb3305193808c01738e9  pg_exporter-1.2.1.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.2.1

v1.2.0

v1.2.0 是一次聚焦稳定性与兼容性的中版本更新，覆盖启动流程、热重载、健康检查、配置校验与 Legacy 支持。

新功能：

支持配置热重载：新增平台相关的信号重载（SIGHUP / SIGUSR1），并强化 POST /reload 工作流，可在不重启进程情况下更新配置与查询计划
启动流程改为非阻塞：即使目标库预检失败，也会先启动 HTTP 服务，便于监控系统先接入后恢复
新增 PostgreSQL 9.1-9.6 Legacy 配置套件：提供 legacy/ 配置目录与 make conf9 目标，便于 EOL 老版本平滑接入
健康检查机制重构：引入缓存健康快照与周期探测，读写角色类健康端点行为更一致，重载期间更平滑
工程链路增强：Release 工作流增加 go test 与 go vet，并升级构建链到 Go 1.26.0

Bug 修复：

修复多处配置解析边界问题：拒绝非法 metrics 定义、无效目录加载失败场景可正确报错，并补齐运行时回退逻辑
修复命令行布尔参数解析：正确处理 --flag=false 风格传参，避免被误判为启用
修复 /explain 输出与渲染安全性：调整内容类型并改用更安全的模板渲染路径
修复谓词查询与连接 URL 处理细节：增强 BOOL/BOOLEAN 条件支持、完善 dbname 查询参数解析与 URL 脱敏输出
修复自动发现目标移除时的资源释放行为：异步关闭已移除数据库连接，降低采集阻塞风险
修复指标与标签校验细节：补齐常量标签冲突检查、默认值缩放处理与若干 Prometheus 规则校验

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.2.0/checksums.txt

26e7a052e730b412bbbe5f49846f951b89650f1f95c2466d5d486923f0825f64  pg-exporter_1.2.0-1_amd64.deb
4ec219135c49708d010af7b8a7553b8008f630574e1d4cfc7642fbf951eefafe  pg-exporter_1.2.0-1_arm64.deb
5b2cc00e2c3e2ffd9eb0ab1a4f5e937dd68f3a69a14423a74d4de3d7cf29283e  pg-exporter_1.2.0-1_ppc64le.deb
d536d41a92e8aa85ae3935715d1bf0463208b1e614eae73543f1472ca8a7e0d4  pg_exporter-1.2.0-1.aarch64.rpm
b7a1daa225f8ca4de6d227e6004330589295d924accd221892ebe14f191fe35c  pg_exporter-1.2.0-1.ppc64le.rpm
28bf7d85862510675c64ff5181d216c6a068a23ffa56dc4bb9e6b82165ff99b5  pg_exporter-1.2.0-1.x86_64.rpm
51c3b3d18089d888a54a6b3e7ecb0620dc0da04c81471a0b7aaa88c1677ddb8c  pg_exporter-1.2.0.darwin-amd64.tar.gz
3ba1c7adea9c926afd3054ba18cc43e665e420a495bfcfd2248242c49a67b077  pg_exporter-1.2.0.darwin-arm64.tar.gz
9e1ec6c15e6b2aaadbe27a27053ee1ec289bdd012c19ca6371de738fa5f8843e  pg_exporter-1.2.0.linux-amd64.tar.gz
9e18849693ccda313979db0a230cb81acfe4199364feb6ce3e72d1a89fbfb809  pg_exporter-1.2.0.linux-arm64.tar.gz
6e28489685d0bd1fdabcb71474f64f559ade199b871666954323bae9dc01465f  pg_exporter-1.2.0.linux-ppc64le.tar.gz
9e9beac619fe2c614a77bc3334bc4b80df9db355bf95845eb4b11674ddad52d9  pg_exporter-1.2.0.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.2.0

v1.1.2

小版本更新，修复 pg_timeline 配置问题，使用最新 Go 依赖构建。

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.1.2/checksums.txt

8cddd57a843914a3145a80a3220bc875047b9bcac0664357c01ba86485436236  pg-exporter_1.1.2-1_amd64.deb
f5b25a8ae5c022867a54c17ba1c6493eba20dcb292340460390289336df24f04  pg-exporter_1.1.2-1_arm64.deb
4da2c287f6717681b25befda0d59a89b9d1b258281ce94f3a6bc21d02f70c83c  pg-exporter_1.1.2-1_ppc64le.deb
b26355f3c1a5b8a147291a51e2d7ada204deed6d52877c146a8b3e499defa5e8  pg_exporter-1.1.2-1.aarch64.rpm
42ef89716ba99dd918b0e9c77ef3236129d613f68bb8ae5929668a5a2596cca5  pg_exporter-1.1.2-1.ppc64le.rpm
a8f4a2d5c7b6701c7bac788a7ed7183b6c4b74a334326cd389f3a695fb77675d  pg_exporter-1.1.2-1.x86_64.rpm
775f5ea3188a6acb1327c001c4ba9a0651424c3bb37d800e6f67972c904c4750  pg_exporter-1.1.2.darwin-amd64.tar.gz
7f2bbcc2db1e16dc78c3edd8e67e20e4ec81f2972c8c37135cba6f6afbf91003  pg_exporter-1.1.2.darwin-arm64.tar.gz
33c34b1f9ef6b6e7615f241a95059a8137a2337a454930b668180a9329d12b98  pg_exporter-1.1.2.linux-amd64.tar.gz
2b91a5818d780e38692ab6446cacb496695e67388676c18012be582e8ddfbdd8  pg_exporter-1.1.2.linux-arm64.tar.gz
adcb5f229f4a5d641f6430b9a2dfb0377a2e4310efad242730867d6cdf5e27ee  pg_exporter-1.1.2.linux-ppc64le.tar.gz
90b7c7e4b2b94936b5faa3cf2d35509b62ebc0d60b3afe1abaaf03efcd415a4a  pg_exporter-1.1.2.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.1.2

v1.1.1

小版本更新，新增采集器和 Bug 修复。

新功能：

新增 pg_timeline 采集器，用于时间线监控
新增 pg_sub_16 采集器分支，排除订阅中的并行操作（PostgreSQL 16+ 兼容性）

Bug 修复：

修复：为 pg_recv 采集器的 slotname 添加 coalesce 以处理 NULL 值

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.1.1/checksums.txt

fd5ee96511676fc11b975115a4870ed0c811056519f79ad7f24ab7ec538fa278  pg-exporter_1.1.1-1_amd64.deb
b90a08d16a6e4707d82f8f3ae282cb76acb331de607e7544532fd0b774b7aa27  pg-exporter_1.1.1-1_arm64.deb
163955f59a71da48901ffa26bb2f2db0712d31d8aeb1ab3fa463683f719a6d3a  pg-exporter_1.1.1-1_ppc64le.deb
cf4f8bc12bb8a2d1e55553f891fd31c43324e4348249727972eb44f82cd4e6c8  pg_exporter-1.1.1-1.aarch64.rpm
5a425b2f61f308b32f2d107372830c34eb685bfb312ee787f11877a20f1c4a2e  pg_exporter-1.1.1-1.ppc64le.rpm
23606ccea565368971ac2e7f39766455b507021f09457bcf61db13cb10501a16  pg_exporter-1.1.1-1.x86_64.rpm
ce74624eba92573318f50764cee4f355fa1f35697d209f70a4240f8f9d976188  pg_exporter-1.1.1.darwin-amd64.tar.gz
35fba12521dbdcc54a3792278ed4822e4ca9e951665b5e53dff7c2a0f7014ae3  pg_exporter-1.1.1.darwin-arm64.tar.gz
7699bdef15dd306289645beee8d40a123ca75dc988e46d89cdd75a1c1f650bef  pg_exporter-1.1.1.linux-amd64.tar.gz
f4baba59d27a8eb67f0c5209fed7b9f00f78db796e583cc3487701e7803671c6  pg_exporter-1.1.1.linux-arm64.tar.gz
810c3817c27358fa667714f8bfe8d52840a7ea010035e29547919ccb7c9fa781  pg_exporter-1.1.1.linux-ppc64le.tar.gz
3f6df693b3eb92fdaeaeccf99ea7e5977b2c65028a4f00bdfabbc0405b9f5f93  pg_exporter-1.1.1.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.1.1

v1.1.0

使用 Go 1.25.5 和最新依赖构建，采集器更新：

采集器变更：

pg_setting：针对 PG10-18 兼容性进行重大重构，支持 missing_ok
- 新增 13 个指标：max_parallel_workers、max_parallel_workers_per_gather、max_parallel_maintenance_workers、shared_buffers、maintenance_work_mem、effective_cache_size、fsync、full_page_writes、autovacuum、autovacuum_max_workers、checkpoint_timeout、checkpoint_completion_target、hot_standby、synchronous_commit、io_method
- 将 work_memory_size 重命名为 work_mem
- min_version 从 9.6 改为 10，显式 ::int 类型转换
pg_size：修复日志目录大小检测，使用 logging_collector 检查代替路径模式匹配
pg_table：性能优化，用 JOIN 替换 LATERAL 子查询以提升查询性能；修复 tuples 和 frozenxid 指标类型从 COUNTER 改为 GAUGE；超时从 1s 增加到 2s
pg_vacuuming：新增 PG17 采集器分支，包含新指标 indexes_total、indexes_processed、dead_tuple_bytes 用于索引 vacuum 进度跟踪
pg_query：超时从 1s 增加到 2s 以应对高负载场景
pg_io：修复 reuses 描述中的拼写错误（“in reused” -> “is reused”）
pg_checkpointer：修复 pg_checkpointer_10 描述（“9.4+” -> “9.4-17”）
pg_db_confl：修复 pg_db_confl_15 描述（“9.1 - 16” -> “9.1 - 15”）
pg_db、pg_indexing、pg_clustering、pg_backup 格式对齐修复

其他变更：

由 @anayrat 修复发布年份

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.1.0/checksums.txt

9c65f43e76213bb8a49d1eab2c76a27d9ab694e67bc79f0ad12769ea362b5ca2  pg-exporter_1.1.0-1_amd64.deb
bcd2cacb4febc5fb92f9eda8e733c161c8c6721416e16ec91a773503241c972d  pg-exporter_1.1.0-1_arm64.deb
2c9d4a9cb06d07af0b6dd9dd6e568af073dc9f6775abde63b45f0aae34d171b1  pg-exporter_1.1.0-1_ppc64le.deb
2934ab5b0fb16dca5a96ec1e8f230e32c72b30ca076b5e5ddf8ec553c821f7b8  pg_exporter-1.1.0-1.aarch64.rpm
3c9955f31ba93532cc7f95ff60b0658f4b6eca6a827710e2f70c0716b34eab43  pg_exporter-1.1.0-1.ppc64le.rpm
9fdefbd8e7660dcb130207901a27762e0a381857ba8cf12b63184744f92dea05  pg_exporter-1.1.0-1.x86_64.rpm
7159002016754309e0ed625a9a48049d21177883fa11d1e448eb7655ceb690cc  pg_exporter-1.1.0.darwin-amd64.tar.gz
7d55ac5cda0b1fd8ffbd5e76b9c1c1784ac8e353104a206caaadce89adda6d65  pg_exporter-1.1.0.darwin-arm64.tar.gz
8211ec24277554b9b1a36920d7865153e21c2621031d3d08f22d94cdd2ddf02f  pg_exporter-1.1.0.linux-amd64.tar.gz
d17ab7f9bf04442e642483d432d005d25bb62e0c9caa73cb7e69ee19eb89b3ae  pg_exporter-1.1.0.linux-arm64.tar.gz
c074aeb345cc30f7b6e16aa153ae3d9a12789e4425987590c3fd77c4e68a40b6  pg_exporter-1.1.0.linux-ppc64le.tar.gz
13d653e2abb023ce9526bdc2815135b82f49c044d237030f3f56b09fb016fcb7  pg_exporter-1.1.0.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.1.0

v1.0.3

使用 Go 1.25.4 和最新依赖构建
修复 #80 与 libpq 环境变量冲突
由 @kadaffy 将 auto-discovery 默认值改为 true

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.0.3/checksums.txt

7efa1a77dfd5b94813c32c7ac015b1d479b1f04fb958f6b1ed5af333e354d015  pg-exporter_1.0.3-1_amd64.deb
41e18bf18eba2ab90ac371bfb46e9152da9fe628ebd8e26766cac08325eb3b07  pg-exporter_1.0.3-1_arm64.deb
7da8ed738d254c120d42aa51d6137f84e7f4e3188bc764d4f9a1438220363a43  pg-exporter_1.0.3-1_ppc64le.deb
a214b555981156da7b7d248b1f728f8ac88a07ac8f77a66c5d8e43b40670d6b4  pg_exporter-1.0.3-1.aarch64.rpm
d876fc66e208612ebffe3c43dabce88b088d915f92584260d710b85a3a131413  pg_exporter-1.0.3-1.ppc64le.rpm
75f62d314fec50c836c534996c884d25ecea77810ab33e7ba0e9c4b783e775b4  pg_exporter-1.0.3-1.x86_64.rpm
47829a19707284bcee1b8dc47cc7d0172398bb533e6b4043950f787486712769  pg_exporter-1.0.3.darwin-amd64.tar.gz
38b6ccb72315cadea542b1f2a7b7022d0e8d48ffd4ab177bb69a0a909b99af6b  pg_exporter-1.0.3.darwin-arm64.tar.gz
36e8dff84d61a7593ff1fcec567ca4ffeaecd0be2f9eabd227ceac71b12a919a  pg_exporter-1.0.3.linux-amd64.tar.gz
6477e8ef873773a09c4f39a29444f21b5b2c71e717e52ca425bcc8e8e5448791  pg_exporter-1.0.3.linux-arm64.tar.gz
a083b51ebed2b280e2eaa0f19558494e7fa6f122a0a86a1d117206fcd090820c  pg_exporter-1.0.3.linux-ppc64le.tar.gz
a1f9b27b7190f478726d96f270a72d9dc4d3f2bcc3b0326b7c4a2607e62ea588  pg_exporter-1.0.3.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.0.3

v1.0.2

使用 Go 1.25.0 和最新依赖构建
专属网站和主页：https://exp.pgsty.com
使用 goreleaser 通过 CI/CD 流水线发布更多操作系统/架构：
- 新增 Windows amd64 支持
- 新增 Linux ppc64le 支持

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.0.2/checksums.txt

683bf97f22173f2f2ec319a88e136939c2958a1f5ced4f4aa09a1357fc1c44c5  pg-exporter_1.0.2-1_amd64.deb
f62d479a92be2d03211c162b8419f968cea87ceef5b1f25f2bcd390e0b72ccb5  pg-exporter_1.0.2-1_arm64.deb
e1bbfc5a4c1b93e6f92bc7adcb4364583ab763e76e156aa5c979d6d1040f4c7a  pg-exporter_1.0.2-1_ppc64le.deb
f51d5b45448e6bbec3467d1d1dc049b1e16976f723af713c4262541ac55a039c  pg_exporter-1.0.2-1.aarch64.rpm
18380011543674e4c48b2410266b41165974d780cbc8918fc562152ba623939e  pg_exporter-1.0.2-1.ppc64le.rpm
198372d894b9598c166a0e91ca36d3c9271cb65298415f63dbffcf6da611f2bb  pg_exporter-1.0.2-1.x86_64.rpm
cbe7e07df6d180507c830cdab4cf86d40ccd62774723946307b5331d4270477d  pg_exporter-1.0.2.darwin-amd64.tar.gz
20c4a35fa244287766c1d1a19cd2e393b3fa451a96a81e5635401e69bef04b97  pg_exporter-1.0.2.darwin-arm64.tar.gz
d742111185f6a89fff34bfd304b851c8eb7a8e38444f0220786e11ed1934eff1  pg_exporter-1.0.2.linux-amd64.tar.gz
0b1f4c97c1089c4767d92eb22419b8f29c9f46fb90ddfd1e8514cc42dc41054f  pg_exporter-1.0.2.linux-arm64.tar.gz
895083fd2c7fc5409cc1a2dbaaef1e47ac7aa6a3fd5db2359012922d90bcdcc3  pg_exporter-1.0.2.linux-ppc64le.tar.gz
5f751228e7120604af9a482fb70197489fa633c38a0f2b6a3489393fbc6a10aa  pg_exporter-1.0.2.windows-amd64.tar.gz

https://github.com/pgsty/pg_exporter/releases/tag/v1.0.2

v1.0.1

新增 DockerHub 镜像：pgsty/pg_exporter
升级 Go 依赖到最新版本，使用 Go 1.24.5 构建
默认禁用 pg_tsdb_hypertable 采集器，因为 timescaledb 目录已变更

校验和

d5e2d6a656eef0ae1b29cd49695f9773  pg_exporter-1.0.1-1.aarch64.rpm
cb01bb78d7b216a235363e9342803cb3  pg_exporter-1.0.1-1.x86_64.rpm
67093a756b04845f69ad333b6d458e81  pg_exporter-v1.0.1.darwin-amd64.tar.gz
2d3fdc10045d1cf494b9c1ee7f94f127  pg_exporter-v1.0.1.darwin-arm64.tar.gz
e242314461becfa99c3978ae72838ab0  pg_exporter-v1.0.1.linux-amd64.tar.gz
63de91da9ef711a53718bc60b89c82a6  pg_exporter-v1.0.1.linux-arm64.tar.gz
718f6afc004089f12c1ca6553f9b9ba5  pg-exporter_1.0.1_amd64.deb
57da7a8005cdf91ba8c1fb348e0d7367  pg-exporter_1.0.1_arm64.deb

https://github.com/pgsty/pg_exporter/releases/tag/v1.0.1

v1.0.0

新增 PostgreSQL 18 指标支持

新采集器分支 pg_wal_18：
- 移除 write、sync、write_time、sync_time 指标
- 移至 pg_stat_io
新采集器分支 pg_checkpointer_18：
- 新指标 num_done
- 新指标 slru_written
新采集器分支 pg_db_18：
- 新指标 parallel_workers_to_launch
- 新指标 parallel_workers_launched
新采集器分支 pg_table_18：
- table_parallel_workers_to_launch
- table_parallel_workers_launched
新采集器分支 pg_io_18：
- 新增 WAL 统计系列
- 新指标 read_bytes
- 新指标 write_bytes
- 新指标 extend_bytes
- 移除 op_bytes（因为是固定值）
新采集器分支 pg_vacuuming_18：
- 新指标 delay_time

8637bc1a05b93eedfbfd3816cca468dd  pg_exporter-1.0.0-1.aarch64.rpm
a28c4c0dcdd3bf412268a2dbff79f5b9  pg_exporter-1.0.0-1.x86_64.rpm
229129209b8e6bc356c28043c7c22359  pg_exporter-v1.0.0.darwin-amd64.tar.gz
d941c2c28301269e62a8853c93facf12  pg_exporter-v1.0.0.darwin-arm64.tar.gz
5bbb94db46cacca4075d4c341c54db37  pg_exporter-v1.0.0.linux-amd64.tar.gz
da9ad428a50546a507a542d808f1c0fa  pg_exporter-v1.0.0.linux-arm64.tar.gz
0fa2395d9d7a43ab87e5c87e5b06ffcc  pg-exporter_1.0.0_amd64.deb
fed56f8a37e30cc59e85f03c81fce3f5  pg-exporter_1.0.0_arm64.deb

https://github.com/pgsty/pg_exporter/releases/tag/v1.0.0

v0.9.0

默认采集器

新增 timescaledb 超表指标采集器
新增 citus 分布式节点指标采集器
新增 pg_wait_sampling 等待事件采集器
pg_slot 全面改进：新增 16/17 pg_replication_slot 指标
允许 pg_slot 采集器从 16/17 开始在从库上运行
重构 pg_wait 采集器，从所有进程聚合
限制 pg_clustering、pg_indexing、pg_vacuuming 只在主库运行
将所有 reset_time 标记为 GAUGE 而非 COUNTER
修复 pg_recovery_prefetch_skip_fpw 类型从 GAUGE 改为 COUNTER
修复 pg_recv.state 类型从 LABEL 改为 GAUGE
采集器格式改为紧凑模式
新增默认指标 pg_exporter_build_info / pgbouncer_exporter_build_info
为 pg_meta 采集器新增 server_encoding
为 pg_setting 采集器新增 12 个设置指标：
- wal_block_size
- segment_size
- wal_segment_size
- wal_level
- wal_log_hints
- work_mem
- hugepage_count
- hugepage_status
- max_wal_size
- min_wal_size
- max_slot_wal_keep_size

导出器代码库

使用最小 PG 版本后缀规范化采集器分支名称
为二进制包添加许可证文件
将 pgsty/pg_exporter 仓库移至 pgsty/pg_exporter
重构 server.go 以降低 Compatible 和 PostgresPrecheck 复杂度
使用额外数字前缀重命名指标采集器以便排序
升级依赖到最新版本
在所有非致命采集器之前执行致命采集器，快速失败

https://github.com/pgsty/pg_exporter/releases/tag/v0.9.0

v0.8.1

升级依赖到最新版本
升级 golang.org/x/net 从 0.35.0 到 0.36.0 #67
更新 Docker 镜像构建标签

https://github.com/pgsty/pg_exporter/releases/tag/v0.8.1

v0.8.0

新增 PgBouncer 1.24 新指标支持（stat、pool、database）
修复：310-pg_size.yml 在日志目录设置不正确时失败 #64，由 @Süleyman Vurucu 贡献
使用最新 Go 1.24 构建并升级所有依赖
使用标准 log/slog 重构日志，替代 go-kit
完整变更日志：https://github.com/pgsty/pg_exporter/compare/v0.7.1…v0.8.0

https://github.com/pgsty/pg_exporter/releases/tag/v0.8.0

v0.7.1

使用 dependabot 进行例行更新

功能：支持将配置指定为 Reader，由 @ringerc 在 #62 贡献
升级 golang.org/x/crypto 从 0.21.0 到 0.31.0，由 @dependabot 在 #63 贡献
修复一些拼写错误
完整变更日志：https://github.com/pgsty/pg_exporter/compare/v0.7.0…v0.7.1

https://github.com/pgsty/pg_exporter/releases/tag/v0.7.1

v0.7.0

为最新 Go 版本重构代码库。

PostgreSQL 17 指标支持，由 @Vonng 贡献
pg_exporter: 谓词查询功能，由 @ringerc 贡献
在 Dockerfile 中进行干净构建，由 @ringerc 贡献
pg_exporter: “bind: address already in use” 后不再 panic，由 @ringerc 贡献
pg_exporter: 修复 /stat 端点格式，由 @ringerc 贡献
pg_exporter: yaml 导出时省略默认查询属性，由 @ringerc 贡献
从发现中排除模板数据库并模式限定发现查询，由 @ringerc 贡献
修复一些拼写错误和指标描述错误，由 @ringerc 贡献
从废弃的 lib/pq 驱动切换到带 stdlib 包装的 pgx，由 @ringerc 贡献

https://github.com/pgsty/pg_exporter/releases/tag/v0.7.0

v0.6.0

安全增强：修复安全 dependabot 问题
新增 pg16 采集器
新增 arm64 和 aarch64 包
移除 pg_query 采集器的 monitor 模式要求（您需要通过 search_path 确保或直接在默认 public 模式中安装 pg_stat_statements）
修复 pgbouncer 版本解析消息级别从 info 改为 debug
修复 pg_table_10_12 采集器缺少 relid 的问题
识别配置目录中的 yml 后缀文件，由 @Japin Li 贡献
支持 PostgreSQL 15 及更高版本，由 @Japin Li 贡献
修复 connect-timeout 传播，由 @mouchar 贡献

https://github.com/pgsty/pg_exporter/releases/tag/v0.6.0

v0.5.0

导出器增强

使用 nfpm 构建 rpm 和 deb
新增 column.default，当指标值为 NULL 时替换
新增 column.scale，当指标值为浮点/整数时乘以缩放因子（例如微秒转秒）
修复 /stat 端点输出
新增 Docker 容器 pgsty/pg_exporter

指标采集器

将 bgwriter 和 pg_wal 时间单位缩放为秒
移除 pg_class 采集器，将其移至 pg_table 和 pg_index
为 pg_table 新增 pg_class 指标
为 pg_index 新增 pg_class 指标
默认启用 pg_table_size
将 pg_query、pg_db、pg_bgwriter、pg_ssl、pgbouncer_stat 时间指标缩放为秒

https://github.com/pgsty/pg_exporter/releases/tag/v0.5.0

v0.4.1

更新默认采集器
- 在对象监控中省略 citus 和 timescaledb 模式
- 避免重复的 pg_statio 元组
- 支持 pgbouncer v1.16
- Bug 修复：pg_repl 采集器在 pg 12 上重叠
新参数：-T connect-timeout PG_EXPORTER_CONNECT_TIMEOUT 这在监控远程 Postgres 实例时很有用
现在 pg_exporter.yaml 在 rpm 包中重命名为 pg_exporter.yml

https://github.com/pgsty/pg_exporter/releases/tag/v0.4.1