如何读懂 pgbot inspect 健康报告:仪表盘、健康分与 CRITICAL/WARNING/NOTE 发现的完整解读
如何读懂 pgbot inspect 健康报告:仪表盘、健康分与 CRITICAL/WARNING/NOTE 发现的完整解读
pgbot 是一款面向 PostgreSQL 的只读数据库体检工具:一条 pgbot inspect 命令,它连接数据库、采样统计视图,并打印一份"发现优先"(findings-first)的健康报告。对新手来说,第一次面对报告时最容易困惑的是:仪表盘四行进度条代表什么?Database health: 82/100 怎么算出来的?CRITICAL、WARNING、NOTE 三档发现又该怎么处理?这篇文章带你把 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发现。
三个阅读细节:
- 状态词即结论:
ok(绿)正常、watch(黄)需要留意、review(黄)建议排查、红色词(如low、query 4f2a)表示有对应发现触发。 - 测不出会明说:如果信号无法测量(比如样本太薄),该行显示灰色的
—并写明原因(thin sample、not measurable),而不是画一根像零的空条。 - 窗口太冷会降级:
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_connectionsunused_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)即使在紧凑视图里也绝不省略。
--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 说明。
从发现到行动:四条最常用的下钻路径
报告只告诉你"哪里不对",往下钻的入口在报告最后一行已经写明:
- 看细节:
pgbot inspect --full—— 状态板 + 分节表格。 - 单信号深挖:
pgbot indexes/pgbot queries/pgbot tables/pgbot vacuum,每个命令只钻一个信号。 - 机器可读:
--json输出带版本号的完整 Context(当前1.5.0,JSON Schema 见 schema/),供脚本和 AI Agent 消费;也可用--format=sarif|junit|prometheus接入 CI。 - AI 解读:
pgbot ask "why is it slow?"或pgbot explain—— 模型只解释同样的确定性发现,绝不生成发现;建议永远带着报告里的 caveat 一起给出。
退出码:把报告接入 CI 的契约
pgbot inspect 的退出码是公开契约(inspect.go 中的 exitCode 函数),可直接用于 CI 门禁:
| 退出码 | 含义 |
|---|---|
| 0 | 干净(无 warn 及以上发现,或全部被抑制) |
| 1 | 至少一个 WARNING |
| 2 | 至少一个 CRITICAL |
| 3 | 连接/执行失败 |
| 64 | 用法错误(参数不对) |
配合 --fail-on=critical|warn|info|none 可以调整"什么级别算失败";被抑制和已存在(--fail-on-new 基线中已有)的发现永远不影响退出码。
新手常见误区与收尾清单
误区一:把健康分当精确指标。 82 分和 83 分之间没有可操作的差别,可操作的是发现列表本身。
误区二:在备库看到 unused_indexes 就删索引。 主库上"零扫描"只是该节点的视角,复制可能还在用它——报告里的 ⚠ 护栏行就是为此存在的,删除前务必先查副本的索引统计。
误区三:把 pgbot 当长期监控系统。 它是一次性点状诊断,不部署任何 Agent、不写库、不建表;需要仪表盘、告警和长时保留时,应搭配 pganalyze / PMM 这类平台使用。
收尾清单(报告读完后按顺序问自己):
- ] 有 CRITICAL 吗?有 → 今天处理,参考对应 [findings 页面 的 "How to fix it"。
- [ ] WARNING 里哪条影响用户最明显(延迟、连接、膨胀)?排期。
- [ ]
checked行覆盖了哪些子系统?没被列出的子系统是"没采到"还是"有问题",看状态板即可分辨。 - ] 想留档?
pgbot report > report.html生成自包含的单页 HTML 报告([html.go)。
读完这份报告,你应该能形成这样的习惯:先看仪表盘定基调,再看健康分定优先级,最后逐条处理发现——这就是 pgbot inspect 想要传达的"分级阅读"(graded read)。



