如何读懂 pgbot inspect 健康报告:仪表盘、健康分与 CRITICAL/WARNING/NOTE 发现的完整解读

原创2026-10-11 19:27:591,918 阅读

如何读懂 pgbot inspect 健康报告:仪表盘、健康分与 CRITICAL/WARNING/NOTE 发现的完整解读

pgbot 是一款面向 PostgreSQL 的只读数据库体检工具:一条 pgbot inspect 命令,它连接数据库、采样统计视图,并打印一份"发现优先"(findings-first)的健康报告。对新手来说,第一次面对报告时最容易困惑的是:仪表盘四行进度条代表什么?Database health: 82/100 怎么算出来的?CRITICAL、WARNING、NOTE 三档发现又该怎么处理?这篇文章带你把 pgbot inspect 报告从上到下完整读一遍。

pgbot inspect 健康报告仪表盘

pgbot inspect 报告整体结构

执行一次体检:

pgbot inspect "postgres://pgbot_ro@host:5432/db"

默认报告从上到下分为五块(对应 dashboard.go 中的 renderGrouped 函数):

区块 作用 一句话解读
① 连接信息头 目标主机、版本、统计窗口 确认你查的是"那台"库、多长的时间窗口
② 仪表盘仪表条 四项关键生命体征 1 秒判断数据库当前状态
③ checked 行 点名列出检查过且干净的子系统 说明"哪些已经查过且没问题"
④ 健康分 0–100 分 一眼总评
⑤ 发现列表 CRITICAL / WARNING / NOTE 分级 需要动手处理的问题清单

末尾还会提示两个延伸入口:pgbot inspect --full 查看详细表格,pgbot ask "why is it slow?" 用 AI 解读同样的发现。

仪表盘四行仪表条:1 秒读懂关键指标

仪表条由 gauges.go 渲染,每行是一个进度条 + 数值 + 一个词的状态。设计原则是:状态词永远由对应的发现(finding)驱动,不会和下方的发现列表自相矛盾。

  • cache hit(缓存命中率):缓冲缓存的块读取命中率。健康值通常在 99% 以上;如果状态变成红色的 low,说明大量读操作打到磁盘(对应 low_cache_hit 发现)。
  • lock wait(锁等待):采样窗口内活跃时间花在锁等待上的比例。状态会直接点名"元凶"——比如 query 4f2a 就是那条锁等待占比最高的 SQL 的 query_id 前四位,你可以用它到 pgbot queries 或 pg_stat_statements 里找到完整语句;若没归因则显示 N blocked(N 个会话被阻塞)。
  • rollbacks(回滚率):采样窗口内事务回滚占比。watch 表示回滚异常偏高,往往指向应用层的错误处理问题(对应 high_rollback_ratio 发现)。
  • idle idx(闲置索引):零扫描索引占用的总空间,进度条表示它占整个数据库体积的比例——回答"多少存储是死重"。对应 unused_indexes 发现。

三个阅读细节:

  1. 状态词即结论:ok(绿)正常、watch(黄)需要留意、review(黄)建议排查、红色词(如 low、query 4f2a)表示有对应发现触发。
  2. 测不出会明说:如果信号无法测量(比如样本太薄),该行显示灰色的 — 并写明原因(thin sample、not measurable),而不是画一根像零的空条。
  3. 窗口太冷会降级:idle idx 在统计窗口不足 15 分钟时显示 window < 15m——刚重启/刚唤醒的库里,累计扫描次数没有意义。

checked 行:它替你确认过哪些没问题

checked · queries · vacuum · replication · checkpoints … 这一行由 gauges.go 中的 buildChecked 生成,点名列出已采集且零发现的子系统:queries、indexes、vacuum、replication、checkpoints、connections、settings、wraparound、deadlocks。

它的设计意图是:一个会告诉你"查过哪些、且没发现异常"的工具,读起来才像一个真的检查过的同事,而不是一个只会报警的仪器。所以如果 vacuum 出现在这行里,就意味着死元组、autovacuum 滞后、统计信息过期等一整组检查都通过了;反之,只要该子系统有任何一个发现触发,它就会从这行消失。

健康分 0–100 是怎么算的

Database health: 82/100 不是黑盒,dashboard.go 中的 computeHealthScore 给出了完整规则:

100 分起步,按发现严重度扣分:每个 CRITICAL 扣 10 分、每个 WARNING 扣 3 分、每个 NOTE 扣 1 分,最低 0 分。

三个使用要点:

  • 被抑制的发现不扣分。通过 .pgbot.toml 的 [[ignore]] 规则静音的发现既不影响健康分,也不影响退出码。
  • 颜色分档:< 70 分显示红色,70–89 分显示黄色,≥ 90 分显示绿色。
  • 它是"一瞥指标",不是精确度量。同样的 82 分可能来自 2 个 CRITICAL + 6 个 WARNING,也可能来自更多小问题——具体要看下面的发现列表,不要只盯着分数。

逐档解读:CRITICAL / WARNING / NOTE 各代表什么

发现列表按严重度分三档,同档内按"影响分"(Impact)从大到小排序。每个发现的完整定义都在 docs/findings/ 目录里,可以用 pgbot explain-finding <id> 离线查看某个发现的"观察到了什么 / 为什么重要 / 如何验证 / 如何修复 / 何时可忽略"。

🔴 CRITICAL:正在倒计时的问题

对应数据丢失或全面停写的风险。典型例子(摘自 findings 目录 的 Risk 分组):

  • checksum_failures — 读到了校验和不匹配的页面,可能已损坏(详见 checksums.md)
  • fsync_off / full_page_writes_off — 崩溃后数据可能不可恢复(fsync_off.md)
  • txid_wraparound — 事务 ID 年龄逼近 21 亿的写停墙(txid_wraparound.md)
  • blocking_chains — 会话被锁阻塞链卡住(blocking_chains.md)
  • autovacuum_off — 自动清理关闭,膨胀和回卷倒计时开始(autovacuum_off.md)

一个值得注意的安全设计:即使你用配置抑制了一个 CRITICAL 发现,它仍然会显示在报告里(并标注 suppressed by config),只是不再计入健康分和退出码——配置不允许让危险从屏幕上消失。

🟡 WARNING:需要排期处理的问题

最常见、也最容易被拖延的一档,比如:

  • connection_saturation — 连接数逼近 max_connections
  • unused_indexes — 零扫描索引白占存储和写入开销(unused_indexes.md)
  • query_slowdown — 某条查询相对基线明显变慢
  • stale_statistics / never_analyzed — 统计信息过期,规划器只能瞎猜
  • replica_lag_time — 备库回放延迟超过阈值(replica_lag_time.md)

🔵 NOTE:值得知道,但通常不用马上动

信息级提示,比如 pg_stat_statements_missing(没装查询统计扩展,查询级可见性缺失)、checksums_disabled(没开数据校验和,损坏将无声无息)、statement_timeout_unset(没设全局语句超时,失控查询可以永远跑下去)。它们帮你补齐"观测能力",而不是指出现场故障。

安全护栏:破坏性操作会被明确喊停

对于可能诱导你执行危险动作的发现(比如删索引),报告内会直接打印结构化护栏行:

⚠ do NOT drop — replication is active, replicas may use these
⚠ before drop, confirm: check replica index stats first

这是 dashboard.go 中 renderSafetyGuards 的职责:禁令(prohibition)和前置检查(precondition)即使在紧凑视图里也绝不省略。

pgbot inspect --full 子系统状态板

--full 视图:子系统状态板与明细表格

pgbot inspect --full 在仪表条之上多出一块状态板(statusboard.go 中的 buildBoard):每个子系统一行,status 列只有三个词——ok(绿)、warn(黄)、fail(红),外加一个数值列和备注列(如 84/300 连接、4 idle in txn、210 ms 复制延迟)。状态同样由触发该子系统的发现决定,底部还有一行汇总,如 1 failing · 2 warnings · 5 healthy。状态板之后才是各子系统的明细表格(Top 查询、闲置索引、死元组等)和每个发现的 caveat 说明。

从发现到行动:四条最常用的下钻路径

报告只告诉你"哪里不对",往下钻的入口在报告最后一行已经写明:

  1. 看细节:pgbot inspect --full —— 状态板 + 分节表格。
  2. 单信号深挖:pgbot indexes / pgbot queries / pgbot tables / pgbot vacuum,每个命令只钻一个信号。
  3. 机器可读:--json 输出带版本号的完整 Context(当前 1.5.0,JSON Schema 见 schema/),供脚本和 AI Agent 消费;也可用 --format=sarif|junit|prometheus 接入 CI。
  4. AI 解读:pgbot ask "why is it slow?" 或 pgbot explain —— 模型只解释同样的确定性发现,绝不生成发现;建议永远带着报告里的 caveat 一起给出。

pgbot ask AI 解读发现与护栏

退出码:把报告接入 CI 的契约

pgbot inspect 的退出码是公开契约(inspect.go 中的 exitCode 函数),可直接用于 CI 门禁:

退出码 含义
0 干净(无 warn 及以上发现,或全部被抑制)
1 至少一个 WARNING
2 至少一个 CRITICAL
3 连接/执行失败
64 用法错误(参数不对)

配合 --fail-on=critical|warn|info|none 可以调整"什么级别算失败";被抑制和已存在(--fail-on-new 基线中已有)的发现永远不影响退出码。

pgbot indexes 零扫描索引与删除前检查

新手常见误区与收尾清单

误区一:把健康分当精确指标。 82 分和 83 分之间没有可操作的差别,可操作的是发现列表本身。

误区二:在备库看到 unused_indexes 就删索引。 主库上"零扫描"只是该节点的视角,复制可能还在用它——报告里的 ⚠ 护栏行就是为此存在的,删除前务必先查副本的索引统计。

误区三:把 pgbot 当长期监控系统。 它是一次性点状诊断,不部署任何 Agent、不写库、不建表;需要仪表盘、告警和长时保留时,应搭配 pganalyze / PMM 这类平台使用。

收尾清单(报告读完后按顺序问自己):

读完这份报告,你应该能形成这样的习惯:先看仪表盘定基调,再看健康分定优先级,最后逐条处理发现——这就是 pgbot inspect 想要传达的"分级阅读"(graded read)。

登录后查看全文
pgbot