pgSCV 配置参数详解

pgSCV 0.15.3 配置体系逐项实测：文件+环境变量双层加载与覆盖规则、listen_address/services/authentication(TLS+Basic)/no_track_mode/collect_top_*/concurrency_limit/conn_timeout/refresh_service_config_interval/skip_conn_error_mode/url_prefix 等全部参数语义与默认值、配置失败注入实录、filters 与 custom 自定义指标实测。

pgSCVpgSCVPostgreSQLPrometheus监控可观测性2026/10/28

pgSCV 配置参数详解

本文是 pgSCV 系列第三篇，逐项讲清 pgSCV 0.15.3 配置体系：YAML 主配置文件、环境变量、命令行参数三层的加载与覆盖关系，每个参数的语义、默认值、生效方式与验证方法。除特别说明外，所有「实测」结论均在 Ubuntu 22.04 + PostgreSQL 16.15 + pgSCV 0.15.3 环境执行验证，配置解析行为与源码 internal/pgscv/config.go 对照一致。

一、配置加载模型：文件 + 环境变量双层合并

pgSCV 启动时按固定顺序读配置，先文件后环境变量，环境变量可覆盖文件中的同名项：

root@pgscv-lab:~# journalctl -u pgscv --no-pager -n 10 | grep -E 'read configuration'
{"level":"info",...,"message":"reading file information /etc/pgscv.yaml"}
{"level":"info",...,"message":"read configuration from /etc/pgscv.yaml"}
{"level":"info",...,"message":"read configuration from environment"}

合并规则（实测 + 源码确认）：

  • listen_address、no_track_mode、skip_conn_error_mode、conn_timeout、collect_top_* 等标量：环境变量非零/非空即覆盖文件值；
  • services：环境变量形态（DATABASE_DSN 等）与文件条目按 service_id 合并；
  • disable_collectors：文件列表与环境变量列表取并集；
  • PGSCV_DATABASES：文件里 databases 非空时文件优先，并输出 debug 提示「PGSCV_DATABASES environment setting was ignored」；
  • 完全没有文件时（不传 --config-file），纯环境变量也能拉起完整服务（实测见第四节）。

配置文件为 YAML，官方 deb 自带样例 /etc/pgscv.yaml（3501 字节，640 权限，属主 postgres）带全套注释示例，建议以它为底稿裁剪。注意样例文件带 UTF-8 BOM，实测不影响解析。

二、全局参数逐项详解

以下每个参数均给出：YAML 键 / 对应环境变量 / 默认值 / 语义 / 实测验证。

listen_address

  • YAML：listen_address；环境变量：PGSCV_LISTEN_ADDRESS；默认：127.0.0.1:9890。
  • HTTP 监听地址，承载 /metrics、/targets、/flush-services-config 三个端点。
  • 实测：改为 0.0.0.0:9890 后日志输出 listen on http://0.0.0.0:9890；纯环境变量方式将 PGSCV_LISTEN_ADDRESS=127.0.0.1:9899 注入无配置进程，实测监听 9899 且 /targets 正常返回。

services（服务清单）

  • YAML：services；环境变量：POSTGRES_DSN*/DATABASE_DSN*（postgres）、PGBOUNCER_DSN*（pgbouncer）、PATRONI_URL*（patroni）。
  • 被监控服务定义，键为 service_id，值含 service_type（postgres/pgbouncer/patroni 三选一）与 conninfo（patroni 用 baseurl）。
  • conninfo 校验只做 pgx 语法解析，不做连通性检查——语法错才导致启动失败，连不上只告警（实测：指向 9999 端口的合法 conninfo 可正常启动，日志 warn 后 skip）。
  • 可选 target_labels 子项（如 __scrape_interval__、__scrape_timeout__）随 /targets 下发给 Prometheus 控制单目标抓取节奏。
  • 实测：DATABASE_DSN='postgres://pgscv:***@127.0.0.1:5432/postgres' 无配置文件启动，日志显示 registered new service [postgres]（纯 env 方式 service_id 由 DSN 主机端口推断）。

authentication（HTTP 认证与 TLS）

  • YAML：authentication；环境变量：PGSCV_AUTH_USERNAME/PGSCV_AUTH_PASSWORD/PGSCV_AUTH_KEYFILE/PGSCV_AUTH_CERTFILE。
  • username/password 启用 HTTP Basic；keyfile/certfile 启用 HTTPS（私钥/证书 PEM 路径，属主需为运行用户可读，实测 chmod 600 后服务正常加载）。
  • 实测（组合开启 Basic + 自签 TLS）：
# 无凭据访问 → 401；正确凭据 → 200；错误口令 → 401
# https + 正确凭据 → 200
# 用明文 http 打 TLS 监听 → 400，日志：http: TLS handshake error ... client sent an HTTP request to an HTTPS server
  • 注意：认证仅保护 /metrics，/targets 实测不要求凭据（200），暴露面评估时需计入。

no_track_mode（敏感信息脱敏）

  • YAML：no_track_mode；环境变量：PGSCV_NO_TRACK_MODE；默认：false。
  • 开启后 statements 采集器不上报 pg_stat_statements.query 查询文本，避免敏感 SQL 入库。
  • 实测：no_track_mode: true 启动日志输出 no-track enabled for [pg_stat_statements.query].；关闭时输出 no-track disabled, for details check the documentation about 'no_track_mode' option.。布尔解析接受 y/yes/t/true/1/on 及其否定形式（源码 toBool）。

collect_top_query / collect_top_table / collect_top_index

  • 环境变量：PGSCV_COLLECT_TOP_QUERY/PGSCV_COLLECT_TOP_TABLE/PGSCV_COLLECT_TOP_INDEX；默认：0（不限量）。
  • 分别限制 statements / tables / indexes 采集器上报的 Top-N 元素数，取值 0–1000，防大库全量刷指标。
  • 实测：设 10 后日志逐条确认 option collect_top_query is enabled (limited top-10 queries)、option collect_top_table is enabled (limited top-10 tables)；设 1001 触发启动失败：
validate config failed: invalid setting 'collect_top_query' or env PGSCV_COLLECT_TOP_QUERY (value '1001'), allowed 0 to 1000
  • 已知瑕疵（上游源码如此）：collect_top_index 的确认日志打的是「limited top-N indexes」但前缀误写为 option collect_top_table is enabled，不影响功能。

concurrency_limit（采集并发上限）

  • YAML：concurrency_limit；环境变量：PGSCV_CONCURRENCY_LIMIT；默认：无限制。
  • 限制同一时刻并行执行的采集器数量，控制对数据库的采集压力。
  • 实测：concurrency_limit: 3 → 日志 option concurrency_limit is enabled (limited 3 concurrency collectors)。

conn_timeout（连接超时）

  • YAML：conn_timeout；环境变量：PGSCV_CONN_TIMEOUT；默认：无（pgx 默认）。
  • 单位秒，控制到各服务的连接建立超时；网络质量差的目标库建议显式设置。
  • 实测：conn_timeout: 3 → 日志 option conn_timeout is enabled (set 3 seconds timeout)。

refresh_service_config_interval（服务配置自动刷新）

  • YAML：refresh_service_config_interval；环境变量：PGSCV_REFRESH_SERVICE_CONFIG_INTERVAL；默认：0（不自动刷新）。
  • Go duration 格式（如 2h、10m），定时重读服务连接配置；手动刷新用 POST /flush-services-config（实测返回 {"Status":"OK"}）。
  • 实测：非法 duration 会被环境变量解析层拒绝：invalid setting PGSCV_REFRESH_SERVICE_CONFIG_INTERVAL, value 'xxx'。

skip_conn_error_mode（跳过连接错误）

  • YAML：skip_conn_error_mode；环境变量：PGSCV_SKIP_CONN_ERROR_MODE；默认：false。
  • 默认行为：启动时连接失败的服务不注册（warn + skip，其余服务正常）；开启后：失败服务仍然注册，进入周期重试，期间日志 error update service config failed: failed to connect ...。
  • 实测对比：同一份含 dead:1（9999 端口）与 live:1 的配置，默认模式日志为 registered new service [live:1]（dead 被 skip）；开启后日志出现 registered new service [dead:1]。适合目标库可能晚于采集器启动的部署拓扑。

url_prefix（反代路径前缀）

  • YAML：url_prefix；环境变量：PGSCV_URL_PREFIX；默认：空。
  • 语义：改写 /targets 返回的抓取 URL 前缀，服务于反向代理/路径型网关场景。
  • 实测：设 url_prefix: "example.com" 后 /targets 返回 ["example.com/metrics?target=system:0","example.com/metrics?target=live:1"]；HTTP 层对任意路径后缀 /metrics 均可命中 handler，因此该参数不影响本机 curl 直连。

throttling_interval（抓取节流，已废弃）

  • YAML：throttling_interval；环境变量：PGSCV_THROTTLING_INTERVAL；默认：0。
  • 同一 target 两次抓取之间的最小间隔（秒），防多 Prometheus 重复抓取压垮数据库。
  • 实测：设 25 → 日志 Option 'throttling_interval' is deprecated and removed in next major release.（该参数已进废弃期，新部署建议用 Prometheus 侧 scrape_interval 控制）。

databases（库名过滤，已废弃）

  • YAML：databases；环境变量：PGSCV_DATABASES；默认：.+。
  • 按正则过滤统计类指标覆盖的数据库；启动日志固定输出 option 'databases' is deprecated and removed in next major release.。替代方案见第五节的 collectors.filters。

defaults（默认连接参数）

  • YAML：defaults；默认：postgres_username=pgscv、postgres_dbname=postgres、pgbouncer_username=pgscv、pgbouncer_dbname=pgbouncer。
  • 当 services 条目的 conninfo 未显式给出用户/库名时的兜底值。生产建议在 conninfo 里写全，避免隐式默认。

disable_collectors（采集器禁用列表）

  • YAML：disable_collectors；环境变量：PGSCV_DISABLE_COLLECTORS（逗号分隔）。
  • 可禁用约 40 个内建采集器，粒度为 系统/采集器名，如 postgres/tables、system/sysinfo；system 整族也可整体禁用。
  • 实测：加入 postgres/tables 前后 postgres_* 指标族从 132 → 113，postgres_table_* 归零；采集器名写错不会报错（不存在的名字无匹配效果），改名/删名升级时需回归验证。

三、命令行参数（三层配置的最外层）

pgscv --help 实测输出：

usage: pgscv [<flags>]

Flags:
  --[no-]help         Show context-sensitive help (also try --help-long and --help-man).
  --[no-]version      show version and exit
  --log-level="info"  set log level: debug, info, warn, error ($LOG_LEVEL)
  --config-file=""    path to config file ($PGSCV_CONFIG_FILE)
  • --config-file：主配置路径；deb 环境由 /etc/default/pgscv 的 ARGS 注入。指向目录/不存在文件直接启动失败（lstat ...: no such file or directory，exit 1）。
  • --log-level：debug/info/warn/error 四档；debug 会输出采集器逐个启用日志（enable postgres/logs 等）与 DSN 明文（含口令），生产勿常开。
  • deb 环境修改参数的标准姿势：编辑 /etc/default/pgscv，如 ARGS='--config-file=/etc/pgscv.yaml --log-level=warn'，然后 systemctl restart pgscv。

四、配置验证：失败注入实录

pgSCV 校验失败即拒启（exit 1），以下均在实测环境复现：

注入实测回显（截要）
配置文件不存在create config failed: lstat /nonexistent.yaml: no such file or directory
YAML 语法错create config failed: yaml: line 1: did not find expected ',' or ']'
collect_top_query=1001validate config failed: invalid setting 'collect_top_query' ... allowed 0 to 1000
采集器名带连字符 postgres/custom-1validate config failed: invalid collector name: postgres/custom-1
conninfo 语法错validate config failed: invalid conninfo for <id>: ...

无配置且无环境变量裸跑会直接退出：日志 received shutdown signal: 'no services defined'——pgSCV 不允许零服务运行（system 自动服务也依赖配置加载流程）。

五、采集器级配置：filters 与 custom

collectors 段支持两类精细控制。

filters（按标签值过滤）：

collectors:
  postgres/databases:
    filters:
      database:
        exclude: "^benchdb$"

实测注意：filters 的键是采集器 SQL 结果列名（经 AS 别名后），不是指标标签名。postgres/databases 采集器查询把 datname 别名为 database，写 datname: 时 benchdb 依旧上报，改 database: 后 postgres_database_size_bytes{database="benchdb"} 消失、其余保留。include/exclude 可单用可组合。

custom（自定义指标）：

collectors:
  postgres/custom:
    subsystems:
      tablesizing:
        databases: ".+"
        query: "select schemaname, relname, n_live_tup, n_dead_tup from pg_stat_user_tables"
        metrics:
          - name: live_tuples
            usage: GAUGE
            value: n_live_tup
            labels: [schemaname, relname]
            description: "Estimated number of live rows."

实测输出：

postgres_tablesizing_live_tuples{database="benchdb",host="127.0.0.1",port="5432",relname="pgbench_accounts",schemaname="public",service_id="postgres:5432"} 500000

规则与校验（错误均致拒启，实测确认）：指标名限 [a-zA-Z0-9_]；usage 仅 COUNTER/GAUGE；value 与 labeled_values 二选一；有 metrics 必须有 query；子系统名限 [a-zA-Z0-9_]+；最终指标名为 <子系统名>_<指标名> 且自动附加 database/host/port/service_id 标签。

六、一份生产级完整配置示例

listen_address: 0.0.0.0:9890

authentication:
  username: monitoring
  password: "<强口令>"
  keyfile:  /etc/ssl/pgscv/pgscv.key
  certfile: /etc/ssl/pgscv/pgscv.crt

no_track_mode: true          # 不采集 SQL 文本
collect_top_query: 10
collect_top_table: 10
collect_top_index: 10
concurrency_limit: 5
conn_timeout: 3
skip_conn_error_mode: true   # 目标库允许晚启动
refresh_service_config_interval: 2h

services:
  "postgres:5432":
    service_type: "postgres"
    conninfo: "postgres://pgscv:<口令>@127.0.0.1:5432/postgres"
  "pgbouncer:6432":
    service_type: "pgbouncer"
    conninfo: "postgres://pgscv:<口令>@127.0.0.1:6432/pgbouncer"

disable_collectors:
  - system/sysconfig

collectors:
  postgres/databases:
    filters:
      database:
        exclude: "^(template0|template1)$"

生效方式统一为 systemctl restart pgscv（配置无 reload 信号支持；服务级动态部分用 /flush-services-config）。

七、本系列导航