pgwatch 监控

Prometheus 体系胜在生态通用，Zabbix 胜在企业纳管，但两者的 PostgreSQL 语义都要靠模板与自定义查询自己拼——看板得自己画、指标语义得自己注释、版本升级的适配得自己扛。如果你想要一个为 PostgreSQL 而生、开箱即用又可深度定制的监控工具，来自 CYBERTEC 公司（PostgreSQL 咨询领域的老牌厂商）的开源项目 pgwatch 值得放在候选名单的第一梯队。

pgwatch 的设计哲学可以概括为三句话：采集用 SQL 定义（每个 metric 就是一段返回键值对的 SQL，会写 SQL 就能加监控指标）；看板不重复造轮子（指标存进时序库，可视化直接用 Grafana，官方预置整套看板）；部署不侵入数据库（采集端通过普通 SQL 连接读取统计视图即可工作，不在数据库服务器上安装 agent）。这三条让它成为「DBA 团队自己搭监控」场景里上手最快的方案之一——从零到第一张看板通常只要十几分钟。

本页讲清 pgwatch 的项目沿革与架构、部署方式、被监控库的接入、metric 与 preset 体系、自定义指标、看板与告警，并与前面几页的方案做定位对比。项目近两年迭代很快（v3 用 Go 重写、v4 于 2025 年发布），本页以概念与运维方法论为主，具体配置参数名、环境变量、preset 名称随版本变化，落地时以所用版本的官方文档为准。

前置知识

建议先阅读：Zabbix 监控

基础概念

项目沿革：从 pgwatch2 到 pgwatch

pgwatch 的版本演进在 PostgreSQL 监控工具里算是一部「重写史」，理解沿革才能看懂社区里新旧资料混杂的现状：

阶段	名称	关键特征
2017 年起	pgwatch2	Go 采集守护进程 + Python Web UI，All-in-one Docker 镜像，存储主打 InfluxDB
v3	pgwatch（更名）	纯 Go 重写（含 Web UI），架构组件化解耦，存储后端多元化，废弃 InfluxDB 主推 PostgreSQL 存储
v4（2025-09 发布）	pgwatch	Grafana v12 新看板套件、移除 realtime 指标、metric 支持从目录加载、新增 gRPC sink 等

社区文章里的「pgwatch2」「pgwatch3」「pgwatch v4」都是同一条产品线的不同阶段；GitHub 仓库现为 cybertec-postgresql/pgwatch。检索资料时先对版本再看配置——v2 时代的环境变量与配置方式在 v3/v4 里大多已经变化，这也是本页反复强调「以官方文档为准」的原因。

核心架构：采集器 + 配置 + 存储 + Grafana

┌────────────────────┐
│  被监控 PostgreSQL   │◄──── 定期执行 metric SQL（普通连接）
│  （多实例/多库）      │         ├─ 统计视图（pg_stat_*）
└────────────────────┘         ├─ 扩展（pg_stat_statements 等）
                               └─ 系统函数
┌────────────────────┐
│  pgwatch 采集守护进程 │───── 按配置的间隔拉取各库各 metric
│  （fetcher，Go）     │
└────────┬───────────┘
         │ 写入
┌────────▼───────────┐     ┌──────────────┐
│  指标存储（sink）     │────►│   Grafana     │
│  PostgreSQL/        │     │  （官方预置    │
│  Prometheus/        │     │   看板套件）    │
│  InfluxDB/…         │     └──────────────┘
└────────────────────┘

四个组件的职责边界：

组件	职责	说明
fetcher	采集守护进程，周期执行 metric SQL 并写入 sink	唯一的「运动部件」，无 agent 进程驻留数据库主机
配置来源	被监控库清单 + 每库的 metric/间隔	支持 PostgreSQL 配置库、配置文件、环境变量等多种形态
sink	指标时序存储	PostgreSQL（可加 TimescaleDB）、Prometheus、InfluxDB、Graphite、gRPC 等，按版本支持情况选
Grafana	可视化	官方维护一整套与 metric 对应的看板 JSON，导入即用

这个架构对运维的意义：采集器挂了 = 数据断流（有独立进程要监控）；存储就是现成的数据库技术（运维技能直接复用）；看板与指标解耦（想改图完全不必动采集）。

与前几页方案的定位对比

维度	pgwatch	Prometheus + postgres_exporter	Zabbix（agent2 模板）
PostgreSQL 语义深度	原生：metric 即 SQL，官方持续跟进新版本统计视图	中等：靠 queries.yaml 自定义	中等：靠官方模板更新节奏
开箱看板	官方预置整套 Grafana 看板	社区看板自行导入	内置图形偏基础
部署侵入性	远程采集，数据库侧零安装（个别指标需扩展）	数据库主机装 exporter 或远程探针	数据库主机装 agent2
告警	借助 Grafana Alerting 或 Prometheus 规则	原生强项	原生强项（企业级）
设备/主机监控	无（专注 PostgreSQL）	生态完整（node_exporter 等）	原生完整
适合谁	DBA 团队自建 PG 专用监控	云原生/统一可观测性平台	已有 Zabbix 的企业

定位一句话：pgwatch 是「PostgreSQL 深度语义」的化身，通用监控平台是「组织覆盖面」的化身。两者不互斥——很多团队用 pgwatch 做数据库深度观测，把告警与总览留在企业主平台（见下文「与通用监控平台的组合」）。

关键设计：metric（指标）与 preset（预设组合）

pgwatch 的两个一等概念，也是它可定制性的来源：

• metric：一个具名的采集单元，本质是一段 SQL（多数按 PostgreSQL 版本提供不同语句），返回 tag 键值 + 数值列 的行集。官方内置大量 metric 覆盖 pg_stat_* 系列统计视图、扩展输出与系统函数，metric 定义存配置库或文件，随版本演进。
• preset：metric 的预设组合——把一批 metric 与各自的采集间隔打包成一个「监控等级」配置，接入被监控库时直接引用。直觉上可以理解为「基础档 / 标准档 / 全量档」的分层：基础档覆盖可用性与核心性能指标，高等级档叠加语句级、对象级、膨胀类指标。具体 preset 名称与包含的 metric 清单随版本变化，以官方文档为准，本页只讲机制。

这套设计带来的运维模型：新建一个自定义指标 = 写一段 SQL 并注册 metric（几分钟）；调整某类库的监控强度 = 换 preset 或改个别 metric 间隔（改配置即可）；PostgreSQL 升级 = 官方新版本的 metric 定义同步更新（不用自己重写 queries）。

语法与用法

部署形态选择

pgwatch 提供多种部署路径，按环境选：

形态一：Docker Compose 一体化演示/中小规模生产
  一条 compose 文件拉起 pgwatch + 配置库/存储库 + Grafana，
  十几分钟出第一张看板——评估与中小环境首选

形态二：组件化部署（生产推荐）
  采集器单独跑（二进制/容器）
  存储用组织现成的 PostgreSQL（可选 TimescaleDB 加速）
  Grafana 用现成实例（官方看板 JSON 导入）

形态三：Kubernetes（Helm Chart）
  官方提供 Helm 部署路径，适合容器化平台

具体镜像名、compose 文件与 Chart 用法随版本演进，
以官方仓库的部署文档为准

生产环境建议形态二：pgwatch 的存储 sink 就是 PostgreSQL，多数组织已有现成实例与备份体系，复用比再造一套存储运维负担小得多。TimescaleDB 在指标量大时能显著改善压缩与查询性能，属于「量大了再加」的优化项。

部署采集器（示意流程）

# 以下为流程示意：镜像名/端口/环境变量以所用版本官方文档为准

# 1. 拉起服务（一体化 compose 为例）
git clone https://github.com/cybertec-postgresql/pgwatch.git
cd pgwatch
# 按官方文档选择 compose 文件（含存储库 + Grafana 的演示栈）
docker compose up -d

# 2. 访问组件
#    Web UI（配置被监控库、管理 metric）——默认 8080 附近的端口
#    Grafana（看板）——默认 3000 附近的端口
#    具体端口见 compose 文件映射

# 3. 登录后第一件事：改掉默认口令

部署后健康检查的三步：Web UI 能登录且能看到内置 metric 列表；Grafana 能看到官方预置看板；添加一个测试库后几分钟内看板出现数据。三步全过才算部署完成——三个组件各自健康不等于链路贯通，数据出现在看板上才是端到端的证明。

接入被监控库

在 Web UI（或配置文件）中添加被监控的 PostgreSQL 实例，核心字段是一组连接信息加监控策略：

添加被监控库的关键配置（字段名以所用版本 Web UI 为准）：

  连接组：
    Host / Port / dbname    —— 连接目标
    User / Password         —— 监控账号（建议专用账号）
    SSL mode                —— 跨网络采集时启用

  监控策略组：
    preset / metrics 集合    —— 用预设组合或自定义
    采集间隔                —— 各 metric 的周期（preset 已含默认值）
    语句级指标开关           —— 是否启用 pg_stat_statements 类采集

准备监控账号

权限模型与前面几页一致——pg_monitor 是标准起点：

-- 监控账号
CREATE ROLE pgwatch_mon WITH LOGIN PASSWORD '强口令';

-- pg_monitor 覆盖统计视图读取（pg_read_all_settings /
-- pg_read_all_stats / pg_stat_scan_tables 已聚合在内）
GRANT pg_monitor TO pgwatch_mon;

-- 语句级与对象级指标需要的扩展（在目标库内）
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-- 部分指标还可能用到其他扩展，以 metric 定义文档的说明为准

pgwatch 的「非侵入」指架构层面不需要在数据库主机上装 agent，但个别高级指标（语句级、I/O 时间级）本身依赖扩展存在——这是 PostgreSQL 的能力边界而非 pgwatch 的限制。装扩展属于标准运维操作（pg_stat_statements 无需重启，见前文慢查询一章），不算破坏「非侵入」承诺。

# pg_hba.conf：放行采集器来源
host  all  pgwatch_mon  10.0.8.20/32  scram-sha-256

验证采集链路

接入后的验证清单：
1. Web UI 的主机列表里该库状态正常（非红色/断连态）
2. Grafana 官方「数据库总览」类看板出现该库数据
   ——连接数、事务速率等基础曲线先动起来
3. 语句级看板（若启用）有 Top 查询数据
   ——空着通常是 pg_stat_statements 未装或未授权
4. 等一个采集周期 × N（如 10 分钟），确认曲线连续无大段空洞

详细说明

metric 体系与采集语义

内置 metric 按语义可归为几大类（名称以官方 metric 列表为准）：

类别	覆盖内容	典型用途
实例健康	存活、启动时长、配置	可用性告警的数据源
连接与会话	连接数、状态分布、最长事务	容量与异常会话发现
累计统计	pg_stat_database 系列计数器	事务/块读写速率曲线
语句级	pg_stat_statements 输出	Top 查询、慢查询分析
对象级	表/索引大小与访问统计	膨胀观察、索引效益评估
WAL 与复制	WAL 速率、延迟、归档	复制健康度
锁与等待	锁等待、等待事件	阻塞诊断
I/O	pg_stat_io（新版本）等	I/O 特性分析

理解 pgwatch 的采集语义有两把钥匙。其一，与所有监控体系一样，累计计数器在存储侧被换算成速率（官方看板展示的已是差分/速率结果），所以「看板数字突降」先想计数器重置（实例重启）而不是业务真降了。其二，metric 是按版本分档的 SQL——同一个 metric 对 PG 12 与 PG 18 可能用不同语句（比如新版用 pg_stat_io），官方维护这份版本映射，你自己的自定义 metric 也要学会这个模式（见下文）。

preset 的分层思路与选型

preset 的机制在「基础概念」讲过，这里讲怎么选。官方 preset 按信息量与采集开销分层，选型思路：

选型决策树（思路示意，具体档位名以官方文档为准）：

  生产核心库（延迟敏感）
    → 较低档 preset：健康 + 连接 + 核心速率，分钟级间隔
  生产普通库
    → 标准档：再叠加对象级、锁等待
  测试/预发库
    → 较高档：语句级、全量对象统计，帮测试发现问题
  几百个微库/租户库
    → 最低档 + 放宽间隔，只保可用性与容量信号

两条纪律：生产库不要无脑开最高档——语句级与全量对象统计都有采集成本（对超大实例，对象级 metric 一次查询本身就要跑几秒）；间隔与库的重要度成正比而不是与焦虑度成正比——核心库 1 分钟档、边缘库 15 分钟档是常见配比。采集开销的评估方法见下文。

自定义 metric：SQL 即指标

pgwatch 最受 DBA 欢迎的能力：新指标只需写一段 SQL。metric SQL 的约定（细节以官方文档为准）：

-- 自定义 metric 示例：业务侧队列积压深度
-- 约定：返回行集，tag 列（可选）+ 数值列；列名即指标名
SELECT
    queue_name                          AS tag_queue_name,
    coalesce(count(*), 0)::bigint       AS backlog_depth,
    coalesce(min(created_at), now())    AS oldest_task_age_seconds
FROM task_queue
WHERE status = 'pending'
GROUP BY queue_name;

写自定义 metric 的四条军规（与 Prometheus 页的三条红线一脉相承但更具体）：

1. 只读且快速：查询走统计视图或业务索引，单次执行应在几十毫秒级；不确定的查询先 EXPLAIN ANALYZE。
2. 结果集有界：GROUP BY 的基数可控（按库、按表、按状态枚举），绝不返回无上限的行——每个单元格都是存储与基数的放大器。
3. 幂等无副作用：不写锁、不更新、不用会话状态；metric SQL 在采集失败时安静报错即可，不能影响业务。
4. 版本兼容意识：引用版本相关视图（如 pg_stat_io）时，学官方的样子给不同大版本准备不同语句；升级 PostgreSQL 时把自定义 metric 过一遍。

metric 注册后（Web UI 或配置库/文件，按版本），在 preset 或主机配置里引用它，下个采集周期数据即入库——「改监控不用改代码」的体验就是这么来的。

采集间隔与开销治理

pgwatch 没有免费午餐：每个 metric 每个周期都是一次真实的数据库查询。开销治理的框架：

开销账本（对单实例）：
  QPS增量 ≈ Σ（每个启用 metric 的 1/间隔）
  例：20 个 metric 平均 60s 间隔 → 约 0.33 QPS 的额外查询负载

  真正要警惕的不是 QPS 而是单条查询的代价：
    对象级 metric 在 5000 张表的库上 = 一次较重的统计扫描
    语句级 metric 依赖的 pg_stat_statements 视图在大内存
    机器上可能几百 MB——每次采集都是一次全读

治理手段按效果排序：按库重要度分层 preset（上一节）；对象级/语句级指标放宽间隔（表大小 5 分钟看一次没意义，1 小时足够）；监控 pgwatch 自己（采集器的资源占用、sink 的写入延迟、目标库上监控账号的查询耗时——后两者能在 sink 库或目标库的统计里直接看到）；采集超时与失败告警（metric 卡住会拖垮整个实例的采集节奏，配置层面的超时项按官方文档设置）。

存储后端（sink）的选择与运维

v3 之后的 pgwatch 把存储抽象成可插拔 sink，主流选项的取舍：

sink	优势	代价	适合
PostgreSQL（可选 TimescaleDB）	运维技能复用、SQL 直查、备份体系现成	超大规模要调优	绝大多数团队的默认选择
Prometheus	接入既有 Prometheus/Grafana 告警体系	走拉模型、长历史留存要另配	与云原生栈合流
InfluxDB	v2 时代的主打	v3 起已弃用，新部署不建议	存量迁移
Graphite / gRPC 等	对接既有基础设施	视组织情况	特殊环境

选 PostgreSQL 作为 sink 的运维要点：它就是一台要被运维的数据库——磁盘容量按 metric 数 × 库数 × 间隔 × 保留期估算，保留期策略（原始数据保留多久、降采样后保留多久）要显式配置，TimescaleDB 的压缩策略能把磁盘占用降一个量级。不要把 sink 库和被监控的业务库混部在同一实例——业务高峰 + 采集写入 + 大查询三面挤压，监控体系自己先倒下是最尴尬的故障。

配置来源与配置的版本管理

pgwatch 支持多种配置来源（配置库、配置文件、环境变量等，支持矩阵以官方文档为准），这不只是功能列表，而是配置管理策略的选型：

三种配置来源的运维画像：

  配置库（PostgreSQL 存储 monitored DB 清单与 metric 定义）
    优势：Web UI 增删改即生效，动态性好
    风险：配置变更无审计与回滚能力，容易「谁改的没人知道」

  配置文件 / 目录（YAML 等声明式文件）
    优势：天然可入 Git，变更走评审，环境可复制
    适合：配置即代码（IaC）成熟度高的团队

  环境变量
    优势：容器化的标准姿势
    适合：Kubernetes 部署的基础项

生产建议的混合策略：基础项用环境变量（容器化）、被监控库清单与自定义 metric 用文件形态入 Git、变更通过 CI 同步——Web UI 只用于临时排障性操作（临时给某库加指标看一天），所有长期配置以 Git 为唯一事实源。pgwatch 的 metric 定义本质是 SQL 文本，天生适合版本管理；把自定义 metric 的 SQL 与看板 JSON 都放进基础设施仓库，监控体系就具备了可审计、可回滚、可复制到新环境的完整能力。这条实践与 Zabbix 页的「模板导出入 Git」、Prometheus 页的「queries.yaml 入 Git」是同一条原则的三个化身。

多租户环境（RDS/托管服务）的监控建模

pgwatch 对云托管数据库（RDS 类）有天然亲和性——远程采集意味着不需要在托管实例上装任何东西，这也是它相对 agent 型方案的核心优势。多租户建模要点：

托管数据库场景的接入要点：

  1. 监控账号走云平台的标准方式创建与授权
     （RDS 类服务的 pg_monitor 角色授予方式见云方文档）
  2. 个别依赖超级权限或文件系统访问的 metric 在托管环境不可用
     ——官方对兼容性有说明，按可用清单选 preset
  3. 网络链路：采集器所在网络要能到达数据库端口
     （VPC 对等/专线），SSL 默认开启
  4. 成本意识：跨可用区/跨区流量按云方计费，
     采集间隔与流量账单直接相关

  租户库的分层建模：
    租户库数量大 → 最低档 preset + 宽间隔
    租户隔离要求高 → 每租户独立监控账号（凭据管理成本上升）
    租户容量计费 → 库大小类 metric 的间隔与账期对齐

托管场景还有一个隐性收益：pgwatch 的 sink 用自建 PostgreSQL 存云上数据库的指标，监控数据的所有权在自己手里——这在数据主权敏感的组织里是相对云厂商自带监控的重要差异化（云监控的深入对比见下一页）。

官方看板体系

pgwatch 的 Grafana 看板是「开箱即用」承诺的核心兑现。v4 的看板套件（随版本演进）覆盖：全局多库总览、单库总览（连接/复制/索引使用等面板组）、语句性能分析（Top 查询多维表格 + 可视化）、表级洞察（大小/膨胀/索引使用的树图等）。使用方法论：

看板使用三步法：
1. 先看官方总览类看板，理解每个面板对应哪个 metric
   ——面板标题与 metric 名通常直接对应
2. 团队标准化的「一屏总览」：
   官方总览看板为底，按本组织的告警口径调整阈值线与排序
3. 自定义 metric 的可视化：
   自建看板 + 数据源指向 pgwatch 的 sink 库，
   表/曲线自由组合——数据在你自己库里，完全开放

版本升级时同步升级看板：官方看板 JSON 随 metric 演进（v4 就为 PostgreSQL 18 的新统计字段更新了看板），旧看板配新 metric 会出现空面板——官方仓库的看板目录按版本发布，升级 pgwatch 后重新导入是标准动作。

告警：站在 Grafana（或 Prometheus）肩上

pgwatch 自身不是告警引擎——告警借道看板层：

路线 A：Grafana Unified Alerting（默认推荐）
  在 Grafana 里对关键面板配置告警规则
  → 通知渠道（IM/Webhook/电话平台）
  优势：与看板同一界面，规则即所见即所得

路线 B：Prometheus sink + Prometheus 规则/Alertmanager
  sink 选 Prometheus 时，指标进入既有 Prometheus 体系
  → 告警规则、路由、静默全部复用组织现有标准
  优势：告警治理与企业级实践对齐（参考本章节 Prometheus 页）

告警规则的选题直接复用 Prometheus 页的六条清单（实例存活、连接饱和、复制延迟、WAL 堆积、缓存命中率劣化、长事务），阈值推导方法也通用。pgwatch 场景的特殊点：它的数据粒度由你的 preset 决定——告警的多周期确认窗口要大于等于采集间隔，1 分钟采集配 30 秒告警窗口会在数据断点上产生误报。

高可用与规模化的部署考量

监控体系自身的健壮性按规模分档：

单套部署（几十个库以内）：
  采集器单实例即可——它挂掉的损失是「数据断流」，重启后自愈；
  给采集器进程配 systemd/容器的自动拉起即可
  sink 用单实例 PostgreSQL + 常规备份

规模化（数百实例起）：
  采集器关注吞吐（官方有大规模部署的实践指引）
  sink 上 TimescaleDB 或分区表，保留期策略显式化
  采集器自身要有存活监控（meta-monitoring，参考 Zabbix 页的演习思路）

多环境隔离：
  生产/测试分开部署采集器与 sink，
  避免测试库的实验性 metric 拖累生产采集节奏

pgwatch 采集器无状态（配置在配置库/文件、数据在 sink），这让它的「高可用」异常简单——挂了拉起来就行，最多丢断流期间的采样点。真正要保高可用的是 sink 库。

与通用监控平台的组合

pgwatch 与企业既有监控平台不是替代关系，组合模式参考 Zabbix 页的并存策略，这里给出 pgwatch 特有的分工建议：

组合模式（经过验证）：

  pgwatch 负责：
    PostgreSQL 深度语义（语句级、对象级、膨胀、复制细节）
    DBA 日常巡检与排障看板
    版本升级前的统计视图验证

  企业主平台（Prometheus/Zabbix）负责：
    可用性告警与值班流程（pgwatch 数据可经 Prometheus sink 汇入）
    主机/网络/中间件监控
    合规审计口径

  组合的粘合点：
    sink 选 Prometheus → 指标自动进入企业 Prometheus，
    主平台的告警规则直接消费 pgwatch 的高语义指标

这个组合的精髓是告警留在主平台、语义深度留在 pgwatch——值班同学不需要学新系统，DBA 却拿到了通用平台永远给不了的语句级视野。

存量部署的升级与迁移路径

v2 时代的存量部署（社区里为数不少）升级到当前版本的路径规划：

v2 → v3/v4 迁移的关键差异（迁移前逐项核对官方迁移说明）：

  1. 架构形态：一体化镜像 → 组件化（采集器/存储/看板分离）
  2. 存储：InfluxDB 为主 → PostgreSQL/Prometheus 等
     （InfluxDB 支持已弃用，数据要迁移或接受历史断层）
  3. 配置：旧环境变量体系 → 新配置体系（名称大改）
  4. 看板：旧 Grafana 看板 → 新版看板套件（重新导入）
  5. realtime 指标：v4 已移除，依赖它的看板要找替代

迁移策略的经验顺序：先并行后切换（新版本部署一套，同一批库双采一至两周，对比指标语义与开销）、历史数据通常不值得迁移（旧 InfluxDB 里的历史曲线导出归档即可，监控数据的长期价值在于持续可比的基线，中断一次无伤大雅，前提是新基线尽快开始积累）、迁移窗口选在业务低峰并做好回滚预案（保留旧采集器配置的快照，随时可以切回）。

如果是全新部署，直接用当前版本，上述差异仅作资料甄别知识——看到讲 InfluxDB 与旧变量的教程，先看发布日期再决定是否采用。

实战示例

示例一：从零到第一张看板（评估流程）

# 目标：30 分钟内在测试环境完成评估
# 1. 拉起一体化演示栈（compose 文件以官方仓库为准）
git clone https://github.com/cybertec-postgresql/pgwatch.git
cd pgwatch && docker compose up -d

# 2. 准备一个测试库并接入
psql -h testdb-host -c "CREATE ROLE pgwatch_mon LOGIN PASSWORD '...';"
psql -h testdb-host -c "GRANT pg_monitor TO pgwatch_mon;"
psql -h testdb-host -c "CREATE EXTENSION pg_stat_statements;"

# 3. Web UI 添加该库，preset 选标准档
# 4. 等 5~10 分钟，Grafana 看总览看板

评估清单（决定是否进入生产）：
□ 总览看板的核心面板（连接/事务/缓存命中）有数据且语义清晰
□ 语句级看板能看到 Top 查询并按耗时/调用数排序
□ 自定义一个 metric 的全流程（写 SQL→注册→看板出图）≤ 30 分钟
□ 采集对测试库的负载无感（对比接入前后 pg_stat_statements）
□ sink 侧写入稳定，无持续增长的表（保留策略生效）
□ 重启采集器后曲线自动恢复，无数据空洞残留
□ 团队对看板与 metric 模型的一致认可

示例二：业务队列积压的自定义指标

-- metric: biz_queue_backlog（业务告警的核心信号）
SELECT
    q.name                      AS tag_queue,
    count(*) FILTER (WHERE t.status = 'pending')::bigint
                                AS pending_cnt,
    count(*) FILTER (WHERE t.status = 'running'
                      AND t.started_at < now() - interval '30 min')::bigint
                                AS stuck_cnt,
    coalesce(max(extract(epoch FROM now() - t.created_at))
             FILTER (WHERE t.status = 'pending'), 0)::int
                                AS oldest_pending_age
FROM queues q
LEFT JOIN tasks t ON t.queue_id = q.id
GROUP BY q.name;

落地步骤：
1. Web UI（或配置库）注册 metric "biz_queue_backlog"
2. 给相关库的 preset 附加该 metric，间隔 1m
3. Grafana 新建看板：
   按 tag_queue 分组的 pending 曲线 + stuck 数值表
4. Grafana Alerting：
   stuck_cnt > 0 持续 5 分钟 → Warning
   oldest_pending_age > 1800 持续 5 分钟 → High
5. 观察一周：确认查询耗时 < 50ms、结果集行数 = 队列数（有界）

这个例子展示了 pgwatch 的杀手级场景：业务指标与数据库指标在同一套体系里同屏——积压曲线与连接数、锁等待出现在同一张看板上，跨域排障不再两头翻系统。

示例三：核心库的分级监控落地

环境：3 套核心集群（每套 1 主 2 备）+ 40 个普通业务库 + 200 个租户库

1. preset 分层：
   核心集群 → 高档位：语句级 + 对象级 + 复制细节，1m 间隔
   普通业务库 → 标准档位：核心统计 + 锁等待，5m 间隔
   租户库 → 最低档位：可用性 + 连接 + 容量，15m 间隔

2. 复制监控的视角处理：
   主库采集延迟指标（pg_stat_replication 视角），
   备库采集回放年龄类指标，两边看板同屏

3. sink 配置：
   独立 PostgreSQL 实例 + TimescaleDB，
   原始数据保留 30d，降采样数据保留 1y（按官方文档配置策略）

4. 验证开销：
   核心库接入前后对比 pg_stat_statements 中监控账号的
   total_exec_time 占比（预期 < 1%）

示例四：与 Prometheus 体系合流

背景：公司统一可观测性平台是 Prometheus + Grafana，
      DBA 团队想用 pgwatch 的语句级/对象级深度指标。

方案：pgwatch sink 选 Prometheus
  1. pgwatch 采集器把 metric 暴露给 Prometheus 抓取
     （具体暴露方式与指标命名以官方文档为准）
  2. Prometheus 侧添加抓取任务
  3. 告警规则直接在 Prometheus 写
     （复用 Prometheus 页的告警清单与阈值推导）
  4. 看板策略：
     企业 Grafana 里官方 pgwatch 看板（Prometheus 数据源版）
     + DBA 自建的深度排障看板并存

效果：
  值班告警走企业标准链路（Alertmanager → IM/电话）
  DBA 深度排障用 pgwatch 的高语义看板
  两套视野共享同一份指标数据，无重复采集

示例五：PostgreSQL 大版本升级前的监控护航

背景：计划把核心库从 PG 13 升级到 PG 18，用监控护航。

1. 升级前两周：
   - 确认所用 pgwatch 版本对 PG 18 的 metric 支持
     （v4 的发布说明明确列出 PG 18 相关的 metric 更新）
   - 升级官方看板到适配版本（旧看板的新字段面板会空）
   - 自定义 metric 过一遍版本兼容（pg_stat_io 等）

2. 升级演练（预发环境）：
   - 切换后观察采集是否报错（版本相关 SQL 是高发雷区）
   - 对比新旧版本的 I/O 与 WAL 曲线基线（帮助评估升级收益）

3. 生产切换当晚：
   - 监控大盘就是验收面板：连接恢复、错误率归零、
     复制重建、延迟收敛——每个环节都有曲线作证
   - pg_stat_statements 计数清零后，语句级看板需要
     重新积累基线（提前告知团队，避免误读）

注意事项

版本资料混杂是这个项目最大的坑。 社区大量教程停留在 pgwatch2 时代（InfluxDB、旧环境变量、旧端口），v3/v4 的架构与配置方式变化很大——任何配置动作前先确认官方文档的版本，本页所有「以官方文档为准」的标注都是这个原因。

「非侵入」不等于「零成本」。 采集查询本身消耗目标库资源，对象级/语句级 metric 在超大实例上的单次代价可观；分级 preset 与间隔治理不是可选项而是必修课。

sink 库是要认真运维的数据库。 容量（metric 数 × 库数 × 间隔 × 保留期）、保留策略、压缩（TimescaleDB）、备份一个都不能少；监控数据无限增长最终会拖垮监控体系本身。

pgwatch 不解决告警与值班流程。 它是采集与展示层，告警要借道 Grafana Alerting 或 Prometheus；企业级值班升级链路（电话/升级链）需要与主监控平台组合，别指望 pgwatch 单体覆盖 Zabbix 页讲的全套告警治理。

扩展依赖要按 metric 清单核对。 pg_stat_statements 等扩展是语句级指标的前置条件，漏装的结果是看板空白而非报错——接入验证清单里的「语句级看板有数据」就是为这一条设的。

监控账号口令纳入轮转体系。 pgwatch 侧的连接凭据（配置库或配置文件里）与数据库侧账号的轮转要同步演练；配置库本身的访问控制也要收紧——它存着所有被监控库的连接信息，是敏感资产的集中点。

实时类指标的能力边界随版本变化。 v4 已移除 realtime 指标体系（会话级实时采样让位于统计视图方案），依赖旧版实时能力的老部署升级前要评估替代方案（如改用锁等待与等待事件的周期采集）。

采集器与 sink 的存活要进 meta-monitoring。 pgwatch 自身挂掉的表现是「看板曲线停止更新」——没人盯着就会静默失效；给采集器进程配自动拉起，给 sink 配存活与磁盘告警，参考 Zabbix 页的季度演习方法。

看板与指标要交给团队而不是个人。 pgwatch 的低定制门槛容易造成「metric 和看板都是某位同事手搓的」单点知识风险；自定义 metric 的 SQL 与看板 JSON 入基础设施仓库并做文档化，让体系资产化而不是人格化。

最佳实践

1. 新部署直接上当前主版本，不要从旧版资料抄配置。 官方仓库与文档是唯一可信配置来源；评估期用官方一体化 compose，生产用组件化部署。
2. 监控账号 pg_monitor 起步，按 metric 清单增量授权。 禁止 superuser；语句级指标需要的目标库扩展（pg_stat_statements 等）在接入清单里逐项核对。
3. preset 分层是开销治理的第一杠杆。 核心库高档、普通库标准档、海量小库最低档；对象级与语句级 metric 的间隔宁可宽不可窄。
4. 自定义 metric 遵守四条军规：只读快速、结果有界、无副作用、版本兼容。 每个自定义 metric 上线前在预发库压一遍查询耗时。
5. sink 优先选组织现成的 PostgreSQL，量大了加 TimescaleDB。 sink 与业务库严格分离；保留期策略显式配置并纳入容量规划。
6. 告警规则选题复用本章节的六条清单，确认窗口大于采集间隔。 走 Grafana Alerting（简单）或 Prometheus sink + Alertmanager（企业级）两条路线之一，别双轨并行。
7. 看板随版本升级同步更新。 官方看板 JSON 与 metric 演进绑定，升级 pgwatch 后重新导入；团队标准「一屏总览」在官方看板基础上定制并版本化。
8. 业务自定义指标是 pgwatch 的差异化价值。 队列深度、租户健康度这类「SQL 能算出来的业务信号」放进同一监控体系，排障效率倍增——这是通用监控平台给不了的。
9. 与主监控平台的分工：告警值班归主平台，语义深度归 pgwatch。 Prometheus sink 是现成的粘合点，避免两套体系重复采集与两套告警口径。
10. 大规模部署前做采集开销压测。 用 pg_stat_statements 观察监控账号的耗时占比，超 1% 就回头调 preset 与间隔；监控查询本身也应该被监控——这是「吃自己的狗粮」在监控领域的含义。
11. 监控自身的存活（采集器进程、sink 库、磁盘）纳入 meta-monitoring。 pgwatch 无状态、可随时重启的特性让它的 HA 成本极低——用好这个特性而不是假装它不会挂。
12. PostgreSQL 大版本升级与 pgwatch 升级联动规划。 新版本统计视图是升级收益评估的数据源，也是版本兼容雷区——升级护航流程里给监控适配留出两周缓冲。

下一节

继续学习：云监控与 SaaS 工具

参考链接

• pgwatch GitHub 仓库（cybertec-postgresql/pgwatch）
• pgwatch 官网
• pgwatch 在线演示（demo.pgwatch.com）
• PostgreSQL 官方新闻：pgwatch v4 is out!
• pgwatch v4.0.0 Release Notes（GitHub Releases）
• CYBERTEC 官方：Announcing pgwatch2（项目设计哲学）
• CYBERTEC 官方产品页：pgwatch
• PostgreSQL Wiki：Monitoring 工具清单
• Grafana 官方文档：Alerting
• pgwatch-contrib（社区扩展仓库）