pgwatch v6：让 Prometheus 成为指标来源，而不只是输出目标

预计阅读时间：8 分钟

pgwatch v6.0.0-beta 带来了一个重要变化：它现在可以直接抓取 Prometheus exporter，把 Prometheus 文本格式的指标作为一等数据源，与 PostgreSQL 数据源并列采集。这样，数据库内部状态和数据库外部环境信息就能进入同一个指标存储系统。

PostgreSQL 看不到的状态，也能纳入采集

pgwatch 的传统模式是执行针对 pg_stat_* 视图的 SQL 查询，并把结果保存为测量值。这对于连接数、锁、缓存命中率和复制状态等 PostgreSQL 自身能够提供的信息很有效。

但高可用环境中有一批关键状态并不属于 PostgreSQL 的观测范围，例如：

Patroni 当前认定的主库和副本角色；
Patroni 看到的复制延迟；
DCS 最近一次心跳时间；
节点是否需要重启；
node_exporter 提供的磁盘 I/O 和主机资源指标。

过去，这些指标通常需要由另一个采集系统负责。v6 将 Prometheus endpoint 直接接入 pgwatch，减少了旁路组件和额外的指标存储路径。

用 Prometheus source 接入 exporter

Prometheus source 的配置形式与 PostgreSQL source 相似，只是连接信息从 DSN 变成了 metrics URL。下面是一个可以改造的 Patroni 配置：

sources:
  - name: patroni-prod-node1
    kind: prometheus
    conn_str: "http://patroni-node1:8008/metrics"
    preset_metrics: patroni
    custom_tags:
      cluster: prod
      node: dc1-alpha
    is_enabled: true

conn_str 可以指向任何提供 Prometheus text exposition format 的 endpoint。内置的 patroni preset 覆盖多个常用指标族，例如：

patroni_primary
patroni_replica
patroni_xlog_location
patroni_dcs_last_seen
patroni_pending_restart

也可以显式指定指标族和采集间隔。下面的配置展示了更精细的控制方式，具体字段名称和配置结构应以当前 beta 版本的配置文档为准：

sources:
  - name: node1-exporter
    kind: prometheus
    conn_str: "http://node1:9100/metrics"
    custom_metrics:
      - name: node_cpu_seconds_total
        interval: 60s
      - name: node_disk_io_time_seconds_total
        interval: 60s
    custom_tags:
      cluster: prod
      node: dc1-alpha
    is_enabled: true

如果没有配置任何指标，pgwatch 会尝试抓取 exporter 暴露的全部指标族，默认间隔为 60 秒。这适合探索一个陌生 exporter，但不建议直接用于长期生产配置，因为指标族数量可能持续增长，最终在下游生成大量测量表或字段。

一个 HA 集群可以统一管理

三节点 Patroni 集群可以在同一个配置文件中声明为三个 Prometheus source：

sources:
  - name: patroni-prod-node1
    kind: prometheus
    conn_str: "http://patroni-node1:8008/metrics"
    preset_metrics: patroni
    custom_tags:
      cluster: prod
      node: dc1-alpha
    is_enabled: true

  - name: patroni-prod-node2
    kind: prometheus
    conn_str: "http://patroni-node2:8008/metrics"
    preset_metrics: patroni
    custom_tags:
      cluster: prod
      node: dc1-beta
    is_enabled: true

  - name: patroni-prod-node3
    kind: prometheus
    conn_str: "http://patroni-node3:8008/metrics"
    preset_metrics: patroni
    custom_tags:
      cluster: prod
      node: dc2-single
    is_enabled: true

  - name: app-db
    kind: postgres
    conn_str: "postgres://monitor@db-prod:5432/app"
    is_enabled: true

custom_tags 会写入该 source 产生的每个数据点。仪表盘因此可以直接按 cluster 或 node 分组和筛选，不需要为每个 Patroni endpoint 编写额外查询。

更重要的是，SQL 采集结果和 Prometheus 采集结果可以写入同一个 sink。运维人员可以在同一套观测数据中关联数据库内部指标、集群管理器状态和主机资源指标。

指标名称和标签如何落库

Prometheus source 不依赖 pgwatch 的 SQL 指标目录。custom_metrics 中的指标族名称会原样用于采集键和结果中的数值列。例如，采集 node_cpu_seconds_total 时，样本值会进入同名字段。

映射规则可以概括为：

Prometheus 指标族名称保留原名；
每个 Prometheus label 转换为 tag_<label> 列；
样本数值写入以指标族命名的列；
epoch_ns 优先使用 exporter 提供的样本时间戳；
exporter 未提供时间戳时，使用当前时间；
+Inf、-Inf 和 NaN 会原样传递。

最后一条需要特别注意：pgwatch 不会替 exporter 重新解释特殊浮点值，但下游 sink 可能使用严格的数值类型。如果目标存储无法接受这些值，写入阶段仍可能失败。

TLS、认证和 Prometheus sink 的兼容性

Prometheus endpoint 可以使用 Basic Auth 和 TLS。例如：

sources:
  - name: patroni-secure
    kind: prometheus
    conn_str: "https://metrics_user:change-me@patroni-node1:8008/metrics?tlsskipverify=true"
    tlsrootcert: "/etc/pgwatch/certs/ca.pem"
    preset_metrics: patroni
    is_enabled: true

tlsrootcert 和 tlsskipverify 会在请求发出前从连接参数中剥离，不会作为普通 URL 参数泄漏给 exporter。密码也会在日志中脱敏，因此排查 source 时不会因为搜索名称而意外暴露凭据。

如果 sink 本身是 Prometheus，来自 Prometheus source 的测量会使用原始指标族名称重新暴露，而不会再套上 pgwatch 默认的 pgwatch_ 前缀。比如从 postgres_exporter 抓取的 pg_stat_activity_count，输出时仍然是 pg_stat_activity_count。已有的 Prometheus 仪表盘可以继续使用原指标名。

Beta 版本的落地建议

Prometheus source 仍处于 beta 阶段，建议按以下顺序采用：

先接入 staging exporter，确认网络、认证和 TLS 配置；
显式配置需要的指标族，避免一开始抓取全部指标；
检查标签数量，防止高基数标签扩大存储和查询成本；
验证 NaN、无穷大和 exporter 时间戳在 sink 中的处理方式；
观察 pgwatch 日志和下游数据，再接入生产仪表盘。

pgwatch v6 的方向很明确：Prometheus 不再只是 pgwatch 的输出目标，也可以成为数据库观测链路中的输入来源。对于 Patroni、postgres_exporter 和 node_exporter 并存的环境，这让多来源指标进入同一套采集配置成为可能；但在 beta 阶段，仍应控制指标范围，并把存储容量、标签基数和异常浮点值纳入上线检查。