postgres_exporter 0.20.1 配置参数详解

postgres_exporter 0.20.1 三层配置入口逐项详解：DATA_SOURCE_* 数据源族（含 *_FILE 文件态凭据）、26 个 collector 开关、行为参数与 0.20.0 后已失效的 disable-default-metrics/metric-prefix 逐条实测，queries.yaml 自定义查询器与 auth_modules 多目标配置，全部结论附真实回显（2026-10-28）。

postgres_exporterpostgres_exporter数据库监控Prometheus2026/10/28

postgres_exporter 0.20.1 配置参数详解

目标：把 postgres_exporter 0.20.1 的三类配置入口（命令行旗标、环境变量、config.file）逐项讲清语义、默认值、生效方式与优先级，关键参数均附 2026-10-28 实测验证与真实回显。安装与 systemd 托管见 B1 安装指南，选型背景见 A1 介绍与选型指南，命令与端点实操见 D1《常用 CLI 命令与工具详解》。

一、参数体系总览与优先级

0.20.1 的配置入口有三层，作用域互不相同：

入口解析器作用域典型内容
命令行旗标kingpin/v2全部行为--web.listen-address、--collector.*、--extend.query-path
环境变量进程环境数据源与部分行为DATA_SOURCE_*、PG_EXPORTER_*
config.file--config.file（默认 postgres_exporter.yml）仅 多目标 auth_modulesauth_modules: 段

优先级规则（README 原文：Settings set by environment variables starting with PG_ will be overwritten by the corresponding CLI flag if given）：同名旗标 > PG_EXPORTER_* 环境变量；--help 输出中每个受环境变量支持的旗标都在括号里标注了对应变量名（如 --web.telemetry-path="/metrics" ... ($PG_EXPORTER_WEB_TELEMETRY_PATH)），这是查对应关系的权威速查表。注意 DATA_SOURCE_* 族没有同名旗标，只能用环境变量或 systemd EnvironmentFile 传递。

⚠️ 一条实测得出的重要提醒：0.20.0 起五类指标转独立 collector 后，PG_EXPORTER_DISABLE_DEFAULT_METRICS 与 PG_EXPORTER_METRIC_PREFIX 对默认指标已实际失效（第五节有逐条实测），旧脚本里依赖这两项的配置在 0.20.1 上不会报错、但也不会生效——"配置不报错"不等于"配置生效"。

二、数据源参数族（DATA_SOURCE_*）

2.1 DATA_SOURCE_NAME（主入口）

兼容两种形态：URI 形态 postgresql://user:pass@host:5432/db?sslmode=disable 与 lib/pq keyword=value 形态 host=10.89.74.10 port=5432 user=exporter password=... sslmode=disable；多个 DSN 用逗号分隔即可同时抓多个实例（README 示例 DATA_SOURCE_NAME="port=5432,port=6432"）。没有旗标对应项，只能经环境变量传递。

sslmode 语义（实测关键点）：lib/pq 缺省 sslmode=require。实测未加该参数直接抓未启用 TLS 的实例：

level=ERROR source=collector.go:191 msg="Error opening connection to database" err="error querying postgresql version: pq: SSL is not enabled on the server"

同时 /metrics 中 pg_up 0、pg_exporter_last_scrape_error 1。内网无 TLS 环境必须显式 ?sslmode=disable；公网/跨网段应改用 verify-full + CA 证书。

2.2 拆分形态与文件态（DATA_SOURCE_URI / USER / PASS 及 *_FILE）

URI、用户名、密码可拆开传，且 USER/PASS 各有 _FILE 变体从文件读取，避免密码进环境变量快照：

变量语义实测
DATA_SOURCE_URI仅主机部分，如 10.89.74.10:5432/appdb?sslmode=disable✅
DATA_SOURCE_USER用户名✅
DATA_SOURCE_PASS密码✅
DATA_SOURCE_URI_FILE / DATA_SOURCE_USER_FILE / DATA_SOURCE_PASS_FILE同上，从文件读✅

实测一（拆分三件套，pg_up 1、pg_exporter_last_scrape_error 0）：

$ DATA_SOURCE_URI='10.89.74.10:5432/appdb?sslmode=disable' \
  DATA_SOURCE_USER=exporter DATA_SOURCE_PASS=exp2026 \
  postgres_exporter --web.listen-address=:8151 &
$ curl -s http://127.0.0.1:8151/metrics | grep -E '^pg_up|^pg_exporter_last_scrape_error'
pg_exporter_last_scrape_error 0
pg_up 1

实测二（echo 'exp2026' > /tmp/pgpass.txt 后改用 DATA_SOURCE_PASS_FILE=/tmp/pgpass.txt，同样 pg_up 1）。文件态配合 chmod 600 是凭据管理的推荐姿势；官方镜像场景 README 还特别提示进程以 uid/gid 65534 运行时的文件属主要求，本文单机 systemd 形态按运行账号属主收紧即可。

三、Web 端点参数

参数默认语义与实测
--web.listen-address:9187监听地址，可重复多次监听多地址（--help 原文 "Repeatable for multiple addresses"）。本文 B1 用 :8150
--web.telemetry-path / PG_EXPORTER_WEB_TELEMETRY_PATH/metrics指标路径。实测设为 /mymetrics 后 /metrics 返回 404、/mymetrics 返回 200
--web.config.file空TLS/Basic 认证配置，格式见 exporter-toolkit 文档（README 链接）
--web.systemd-socketfalsesystemd socket activation 接管监听（Linux）

路径改名实测回显：

$ PG_EXPORTER_WEB_TELEMETRY_PATH=/mymetrics postgres_exporter --web.listen-address=:8153 &
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8153/metrics
404
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8153/mymetrics
200

四、采集器开关族（--collector.*）

4.1 全量清单（--help 实录，26 个）

collector默认采集内容
database启用库清单与 pg_stat_database_conflicts_* 系列事务冲突指标
locks启用pg_locks 锁等待计数
replication启用复制布尔态
replication_slots启用复制槽状态（0.20.0 由 replication_slot 更名）
roles启用角色属性
settings启用pg_settings 全量参数
stat_activity启用会话/等待事件
stat_archiver启用WAL 归档统计
stat_bgwriter启用后台写统计
stat_database启用每库事务/块统计
stat_progress_vacuum启用VACUUM 进度
stat_replication启用流复制延迟
stat_user_tables启用用户表增删改查/死元组
statio_user_tables启用用户表 I/O
wal启用WAL 位置与 pg_ls_waldir
database_wraparound / long_running_transactions / postmaster / process_idle / stat_activity_autovacuum / stat_checkpointer / stat_statements / stat_wal_receiver / statio_user_indexes / xlog_location / buffercache_summary停用库即将回绕预警、长事务、postmaster 生命周期、空闲会话、autovacuum 会话、检查点统计、语句级统计、WAL 接收端、索引 I/O、LSN 位置、缓冲池摘要

开关写法为 [no-]collector.<名>（kingpin 双态语法）：--no-collector.locks 关闭、--collector.stat_statements 打开。默认启用面实测为 15 个 collector、547 条 pg_* 指标（PostgreSQL 16.15 实例）。

4.2 开关生效实测

实测一：--no-collector.locks --no-collector.stat_database --collector.stat_statements 三连改：

locks 行数: 0                       # --no-collector.locks 生效
stat_database 行数: 24              # 主族 pg_stat_database_* 消失
stat_statements 行数: 225           # 新开的语句统计 collector 出数
pg_stat_statements_block_read_seconds_total{datname="appdb",queryid="-1330044169105867050",user="exporter"} 0
pg_scrape_collector_success{collector="stat_statements"} 1

⚠️ 但 pg_stat_database 仍余 24 行——逐行核对全部是 pg_stat_database_conflicts_confl_*，归属第四节的 database collector（默认启用）而非 stat_database。指标族与 collector 不是一一对应，收敛指标面时应按 pg_scrape_collector_success 标签反查归属，避免"关了还在"的误判。

实测二：--collector.stat_statements 需要实例端 CREATE EXTENSION pg_stat_statements（且启动参数含 shared_preload），实测扩展版本 1.10 正常出 225 行指标；该 collector 另有四个子参数：--collector.stat_statements.query_length（语句文本截断长度，默认 120）、--collector.stat_statements.limit（最多返回语句数，默认 100，0.19.0 新增）、--collector.stat_statements.include_query（附带查询文本标签）、--collector.stat_statements.exclude_databases / exclude_users（排除清单，0.19.0 新增）。

五、行为参数与失效项实录

5.1 --collection-timeout / PG_EXPORTER_COLLECTION_TIMEOUT

单轮采集总时长上限，默认 1m，超时断连接防堆积（v0.19.0 引入）。合法值必须 > 1ms，实测 0：

$ PG_EXPORTER_COLLECTION_TIMEOUT=0 postgres_exporter --web.listen-address=:8155
level=WARN source=main.go:137 msg="Failed to create PostgresCollector" err="timeout must be greater than 1ms"
level=INFO source=tls_config.go:372 msg="Listening on" address=[::]:8155

进程照常监听，但 /metrics 只剩 29 条自观测指标（pg_exporter_*、pg_up 等），数据库指标全灭。这是"服务活着却没数据"的经典静默降级，排障时先查这条 WARN。

5.2 已失效项：disable-default-metrics 与 metric-prefix

PG_EXPORTER_DISABLE_DEFAULT_METRICS / --disable-default-metrics：README 语义为"仅输出 queries.yaml 的自定义指标"。实测（0.20.1 + 环境变量置 true，且不带 queries.yaml）：

259 pg_settings      72 pg_stat_database     48 pg_stat_activity
 36 pg_locks         21 pg_stat_user_tables  17 pg_roles
 11 pg_stat_bgwriter  8 pg_statio_user_tables 8 pg_database ...

默认指标一行不少——该开关在 0.20.0 起对独立 collector（settings、stat_activity、stat_archiver、stat_replication、replication_slots）失效（Release 原文：are no longer disabled by --disable-default-metrics. To stop collecting them, disable the corresponding collector explicitly with its --no-collector.* flag），实测进一步表明其余默认族也未再受其控制。0.20.x 收敛指标面的唯一正解是 --no-collector.*。

PG_EXPORTER_METRIC_PREFIX / --metric-prefix：语义为把默认指标前缀从 pg 改为自定义（如 mypg_up）。实测置 mypg 后 /metrics 中 mypg_* 计数 0，pg_up 纹丝不动——同样是 0.20.0 独立 collector 化后不再生效的能力（Release 原文 no longer honor --metric-prefix）。告警/看板如依赖该前缀改名，0.20.x 需另寻方案。

5.3 DEPRECATED 族（仍可用但应规划退出）

参数语义现状
--extend.query-path / PG_EXPORTER_EXTEND_QUERY_PATH加载 queries.yaml 自定义查询DEPRECATED；实测功能稳定，自定义查询链路正常
--auto-discover-databases / PG_EXPORTER_AUTO_DISCOVER_DATABASES按 pg_database 动态发现库并逐一抓取DEPRECATED
--include-databases / --exclude-databases动态发现的白/黑名单DEPRECATED，配合上一项
--constantLabels / PG_EXPORTER_CONSTANT_LABELS全指标附加静态标签DEPRECATED，且独立 collector 已不携带

上游在 queries.yaml 加载时的 WARN：level=WARN source=main.go:94 msg="The extended queries.yaml config is DEPRECATED" file=...；同时 README 建议"泛 SQL 数据源采集"改用 sql_exporter。存量用户建议：新写的自定义指标优先收敛到少量高价值查询，并为将来迁移预留 SQL 脚本。

另有 --dumpmaps（不跑服务、打印内置指标映射后退出，调试 queries.yaml 用，见 D1）与 --log.level（debug/info/warn/error）、--log.format（logfmt/json）两个通用参数。

六、queries.yaml 自定义查询器详解

6.1 格式与命名规则

app_orders_total:                # 查询名（成为指标前缀）
  query: "SELECT count(*) AS rows_total, coalesce(sum(amount),0) AS amount_sum FROM orders"
  metrics:
    - rows_total:                # 列别名（成为指标后缀）
        usage: "GAUGE"           # GAUGE / COUNTER / LABEL / TIMESTAMP 等
        description: "Total rows in orders table"

产出指标名为 <查询名>_<列别名>（app_orders_total_rows_total），并自动附加 server="<DSN 主机:端口>" 标签（实测：app_orders_total_rows_total{server="10.89.74.10:5432"} 500）。LABEL usage 的列转为指标标签（实测 app_db_size_size{datname="appdb",...}）。

6.2 生效方式与权限要求

  • 不热加载：修改 queries.yaml 后必须重启进程才生效（实测改后抓取仍为旧集）。
  • 权限：查询以 DATA_SOURCE_NAME 账号执行，pg_monitor 不含业务表 SELECT。实测未授权时报错并置 pg_exporter_last_scrape_error 1：
level=ERROR source=postgres_exporter.go:606 msg="error scraping dsn" err="queryNamespaceMappings errors encountered, namespace: app_orders_total error: Error running query on database \"10.89.74.10:5432\": app_orders_total pq: permission denied for table orders" dsn="postgresql://exporter:PASSWORD_REMOVED@10.89.74.10:5432/appdb?sslmode=disable"

GRANT SELECT ON orders TO exporter; 后即恢复 500 行计数。注意连接串在日志中自动脱敏（PASSWORD_REMOVED），贴日志无需再手工打码。

  • 坏文件行为：非法 YAML 不会阻止启动，仅首轮抓取时报 level=ERROR source=postgres_exporter.go:564 msg="Failed to reload user queries" path=... err="yaml: line 2: did not find expected key"，自定义指标集体消失、pg_up 仍 1。上线路前用本地 YAML 校验器过一遍。

七、config.file 与多目标（auth_modules）

--config.file 指向的 YAML 只承载一件事：auth_modules，为 /probe 端点预置账号（当前仅 userpass 类型），options 段展开为 DSN 参数。实测配置：

auth_modules:
  lab1:
    type: userpass
    userpass:
      username: exporter
      password: exp2026
    options:
      sslmode: disable

同一进程仍用 DATA_SOURCE_NAME 抓默认实例；对外的第二通道由 Prometheus 请求 /probe?target=10.89.74.10:5432/postgres&auth_module=lab1 触发，实测 HTTP 200、74,999 字节、517 条指标、pg_up 1。多目标参数 relabel 写法与端点行为详见 D1。

八、推荐基线与生效方式速查

单机 systemd 形态的最小推荐配置（含义见前文对应节）：

DATA_SOURCE_NAME=postgresql://exporter:<强口令>@<db-host>:5432/appdb?sslmode=disable

ExecStart=... postgres_exporter \
  --web.listen-address=:8150 \
  --collector.stat_statements \
  --no-collector.statio_user_indexes \
  --log.level=info

生效方式：除 /probe 端点的 target 参数外，其余所有变更均需重启进程（systemd 形态 systemctl restart postgres-exporter）；queries.yaml 与 config.file 都在启动时一次性读取。

九、参考与延伸

  • 本专栏系列：A1 介绍与选型指南、B1 安装指南、D1《常用 CLI 命令与工具详解》。
  • 上游：v0.20.1 README 的 Flags / Environment Variables / Configuration File 三节；v0.20.0 Release 的 BREAKING CHANGES 原文（本文失效项结论的官方依据）；exporter-toolkit web-configuration 文档。
  • 站内延伸（姊妹组件）：pgexporter 0.8.0 配置参数详解。