prometheuscommunity/postgres-exporter

PostgreSQL Server Exporter

镜像概述和主要用途

PostgreSQL Server Exporter是一个Prometheus exporter，用于收集PostgreSQL服务器的指标。它能够从PostgreSQL数据库实例中提取各种性能和状态指标，并以Prometheus可抓取的格式暴露这些指标，便于监控和告警。

CI测试过的PostgreSQL版本：13、14、15、16、17。

核心功能和特性

• 收集多种PostgreSQL性能指标，包括数据库统计、连接数、复制状态、锁信息等
• 支持通过环境变量或配置文件配置数据库连接
• 多目标支持（BETA），可从单个exporter实例监控多个PostgreSQL实例
• 可配置的指标收集器，支持启用/禁用特定指标集
• 支持TLS和基本身份验证保护指标端点
• 容器化部署，使用非root用户运行，增强安全性

使用场景和适用范围

• PostgreSQL数据库服务器的性能监控
• 数据库健康状态检查和告警
• 性能瓶颈分析和容量规划
• 多数据库实例集中监控
• 云环境或容器化环境中的PostgreSQL监控

详细的使用方法和配置说明

快速开始

该软件包提供Docker镜像：

bash
# 启动示例数据库
docker run --net=host -it --rm -e POSTGRES_PASSWORD=password postgres

# 连接到数据库
docker run \
  --net=host \
  -e DATA_SOURCE_URI="localhost:5432/postgres?sslmode=disable" \
  -e DATA_SOURCE_USER=postgres \
  -e DATA_SOURCE_PASS=password \
  quay.io/prometheuscommunity/postgres-exporter

测试指标暴露：

bash
curl "http://localhost:9187/metrics"

Prometheus配置示例：

yaml
scrape_configs:
  - job_name: postgres
    static_configs:
      - targets: ["127.0.0.1:9187"]  # 如果在独立网络中运行容器，请将IP替换为docker容器的主机名

建议使用DATA_SOURCE_PASS_FILE配合挂载文件来存储密码，避免将密码存储在环境变量中。容器进程使用uid/gid 65534运行（对文件权限很重要）。

多目标支持（BETA）

此功能处于测试阶段，未来版本可能会有变化。欢迎提供反馈。

该exporter支持多目标模式。这允许运行单个exporter实例来监控多个PostgreSQL目标。此功能是可选的，适用于无法将exporter作为sidecar安装的场景，例如SaaS托管服务。

要使用多目标功能，向端点/probe?target=foo:5432发送HTTP请求，其中target设置为要抓取指标的PostgreSQL实例的DSN。

为避免在URL中包含用户名和密码等敏感信息，通过配置文件的auth_modules部分支持预配置的身份验证模块。通过指定?auth_module=fooHTTP参数，可以在/probe端点使用DSN的auth_modules。

Prometheus配置示例：

yaml
scrape_configs:
  - job_name: 'postgres'
    static_configs:
      - targets:
        - server1:5432
        - server2:5432
    metrics_path: /probe
    params:
      auth_module: [foo]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9116  # postgres exporter的实际主机名:端口

配置文件

配置文件控制exporter的行为。可以使用--config.file命令行标志设置，默认为postgres_exporter.yml。

auth_modules

此部分定义用于多目标端点的预设身份验证和连接参数。auth_modules是模块映射，键是可在/probe端点中使用的标识符。目前仅支持userpass类型。

示例：

yaml
auth_modules:
  foo1:  # 可设置为任何名称
    type: userpass
    userpass:
      username: first
      password: firstpass
    options:
      # 选项将成为DSN的key=value参数
      sslmode: disable

构建和运行

bash
git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter
make build
./postgres_exporter <flags>

构建Docker镜像：

bash
make promu
promu crossbuild -p linux/amd64 -p linux/armv7 -p linux/arm64 -p linux/ppc64le
make docker

这将构建名为prometheuscommunity/postgres_exporter:${branch}的Docker镜像。

命令行标志

环境变量

以下环境变量用于配置exporter：

以PG_开头的环境变量设置的配置，如果给定了相应的CLI标志，将被CLI标志覆盖。

设置PostgreSQL服务器的数据源名称

PostgreSQL服务器的数据源名称必须通过DATA_SOURCE_NAME环境变量设置。

对于在默认Debian/Ubuntu安装上本地运行，以下命令将起作用（可相应地转换为init脚本）：

bash
sudo -u postgres DATA_SOURCE_NAME="user=postgres host=/var/run/postgresql/ sslmode=disable" postgres_exporter

此外，可以设置源列表以从一个exporter设置中抓取不同的实例。只需定义一个逗号分隔的字符串：

bash
sudo -u postgres DATA_SOURCE_NAME="port=5432,port=6432" postgres_exporter

有关格式化连接字符串的其他方式，请参见http://github.com/lib/pq%E6%A8%A1%E5%9D%97%E3%80%82

以非超级用户身份运行

要能够以非超级用户身份从PostgreSQL服务器版本>=10的pg_stat*视图收集指标，可以将pg_monitor或pg_read_all_stats内置角色授予该用户。如果需要监控较旧的PostgreSQL服务器，必须以超级用户身份创建函数和视图，并单独为这些用户分配权限。

sql
-- 要使用IF语句，因此能够在尝试创建用户之前检查用户是否存在，
-- 我们需要切换到过程SQL（PL/pgSQL）而不是标准SQL。
-- 更多信息：https://www.postgresql.org/docs/9.3/plpgsql-overview.html
-- 为了保持与<9.0的兼容性，不使用DO块；而是创建并删除一个函数。
CREATE OR REPLACE FUNCTION __tmp_create_user() returns void as $
BEGIN
  IF NOT EXISTS (
          SELECT                       -- 为此，SELECT列表可以为空
          FROM   pg_catalog.pg_user
          WHERE  usename = 'postgres_exporter') THEN
    CREATE USER postgres_exporter;
  END IF;
END;
$ language plpgsql;

SELECT __tmp_create_user();
DROP FUNCTION __tmp_create_user();

ALTER USER postgres_exporter WITH PASSWORD 'password';
ALTER USER postgres_exporter SET SEARCH_PATH TO postgres_exporter,pg_catalog;

-- 如果以非超级用户部署（例如在AWS RDS中），取消下面的GRANT行注释并将<MASTER_USER>替换为您的root用户。
-- GRANT postgres_exporter TO <MASTER_USER>;

GRANT CONNECT ON DATABASE postgres TO postgres_exporter;

如果使用PostgreSQL版本>=10，运行以下命令：

sql
GRANT pg_monitor to postgres_exporter;

仅当使用早于10的PostgreSQL版本时，运行以下SQL命令。在PostgreSQL中，视图以创建它们的用户的权限运行，因此它们可以充当安全屏障。需要创建函数来与非超级用户共享此数据。仅创建视图会遗漏最重要的数据位。

sql
CREATE SCHEMA IF NOT EXISTS postgres_exporter;
GRANT USAGE ON SCHEMA postgres_exporter TO postgres_exporter;

CREATE OR REPLACE FUNCTION get_pg_stat_activity() RETURNS SETOF pg_stat_activity AS
$ SELECT * FROM pg_catalog.pg_stat_activity; $
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter.pg_stat_activity
AS
  SELECT * from get_pg_stat_activity();

GRANT SELECT ON postgres_exporter.pg_stat_activity TO postgres_exporter;

CREATE OR REPLACE FUNCTION get_pg_stat_replication() RETURNS SETOF pg_stat_replication AS
$ SELECT * FROM pg_catalog.pg_stat_replication; $
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter.pg_stat_replication
AS
  SELECT * FROM get_pg_stat_replication();

GRANT SELECT ON postgres_exporter.pg_stat_replication TO postgres_exporter;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE OR REPLACE FUNCTION get_pg_stat_statements() RETURNS SETOF pg_stat_statements AS
$ SELECT * FROM public.pg_stat_statements; $
LANGUAGE sql
VOLATILE
SECURITY DEFINER;

CREATE OR REPLACE VIEW postgres_exporter.pg_stat_statements
AS
  SELECT * FROM get_pg_stat_statements();

GRANT SELECT ON postgres_exporter.pg_stat_statements TO postgres_exporter;

注意
请记住在连接字符串中使用postgres数据库名称：

DATA_SOURCE_NAME=postgresql://postgres_exporter:password@localhost:5432/postgres?sslmode=disable

Docker部署方案示例

使用docker run部署

基本部署：

bash
docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \
  -e DATA_SOURCE_URI="postgres:5432/postgres?sslmode=disable" \
  -e DATA_SOURCE_USER=postgres_exporter \
  -e DATA_SOURCE_PASS=secure_password \
  quay.io/prometheuscommunity/postgres-exporter

使用密码文件部署：

bash
# 创建密码文件
echo "secure_password" > /path/to/passfile
chmod 600 /path/to/passfile

# 运行容器，挂载密码文件
docker run -d \
  --name postgres-exporter \
  -p 9187:9187 \
  -e DATA_SOURCE_URI="postgres:543