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

返回本页常规视图.

PG Exporter

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

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

快速上手 | GitHub | 在线演示


功能特性

特性描述
全指标覆盖监控 PostgreSQL(10-18+)与 pgBouncer(1.8-1.24+),全指标覆盖
声明式配置通过 YAML 配置文件定义自定义指标,精细控制超时、缓存和跳过条件
采集器定制使用声明式 YAML 配置定义自己的指标,支持动态查询规划
自动发现自动发现并监控 PostgreSQL 实例中的多个数据库
动态规划根据 PostgreSQL 版本、扩展和服务器特性自动调整指标采集策略
生产就绪在真实环境中经过 6 年以上、12K+ 核心的实战检验,具备企业级可靠性
健康检查提供全面的 HTTP 端点用于服务健康检查和流量路由,支持主从检测
智能缓存内置缓存机制,可配置 TTL,减少数据库负载并提升性能
扩展感知原生支持 pg_stat_statements、pg_wait_sampling, citus, timesacledb

快速安装

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
wget https://github.com/pgsty/pg_exporter/releases/download/v1.1.0/pg_exporter-v1.1.0.linux-amd64.tar.gz
tar -xf pg_exporter-v1.1.0.linux-amd64.tar.gz
sudo install pg_exporter-v1.1.0.linux-amd64/pg_exporter /usr/bin/
sudo install pg_exporter-v1.1.0.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,参见 快速上手

# 使用 PostgreSQL 连接 URL 运行
PG_EXPORTER_URL='postgres://user:pass@localhost:5432/postgres' pg_exporter

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

文档目录

文档描述
快速上手快速开始指南与基础概念
安装指南各平台的安装说明
配置参考配置参考与采集器定义
API 参考HTTP API 端点参考
部署指南生产部署最佳实践
发布说明版本发布历史

在线演示

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

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

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

社区与支持

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

开源协议

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

Copyright 2018-2025 © 冯若航 / rh@vonng.com

1 - 快速上手

几分钟内启动并运行 PG Exporter

PG Exporter 是一款先进的 PostgreSQL 与 pgBouncer 指标导出器,专为 Prometheus 设计。本指南将帮助您快速启动并运行。


前置条件

在开始之前,请确保您具备:

  • PostgreSQL 10+ 或 pgBouncer 1.8+ 实例用于监控
  • 具有适当监控权限的用户账户
  • Prometheus 兼容系统(用于指标抓取)
  • 对 PostgreSQL 连接字符串的基本了解

快速开始

最快速地启动 PG Exporter:

# 下载并安装最新版本
curl -L https://github.com/pgsty/pg_exporter/releases/latest/download/pg_exporter-$(uname -s)-$(uname -m).tar.gz | tar xz
sudo install pg_exporter /usr/bin/

# 使用 PostgreSQL 连接 URL 运行
PG_EXPORTER_URL='postgres://user:pass@localhost:5432/postgres' pg_exporter

# 验证指标是否可用
curl http://localhost:9630/metrics

基本概念

连接字符串

PG Exporter 使用标准的 PostgreSQL 连接 URL:

postgres://[user][:password]@[host][:port]/[database][?param=value]

示例:

  • 本地 PostgreSQL:postgres:///postgres
  • 带认证的远程连接:postgres://monitor:password@db.example.com:5432/postgres
  • 使用 SSL:postgres://user:pass@host/db?sslmode=require
  • pgBouncer:postgres://pgbouncer:password@localhost:6432/pgbouncer

内置指标

PG Exporter 开箱即用提供 4 个核心内置指标:

指标类型描述
pg_upGauge如果导出器能够连接到 PostgreSQL 则为 1,否则为 0
pg_versionGaugePostgreSQL 服务器版本号
pg_in_recoveryGauge如果服务器处于恢复模式(从库)则为 1,主库则为 0
pg_exporter_build_infoGauge导出器版本和构建信息

配置文件

所有其他指标(600+)都在 pg_exporter.yml 配置文件中定义。默认情况下,PG Exporter 会按以下顺序查找此文件:

  1. 通过 --config 标志指定的路径
  2. PG_EXPORTER_CONFIG 环境变量中的路径
  3. 当前目录(./pg_exporter.yml
  4. 系统配置(/etc/pg_exporter.yml/etc/pg_exporter/

首次监控设置

步骤 1:创建监控用户

创建一个专用的 PostgreSQL 用户用于监控:

-- 创建监控用户
CREATE USER pg_monitor WITH PASSWORD 'secure_password';

-- 授予必要权限
GRANT pg_monitor TO pg_monitor;
GRANT CONNECT ON DATABASE postgres TO pg_monitor;

-- 对于 PostgreSQL 10+,pg_monitor 角色提供对监控视图的读取权限
-- 对于更早版本,您可能需要额外的授权

步骤 2:测试连接

验证导出器能够连接到您的数据库:

# 设置连接 URL
export PG_EXPORTER_URL='postgres://pg_monitor:secure_password@localhost:5432/postgres'

# 以干运行模式运行以测试配置
pg_exporter --dry-run

步骤 3:运行导出器

启动 PG Exporter:

# 使用默认设置运行
pg_exporter

# 或使用自定义标志
pg_exporter \
  --url='postgres://pg_monitor:secure_password@localhost:5432/postgres' \
  --web.listen-address=':9630' \
  --log.level=info

步骤 4:配置 Prometheus

在您的 prometheus.yml 中将 PG Exporter 添加为目标:

scrape_configs:
  - job_name: 'postgresql'
    static_configs:
      - targets: ['localhost:9630']
        labels:
          instance: 'postgres-primary'

步骤 5:验证指标

检查指标是否正在被采集:

# 查看原始指标
curl http://localhost:9630/metrics | grep pg_

# 检查导出器统计信息
curl http://localhost:9630/stat

# 验证服务器检测
curl http://localhost:9630/explain

自动发现模式

PG Exporter 可以自动发现并监控 PostgreSQL 实例中的所有数据库:

# 启用自动发现(默认行为)
pg_exporter --auto-discovery

# 排除特定数据库
pg_exporter --auto-discovery \
  --exclude-database="template0,template1,postgres"

# 仅包含特定数据库
pg_exporter --auto-discovery \
  --include-database="app_db,analytics_db"

当启用自动发现时:

  • 集群级指标(1xx-5xx)每个实例采集一次
  • 数据库级指标(6xx-8xx)为每个发现的数据库采集
  • 指标使用 datname 标签来区分不同的数据库

监控 pgBouncer

要监控 pgBouncer 而不是 PostgreSQL:

# 连接到 pgBouncer 管理数据库
PG_EXPORTER_URL='postgres://pgbouncer:password@localhost:6432/pgbouncer' \
pg_exporter --config=/etc/pg_exporter.yml

导出器会自动检测 pgBouncer 并:

  • 使用 pgbouncer 命名空间作为指标前缀
  • 执行 pgBouncer 专用采集器(9xx 系列)
  • 提供 pgBouncer 专用的健康检查

使用 Docker

在容器中运行 PG Exporter:

docker run -d \
  --name pg_exporter \
  -p 9630:9630 \
  -e PG_EXPORTER_URL="postgres://user:pass@host.docker.internal: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 \
  -e PG_EXPORTER_URL="postgres://user:pass@db:5432/postgres" \
  pgsty/pg_exporter:latest

健康检查

PG Exporter 为负载均衡器和编排器提供健康检查端点:

# 基本健康检查
curl http://localhost:9630/up
# 返回:连接正常返回 200,否则返回 503

# 主库检测
curl http://localhost:9630/primary
# 返回:主库返回 200,从库返回 404,未知返回 503

# 从库检测
curl http://localhost:9630/replica
# 返回:从库返回 200,主库返回 404,未知返回 503

故障排查

连接问题

# 使用详细日志测试
pg_exporter --log.level=debug --dry-run

# 检查服务器规划
pg_exporter --explain

权限错误

确保监控用户具有必要的权限:

-- 检查当前权限
SELECT * FROM pg_roles WHERE rolname = 'pg_monitor';

-- 如需要,授予额外权限
GRANT USAGE ON SCHEMA pg_catalog TO pg_monitor;
GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO pg_monitor;

抓取缓慢

如果抓取超时:

  1. 检查慢查询:curl http://localhost:9630/stat
  2. 在配置中调整采集器超时
  3. 对昂贵的查询使用缓存(在采集器配置中设置 ttl
  4. 如果不需要,禁用昂贵的采集器

下一步

2 - 安装指南

如何下载和安装 PG Exporter

PG Exporter 提供多种安装方式以适应不同的部署场景。本指南涵盖了各平台的所有可用安装选项及详细说明。


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.1.0 发布文件:

类型文件
DEB (amd64)pg-exporter_1.1.0_amd64.deb
DEB (arm64)pg-exporter_1.1.0_arm64.deb
RPM (aarch64)pg_exporter-1.1.0-1.aarch64.rpm
RPM (x86_64)pg_exporter-1.1.0-1.x86_64.rpm
Tarball (Linux amd64)pg_exporter-v1.1.0.linux-amd64.tar.gz
Tarball (Linux arm64)pg_exporter-v1.1.0.linux-arm64.tar.gz
Tarball (macOS amd64)pg_exporter-v1.1.0.darwin-amd64.tar.gz
Tarball (macOS arm64)pg_exporter-v1.1.0.darwin-arm64.tar.gz

您可以直接使用操作系统的包管理器(rpm/dpkg)安装,或者将二进制文件放入 $PATH 中。


软件仓库

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 上提供了 amd64arm64 架构的预构建镜像: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

二进制安装

pg_exporter 可以作为独立的二进制文件安装。从发布页面下载适合您平台的 tarball,解压后将二进制文件放入 $PATH 即可使用。


兼容性

当前 pg_exporter 支持 PostgreSQL 10 及以上版本,但设计上可以兼容任何 PostgreSQL 主版本(向下兼容到 9.x)。

使用旧版本(9.6 及以下)的唯一问题是,由于这些版本已停止维护,我们移除了对应的旧版指标采集器分支定义。

您可以随时获取这些旧版配置文件,用于监控历史版本的 PostgreSQL。

PostgreSQL 版本支持状态
10 ~ 18✅ 完全支持
9.6 及更早⚠️ 需要旧版配置

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

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

3 - 配置参考

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

PG Exporter 使用强大而灵活的配置系统,允许您定义自定义指标、控制采集行为并优化性能。本指南涵盖了从基础设置到高级自定义的所有配置方面。


指标采集器

PG Exporter 使用声明式的 YAML 配置系统,为指标采集提供极大的灵活性和控制能力。本指南涵盖了为您的特定监控需求配置 PG Exporter 的所有方面。


配置概述

PG Exporter 的配置以 采集器 为核心 —— 每个采集器是一个独立的指标查询及其关联元数据。配置可以是:

  • 单一的 YAML 文件(pg_exporter.yml
  • 包含多个 YAML 文件的目录(按字母顺序合并)
  • 通过命令行或环境变量指定的自定义路径

配置加载

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

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

采集器结构

每个采集器是 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、LABEL 或 DISCARD
        rename: metric_name      # 可选:重命名指标
        description: "帮助文本"   # 指标描述
        default: 0               # NULL 时的默认值
        scale: 1000              # 值的缩放因子

核心配置元素

采集器分支名称

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

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只增不减的累计值总事务数
LABEL用作 Prometheus 标签数据库名称
DISCARD忽略此列内部值

缓存控制(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

版本格式:MMMMMMPP00,其中:

  • MMMMMM = 主版本(6 位数字)
  • PP = 次版本(2 位数字)
  • 示例:100000 = 10.0,130200 = 13.2,160100 = 16.1

标签系统

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

内置标签

标签描述
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可选昂贵/可选指标
9xxpgBouncer连接池指标
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}

自定义采集器

创建自己的指标

  1. 在配置目录中创建新的 YAML 文件:
# /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: "平均作业处理时间"}
  1. 测试您的采集器:
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}

性能优化

查询优化技巧

  1. 使用适当的 TTL 值

    • 快速查询:1-10 秒
    • 中等查询:10-60 秒
    • 昂贵查询:300-3600 秒
  2. 设置合理的超时

    • 默认:100ms
    • 复杂查询:500ms-1s
    • 生产环境中不要禁用超时
  3. 使用集群级标签

    tags: [cluster]  # 每集群运行一次,而不是每数据库
    
  4. 禁用昂贵的采集器

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

监控采集器性能

检查采集器执行统计:

# 查看采集器统计
curl http://localhost:9630/stat

# 检查哪些采集器较慢
curl http://localhost:9630/metrics | grep pg_exporter_collector_duration

配置故障排查

验证配置

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

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

常见问题

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

调试日志

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

pg_exporter --log.level=debug

4 - API 参考

PG Exporter 的 HTTP API 端点参考

PG Exporter 提供全面的 REST API,用于指标采集、健康检查、流量路由和运维控制。所有端点都通过配置的端口(默认:9630)以 HTTP 方式暴露。


端点概览

端点方法描述
/metricsGETPrometheus 指标端点
/upGET基本存活检查
/healthGET详细健康状态
/primaryGET主库服务器检查
/replicaGET从库服务器检查
/readGET读流量路由
/reloadGET重新加载配置
/explainGET解释查询规划
/statGET运行时统计

指标端点

GET /metrics

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

请求

curl http://localhost:9630/metrics

响应

# HELP pg_up PostgreSQL server is up and accepting connections
# TYPE pg_up gauge
pg_up 1

# HELP pg_version PostgreSQL server version number
# TYPE pg_version gauge
pg_version 140000

# HELP pg_in_recovery PostgreSQL server is in recovery mode
# TYPE pg_in_recovery gauge
pg_in_recovery 0

# HELP pg_exporter_build_info PG Exporter build information
# TYPE pg_exporter_build_info gauge
pg_exporter_build_info{version="1.1.0",branch="main",revision="abc123"} 1

# ... 更多指标

响应格式

指标遵循 Prometheus 暴露格式:

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

健康检查

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

GET /up

简单的二元健康检查。

响应码

状态码状态描述
200OK导出器和数据库都正常运行
503Service Unavailable数据库宕机或无法访问

示例

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

Kubernetes 存活探针端点。

# 存活探针配置
livenessProbe:
  httpGet:
    path: /liveness
    port: 9630
  initialDelaySeconds: 30
  periodSeconds: 10

GET /readiness

Kubernetes 就绪探针端点。

# 就绪探针配置
readinessProbe:
  httpGet:
    path: /readiness
    port: 9630
  initialDelaySeconds: 5
  periodSeconds: 5

流量路由

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

GET /primary

检查服务器是否为主库(master)实例。

响应码

状态码状态描述
200OK服务器是主库且接受写入
404Not Found服务器不是主库(是从库)
503Service Unavailable服务器宕机

别名

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

响应码

状态码状态描述
200OK服务器是从库且处于恢复状态
404Not Found服务器不是从库(是主库)
503Service Unavailable服务器宕机

别名

  • /standby
  • /slave
  • /read-only
  • /ro

示例

# 检查服务器是否为从库
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

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

响应码

状态码状态描述
200OK服务器正常运行且可以处理读请求
503Service Unavailable服务器宕机

示例

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

运维端点

POST /reload

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

请求

curl -X POST http://localhost:9630/reload

响应

{
  "status": "success",
  "message": "Configuration reloaded successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

响应码

状态码状态描述
200OK配置重新加载成功
500Internal Server Error重新加载失败

使用场景

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

GET /explain

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

请求

curl http://localhost:9630/explain

响应

Collector: pg_stat_database
  Query: SELECT datname, numbackends FROM pg_stat_database
  Tags: [cluster]
  TTL: 10s
  Timeout: 100ms
  Version: 100000-999999
  Status: Active

Collector: pg_stat_replication
  Query: SELECT client_addr, state FROM pg_stat_replication
  Tags: [primary]
  TTL: 5s
  Timeout: 100ms
  Version: 100000-999999
  Status: Active (primary only)

...

GET /stat

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

请求

curl http://localhost:9630/stat

响应

Collector Statistics:
  pg_stat_database:
    Executions: 1234
    Successes: 1230
    Failures: 4
    Avg Duration: 2.5ms
    Last Execution: 2024-01-15T10:29:55Z

  pg_stat_activity:
    Executions: 1234
    Successes: 1234
    Failures: 0
    Avg Duration: 1.2ms
    Last Execution: 2024-01-15T10:29:55Z
...

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


在负载均衡器中使用

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 配置示例

upstream pg_primary {
    server 10.0.0.1:5432;
    server 10.0.0.2:5432 backup;
}

upstream pg_replicas {
    server 10.0.0.2:5432;
    server 10.0.0.3:5432;
}

server {
    listen 5432;

    location / {
        proxy_pass http://pg_primary;
        health_check uri=/primary port=9630;
    }
}

5 - 部署指南

生产环境部署策略与最佳实践

本指南涵盖生产环境的部署策略、最佳实践和实际配置。

pg_exporter 本身可以通过以下方式配置:

  1. 命令行参数(优先级较高)
  2. 环境变量(优先级较低)

指标采集器通过 YAML 配置文件(目录/文件)进行配置:

  • /etc/pg_exporter.yml(默认)
  • /etc/pg_exporter/(包含多个文件的目录)

配置文件使用 YAML 格式,由 采集器定义 组成,指定要采集的指标以及如何采集。


命令行参数

所有配置选项都可以通过命令行标志指定:

pg_exporter \
  --url="postgres://user:pass@localhost:5432/postgres" \
  --config="/etc/pg_exporter/pg_exporter.yml" \
  --web.listen-address=":9630" \
  --auto-discovery \
  --exclude-database="template0,template1" \
  --log.level="info"

运行 pg_exporter --help 获取完整的可用标志列表:

Flags:
  -h, --[no-]help                显示上下文相关帮助(也可尝试 --help-long 和 --help-man)。
  -u, --url=URL                  postgres 目标 URL
  -c, --config=CONFIG            配置目录或文件路径
      --[no-]web.systemd-socket  使用 systemd socket 激活监听器代替端口监听器(仅限 Linux)。
      --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             显示应用程序版本

环境变量

所有命令行参数都有对应的环境变量:

PG_EXPORTER_URL='postgres://:5432/?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

部署架构

最简单的部署方式是每个 PostgreSQL 实例配置一个导出器:

┌─────────────┐     ┌──────────────┐     ┌────────────┐
│ Prometheus  │────▶│ PG Exporter  │────▶│ PostgreSQL │
└─────────────┘     └──────────────┘     └────────────┘
                         :9630                :5432

多数据库环境

使用自动发现来监控多个数据库(默认启用):

┌─────────────┐     ┌────────────────┐     ┌────────────┐
│ Prometheus  │────▶│ PG Exporter    │────▶│ PostgreSQL │
└─────────────┘     │   启用自动发现  │     │  ├─ db1    │
                    │                │     │  ├─ db2    │
                    └────────────────┘     │  └─ db3    │
                                           └────────────┘

生产配置

PostgreSQL 用户设置

创建一个具有最小必要权限的专用监控用户:

-- 创建监控角色
CREATE ROLE pg_monitor WITH LOGIN PASSWORD 'strong_password' CONNECTION LIMIT 5;

-- 授予必要权限
GRANT pg_monitor TO pg_monitor;  -- PostgreSQL 10+ 内置角色
GRANT CONNECT ON DATABASE postgres TO pg_monitor;

-- 对于特定数据库
GRANT CONNECT ON DATABASE app_db TO pg_monitor;
GRANT USAGE ON SCHEMA public TO pg_monitor;

-- 扩展监控的额外权限
GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO pg_monitor;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA pg_catalog TO pg_monitor;

连接安全

使用 SSL/TLS

# 带 SSL 的连接字符串
PG_EXPORTER_URL='postgres://pg_monitor:password@db.example.com:5432/postgres?sslmode=require&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt'

使用 .pgpass 文件

# 创建 .pgpass 文件
echo "db.example.com:5432:*:pg_monitor:password" > ~/.pgpass
chmod 600 ~/.pgpass

# 在 URL 中不使用密码
PG_EXPORTER_URL='postgres://pg_monitor@db.example.com:5432/postgres'

Systemd 服务配置

完整的生产环境 systemd 设置:

[Unit]
Description=Prometheus exporter for PostgreSQL/Pgbouncer server metrics
Documentation=https://github.com/pgsty/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/?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'

服务管理

启动和停止服务

# 启动服务
sudo systemctl start pg_exporter

# 停止服务
sudo systemctl stop pg_exporter

# 重启服务
sudo systemctl restart pg_exporter

# 查看服务状态
sudo systemctl status pg_exporter

# 设置开机自启
sudo systemctl enable pg_exporter

查看日志

# 实时查看日志
journalctl -u pg_exporter -f

# 查看最近的日志
journalctl -u pg_exporter --since "1 hour ago"

# 查看错误日志
journalctl -u pg_exporter -p err

Docker 部署

基本 Docker 运行

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

Docker Compose

version: '3.8'

services:
  pg_exporter:
    image: pgsty/pg_exporter:latest
    container_name: pg_exporter
    restart: unless-stopped
    ports:
      - "9630:9630"
    environment:
      - PG_EXPORTER_URL=postgres://pg_monitor:password@postgres:5432/postgres
      - PG_EXPORTER_AUTO_DISCOVERY=true
      - PG_EXPORTER_EXCLUDE_DATABASE=template0,template1
    volumes:
      - ./pg_exporter.yml:/etc/pg_exporter.yml:ro
    depends_on:
      - postgres

Kubernetes 部署

Deployment 示例

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
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9630"
    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
        - name: PG_EXPORTER_AUTO_DISCOVERY
          value: "true"
        livenessProbe:
          httpGet:
            path: /liveness
            port: 9630
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /readiness
            port: 9630
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          limits:
            cpu: 200m
            memory: 256Mi
          requests:
            cpu: 100m
            memory: 128Mi

Service 示例

apiVersion: v1
kind: Service
metadata:
  name: pg-exporter
  labels:
    app: pg-exporter
spec:
  ports:
  - port: 9630
    targetPort: 9630
    name: metrics
  selector:
    app: pg-exporter

Prometheus 配置

静态配置

scrape_configs:
  - job_name: 'postgresql'
    static_configs:
      - targets:
        - 'pg-exporter-1:9630'
        - 'pg-exporter-2:9630'
        - 'pg-exporter-3:9630'

服务发现

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

监控与告警

推荐的告警规则

groups:
  - name: pg_exporter
    rules:
      # 导出器宕机告警
      - alert: PgExporterDown
        expr: up{job="postgresql"} == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "PG Exporter 宕机"
          description: "{{ $labels.instance }} 的 PG Exporter 已宕机超过 5 分钟"

      # 数据库连接失败告警
      - alert: PostgreSQLDown
        expr: pg_up == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "PostgreSQL 连接失败"
          description: "无法连接到 {{ $labels.instance }} 上的 PostgreSQL"

      # 抓取时间过长告警
      - alert: PgExporterSlowScrape
        expr: pg_exporter_last_scrape_duration_seconds > 30
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "PG Exporter 抓取缓慢"
          description: "{{ $labels.instance }} 的抓取时间超过 30 秒"

6 - 发布注记

PG Exporter 版本发布历史

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

版本日期摘要GitHub
v1.1.02025-12-15更新默认指标采集器,升级到 Go 1.25.5v1.1.0
v1.0.32025-11-20例行更新到 1.25.4,修复不支持的 libpq 环境变量v1.0.3
v1.0.22025-08-14使用 goreleaser 构建更多操作系统架构v1.0.2
v1.0.12025-07-17DockerHub 镜像,Go 1.24.5,禁用 pg_tsdb_hypertablev1.0.1
v1.0.02025-05-06PostgreSQL 18 支持,新增 WAL/检查点/I/O 指标v1.0.0
v0.9.02025-04-26TimescaleDB、Citus、pg_wait_sampling 采集器v0.9.0
v0.8.12025-02-14依赖更新,Docker 镜像标签v0.8.1
v0.8.02025-02-14PgBouncer 1.24 支持,Go 1.24,日志重构v0.8.0
v0.7.12024-12-29例行更新,支持 Reader 配置v0.7.1
v0.7.02024-08-13PostgreSQL 17 支持,谓词查询功能v0.7.0
v0.6.02023-10-18PostgreSQL 16 支持,ARM64 包,安全修复v0.6.0
v0.5.02022-04-27RPM/DEB 构建,列缩放,指标增强v0.5.0
v0.4.12022-03-08采集器更新,connect-timeout 参数v0.4.1
v0.4.02021-07-12PostgreSQL 14 支持,自动发现功能v0.4.0
v0.3.22021-02-01Shadow DSN 修复,文档更新v0.3.2
v0.3.12020-12-04旧版 PostgreSQL 配置修复v0.3.1
v0.3.02020-10-29PostgreSQL 13 支持,REST API,虚拟服务器v0.3.0
v0.2.02020-03-21YUM 包,配置重载支持v0.2.0
v0.1.22020-02-20动态配置重载,批量模式v0.1.2
v0.1.12020-01-10启动挂起 Bug 修复v0.1.1
v0.1.02020-01-08首个稳定版本v0.1.0
v0.0.42019-12-20生产环境测试版本v0.0.4
v0.0.32019-12-14生产环境测试v0.0.3
v0.0.22019-12-09早期测试版本v0.0.2
v0.0.12019-12-06初始版本,支持 PgBouncer 模式v0.0.1

v1.1.0

使用 Go 1.25.5 和最新依赖构建,采集器更新:

采集器变更:

  • pg_setting:针对 PG10-18 兼容性进行重大重构,支持 missing_ok
    • 新增 13 个指标:max_parallel_workersmax_parallel_workers_per_gathermax_parallel_maintenance_workersshared_buffersmaintenance_work_memeffective_cache_sizefsyncfull_page_writesautovacuumautovacuum_max_workerscheckpoint_timeoutcheckpoint_completion_targethot_standbysynchronous_commitio_method
    • work_memory_size 重命名为 work_mem
    • min_version 从 9.6 改为 10,显式 ::int 类型转换
  • pg_size:修复日志目录大小检测,使用 logging_collector 检查代替路径模式匹配
  • pg_table:性能优化,用 JOIN 替换 LATERAL 子查询以提升查询性能;修复 tuplesfrozenxid 指标类型从 COUNTER 改为 GAUGE;超时从 1s 增加到 2s
  • pg_vacuuming:新增 PG17 采集器分支,包含新指标 indexes_totalindexes_processeddead_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_dbpg_indexingpg_clusteringpg_backup 格式对齐修复

其他变更:

校验和

https://github.com/pgsty/pg_exporter/releases/download/v1.0.3/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 环境变量冲突
  • @kadaffyauto-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
    • 移除 writesyncwrite_timesync_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 以降低 CompatiblePostgresPrecheck 复杂度
  • 使用额外数字前缀重命名指标采集器以便排序
  • 升级依赖到最新版本
  • 在所有非致命采集器之前执行致命采集器,快速失败

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


v0.8.1

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 版本重构代码库。

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


v0.6.0

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


v0.4.0

  • 新增 PG 14 支持
  • 默认指标配置全面改进(但您仍可使用旧配置)
  • 新增 auto-discoveryinclude-databaseexclude-database 选项
  • 新增多数据库监控实现(使用 auto-discovery = on

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


v0.3.2

  • 修复 shadow DSN 边界情况
  • 修复拼写错误和文档

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


v0.3.1

修复默认配置问题(特别是低于 13 的版本)

  • 设置 primary_conninfo 在 PG13 之前不存在
  • pg_func 采集器添加 funcid 标签以避免函数名重复标签
  • 修复版本字符串为 pg_exporter

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


v0.3.0

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

  • 更改默认配置,支持 PostgreSQL 13 新指标(pg_slrupg_shmempg_query13pg_backup 等)
  • 新增一系列用于健康/恢复状态检查的 REST API
  • 新增一个带有假 pg_up 0 指标的虚拟服务器,在 PgExporter 初始化之前提供服务
  • 如果未指定 sslmode,向 URL 添加 sslmode=disable
  • 修复拼写错误和 Bug

v0.2.0

  • 新增 yum 包和 Linux 服务定义
  • 在查询配置中新增 ‘skip’ 标志
  • 修复 pgbouncer_up 指标
  • 新增配置重载支持

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


v0.1.2

  • 修复 pgbouncer_up 指标
  • 新增动态配置重载
  • 移除 ‘shard’ 相关逻辑
  • 在默认设置中添加 ‘bulky’ 模式

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


v0.1.1

修复 pg_exporter 在启动时如果任何查询失败会挂起的 Bug。

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


v0.1.0

可以工作了,看起来不错。

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


v0.0.4

在真实生产环境中测试了大约 2 周,200+ 节点。看起来不错!

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


v0.0.3

v0.0.3 发布,在生产环境中测试

此版本已在生产环境中测试。

这个项目仍在快速发展中,如果您想在生产中使用,请谨慎尝试。

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


v0.0.2

现在可以尝试了

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


v0.0.1

新增 pgbouncer 模式

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