快速上手

采集第一组 PostgreSQL 指标

安装 PG Exporter，创建监控用户并连接 PostgreSQL，然后把指标端点加入 Prometheus。

准备一台 Linux amd64 主机及本机 PostgreSQL 10 或更新版本，并确认拥有 sudo 和数据库管理员权限。

第 01 步

安装

下载并安装程序与采集器配置。

VERSION=1.5.0
ARCHIVE="pg_exporter-${VERSION}.linux-amd64.tar.gz"
curl -fLO "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/$ARCHIVE" &&
curl -fLO "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/checksums.txt" &&
grep "  $ARCHIVE$" checksums.txt | sha256sum -c - &&
mkdir -p "pg_exporter-${VERSION}" &&
tar -xzf "$ARCHIVE" -C "pg_exporter-${VERSION}" &&
sudo install -m 0755 "pg_exporter-${VERSION}/pg_exporter" /usr/local/bin/pg_exporter &&
sudo install -m 0644 "pg_exporter-${VERSION}/pg_exporter.yml" /etc/pg_exporter.yml &&
pg_exporter --version

校验结果应为 OK，安装后的版本应为 v1.5.0。

其他平台与软件包安装方式见下载页。

第 02 步

创建监控用户

以数据库管理员身份连接 PostgreSQL：

sudo -u postgres psql -d postgres

将 change-me 替换为实际密码，然后创建监控角色：

CREATE USER monitor WITH PASSWORD 'change-me';
GRANT pg_monitor TO monitor;

PostgreSQL 10–13 还须在主连接数据库（本例为 postgres）执行：

GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor;

PG14+ 在标准目录 ACL 下不需要这项额外授权；该授权不会开放订阅密码。

输入 \q 返回 Shell。下一步连接 URL 使用相同的密码。

第 03 步

启动并验证

在前台启动导出器，HTTP 端口仅监听本机。

URL 中的密码若包含保留字符，需要进行百分号编码，例如将 # 写为 %23。

export PG_EXPORTER_URL='postgres://monitor:[email protected]:5432/postgres?sslmode=disable'
pg_exporter --config=/etc/pg_exporter.yml --web.listen-address=127.0.0.1:9630

在另一个终端执行：

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

远程数据库、TLS 和密码文件的配置见生产部署。

输出示例

pg_up 1 表示主数据库抓取没有致命错误。下面是 PostgreSQL 17 主库的输出示例。

PostgreSQL 可用性、版本与恢复状态指标

pg_up 1
pg_version 170000
pg_in_recovery 0

第 04 步

加入 Prometheus 抓取目标

在 prometheus.yml 中添加以下抓取目标。本例中 Prometheus 也运行在同一台主机上。

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

重载 Prometheus，在 Targets 页面确认目标状态为 UP。如果 Prometheus 位于另一台主机，请按生产部署配置可达的监听地址与目标地址。

使用 Pigsty 仪表盘查看指标，或访问在线演示。

故障排查

检查采集结果

用日志定位连接错误，用 /explain 查看已选查询，用 /stat 检查查询统计。

为什么 pg_up 为 0？

查看导出器日志，检查主机、端口、数据库、凭据和 pg_hba.conf。致命采集器错误也会使 pg_up 为 0。

故障排查指南

为什么有些指标缺失？

通过 /explain 查看主数据库已选中的采集器，对照目标检查版本限制、标签和 SQL。通过 /stat 查看报错次数与指标数量，具体错误见导出器日志。

故障排查指南

接下来

下一步

运维

生产部署

通过 systemd、Docker 或 Kubernetes 运行服务。

阅读

配置

采集器配置

添加查询并定义指标。

阅读

加固

安全指南

配置数据库权限、密码和 TLS。

阅读