Coroot Postgres 健康巡检（Inspections）实战指南：11 项自动检查、图表判读方法与源码实现解析

Coroot Postgres 健康巡检（Inspections）实战指南：11 项自动检查、图表判读方法与源码实现解析

【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot

Coroot 将 Postgres 视为一类需要持续体检的组件：由 cluster-agent 连接每个已发现的实例、读取pg_stat_activity、pg_stat_statements、pg_stat_replication等系统视图采集指标，再由审计器（auditor）基于这些指标运行一组带默认阈值的自动检查（availability、latency、replication lag、connections、checkpoints、WAL archiving、wraparound、autovacuum、stale statistics、bloat、backups），每项检查超标即产生告警并附带辅助图表。本文按官方文档 Postgres 巡检页 的脉络逐项讲解每个检查的触发条件、默认阈值、图表判读方法，并对照 auditor/postgres.go、model/check.go 等源码说明这些判定是如何落地的，帮助你在读完之后既能看懂巡检报告中的每一张图，也能定位到产生该结论的代码逻辑。

数据来源：cluster-agent 与系统视图

在深入各个检查之前，先明确数据链路。Coroot 的 Postgres 指标并非来自 Postgres 自带的 exporter，而是由独立的 cluster-agent 采集（见 cluster-agent 指标说明）：

• agent 通过 Coroot 服务地图和 Kubernetes 控制面发现数据库实例，使用 Coroot 提供或 Kubernetes 注解中的凭据连接 Postgres，每次抓取（scrape）时验证连接存活，形成pg_up指标；
• 指标来源包括pg_stat_activity、pg_stat_statements、pg_stat_replication、pg_stat_archiver、pg_stat_user_tables、pg_class等系统视图；
• 备份状态则不来自数据库本身，而是读取 CloudNativePG 和 Percona Operator 的自定义资源（见 Postgres backups）；
• 按查询维度的指标只对 TOP-20 按总执行时间排序的查询采集，且查询文本会被归一化、参数打码（例如SELECT * FROM tbl WHERE id='1'归并为SELECT * FROM tbl WHERE id=?），以避免标签基数爆炸；
• 查询 I/O 时间来自pg_stat_activity.wait_event_type = 'IO'与pg_stat_statements的blk_read_time/blk_write_time。

一个容易被忽视的前置条件：如果实例没有开启track_io_timing，按查询的 I/O 时间恒为零。Coroot 的巡检器会检测这种情况并在报告中直接给出配置提示——auditor/postgres.go 中的pgConfigurationHints函数会检查track_io_timing采样值，若为 0 则附加 "Enable track_io_timing to attribute disk I/O to specific queries" 的提示。

指标采集后由 constructor/postgres.go 组装成 model/postgres.go 中的Postgres结构：按连接状态分组的Connections、按查询键（db/user/query）分组的PerQuery（calls、total_time、io_time）、WAL 相关序列（WalCurrentLsn、WalReceiveLsn、WalReplayLsn、WalArchivedSegments等）、checkpoints、表级死元组与膨胀数据、Settings参数序列等，全部以*timeseries.TimeSeries时间序列形式保存，供审计器计算。

报告结构：检查项 + 实例总览表

巡检报告以一组自动检查开头，每个检查跨越阈值时产生告警，并附带支撑图表。阈值可按项目（project）配置，也可以按应用（application）单独覆盖。

检查项与默认阈值定义在 model/check.go 的Checks表中，汇总如下（均可在项目设置中调整）：

检查项下方是每实例总览表，列固定为 Instance（含版本标签）、Role（primary/replica 并带图标）、Status、Queries（QPS）、Latency（毫秒）、Replication lag（字节数 + 折算的时间）、DB Size。auditor/postgres.go 中tableColumns常量定义了这七列；Role 由ClusterRoleLast()得出，Status 列在实例不可用时展示 agent 记录的错误信息或 "down (no metrics)"，若存在告警则附带 warning 文本——这样一眼就能看出故障发生在 replica 还是 primary。

Availability：实例可达性

检测不可达或不接受连接的 Postgres 实例。agent 在每次抓取时验证连接存活（pg_up），检查项统计实例不可用的时间占比；IsUp()在 model/postgres.go 中就是Up.Last() > 0的简单判断。不可用时，auditor/postgres.go 会把实例加入availabilityCheck，并从Postgres.Error（对应采集侧的pg_scrape_error）取出错误文案写入 Status 列。

Latency：平均查询延迟

对平均查询延迟超过阈值（默认 0.1s）的实例告警。Coroot 把pg_stat_statements中已完成查询的统计与pg_stat_activity中的在途查询合并（采集侧由pg_top_query_calls_per_second、pg_top_query_time_per_second两个指标支撑，后者对在途查询用clock_timestamp() - pg_stat_activity.query_start计时），因此慢查询在结束之前就能被看见。

报告为每个实例提供以下图表用于定位原因：

• Average query latency（avg、p50、p95、p99，来自pg_latency_seconds的各 summary 标签）。分布形态能告诉你劣化形状：p50 上升说明所有查询都变慢；p99 上升而 p50 持平说明只有少数慢查询长尾。用选择器切换实例可判断是集群性问题还是单节点问题。
• Queries per second。负载在涨还是在跌。如果延迟上升但查询量没有增加，原因在数据库内部（锁、I/O、坏执行计划）而非入口流量。
• Queries by total time。按消耗容量给查询排名，榜首通常是该优化的对象；某条查询突然冲到这里往往是性能回归点。
• Queries by I/O time。若慢查询的时间主要花在 I/O 上，说明它在等磁盘（缺索引或缓存未命中）而不是 CPU。
• Active connections by query与Idle transactions by query。展示繁忙 backend 实际在跑什么，并暴露持有锁和快照的idle in transaction会话。
• Locked queries与Blocking queries。当劣化源于争用时，直接点名阻塞其他查询的那条查询——阻塞方是通过pg_blocking_pids()归因的（采集指标pg_lock_awaiting_queries的blocking_query标签即由此计算）。

auditor/postgres.go 中，pgQueries函数从PerQuery中拆出TotalTime与IoTime两张 Top-5 堆叠图；延迟告警的判定就是对i.Postgres.Avg.Last()与latencyCheck.Threshold比较。

Replication lag：复制延迟

检测落后主库过多的副本（默认 30s）。Coroot 刻意把复制拆成两个阶段，以区分*传输（shipping）问题（网络或 WAL sender）与回放（apply）*问题（replay 卡住或被暂停）。

源码实现清晰印证了这一点：auditor/postgres.go 中先用所有实例WalCurrentLsn的Max聚合出主库 LSN，总延迟为primaryLsn - replayLsn，而 "Replication stages" 图用两条堆叠序列分别绘制shipping (not yet received)=primaryLsn - receiveLsn与apply (received, not yet replayed)=receiveLsn - replayLsn。

图表判读方法：

• Replication lag, bytes。每个副本落后主库多远。看缺口是平稳的（跟得上但一直落后）还是持续爬升（越落越远），以及落在哪个副本上。
• Replication stages。shipping 段占主导，说明 WAL 没到达副本（网络问题，或 WAL sender 慢/过载）；apply 段占主导，说明 WAL 已到达但回放卡住，典型原因是副本上的长查询引发 recovery conflict，或 replay 被暂停。
• WAL throughput。主库上的 WAL 生成突发可以解释临时延迟尖峰——副本只是有更多数据要追。

副本卡住时，Coroot 还会直接点名原因。checkReplicationLag除了比较延迟字节数，还会沿主库 LSN 序列回溯，把字节差折算成时间差展示；pgWalStallCause按优先级输出具体原因：pg_wal_replay_paused置位 → "WAL replay is paused"；WalReceiverStatus为 0 → "the standby is not connected to the primary"；否则比较 apply 与 shipping 的大小，输出 "WAL replay is slow or blocked (check standby queries and disk I/O)" 或 "WAL shipping can't keep up (network or primary load)"。

Connections：连接数

当实例连接数逼近max_connections（默认 90%）时告警。连接耗尽会阻止新客户端接入，包括故障切换工具。

判定逻辑在pgConnections函数：按连接状态（idle、active、idle in transaction，以及active且wait_event_type = 'Lock'时单独归入active (locked)）聚合连接数，再叠加保留连接——代码同时读取superuser_reserved_connections和rds.rds_superuser_reserved_connections两个参数，因此也覆盖了 AWS RDS 的保留连接语义。连接总数 /max_connections× 100 超过阈值即加入检查项。

图表判读：

• Connections。按状态堆叠并画出max_connections参考线。观察总量离线多近、哪个状态在涨。一片idle in transaction通常意味着客户端开了事务却不提交（应用 bug 或泄漏的事务），这些会话还持有锁和快照，会阻塞 vacuum 和其他查询。
• Idle transactions by query。点名哪些查询的会话停在 idle in transaction，帮你定位出问题的代码路径。
• Active connections by query。连接尖峰时活跃 backend 在跑什么，指向驱动需求的负载。

Checkpoints：检查点停滞

标记停滞或逾期的 checkpoint。距上次完成 checkpoint 过久会拉长崩溃恢复时间，也可能意味着 checkpointer 卡住或 WAL 压力过大。Coroot 与复制检查共享同一套 WAL 停滞诊断（pgCheckpointStallCause先调用pgWalStallCause），例如磁盘满、archiver 卡住、复制槽扣留 WAL 等。

源码中告警条件比较严格，两个条件同时满足才计入：距上次 checkpoint 超过checkpoint_timeout × 阈值倍数（默认 3 倍），且自上次 checkpoint 以来积累的 WAL 超过一个 16MB 段（pgWalSegmentSizeBytes）。避免在低负载时段因定时 checkpoint 尚未触发而误报。

图表判读：

• Time since last checkpoint。对照阈值线（图中线即阈值倍数 × checkpoint_timeout）。持续越过线说明 checkpoint 未完成。
• WAL to replay in the case of a crash。崩溃需要重放的 WAL 量，即你的恢复时间。健康时应呈锯齿状在每个 checkpoint 处回落；持续爬升印证 checkpoint 没完成。
• Checkpoints与Checkpoints by trigger。如果以requested（由max_wal_size触发）为主而非timed（由checkpoint_timeout触发），说明max_wal_size相对写入速率偏小，导致频繁且昂贵的 checkpoint。
• Checkpointer write throughput。checkpointer 刷脏页的工作强度，用于把 checkpoint 尖峰与 I/O 压力关联起来（序列值为 buffer 数 × 8kB 块大小，代码中pgBlockSize = 8192）。

WAL archiving：归档失败

检测失败的 WAL 归档（archive_command）。WAL 无法外运时会在本地磁盘堆积，并破坏时间点恢复（PITR）。该检查基于pg_stat_archiver，对任意 Postgres 生效，不依赖 operator。

实现上是单点判断：pgArchivingIsFailing检查WalArchivingStatus.Last() == 0（archiving 状态不是 "ready"），成立则给该实例追加详情 "the last WAL archive attempt failed - check archive_command and the archive storage"。图表为每实例的 archived 与 failed 分段柱状图，failed系列出现任何柱子即表示archive_command在报错（凭据错误、存储不可达、桶已满）。归档失败时 WAL 无法回收，WAL 目录会持续增长（见下文 Storage & WAL），且 PITR 不再有完整归档。

Transaction ID wraparound：事务 ID 回绕

当最老事务或多事务（multixact）age 逼近回绕上限时告警（默认：2 billion 预算的 50%）。放任不管会触发紧急 anti-wraparound vacuum，最终可能导致数据库为保护数据而关闭，值得尽早发现。

源码细节：auditor/postgres.go 中回绕上限常量pgWraparoundLimit = 1 << 31（约 21 亿），告警值按worstAge / pgWraparoundLimit × 100计算。图表判读：

• Transaction ID age与Multixact ID age。按库的 age，对照autovacuum_freeze_max_age参考线。逼近线的库正在接近强制 anti-wraparound vacuum；某个库的 age 稳定增长指向 vacuum 没有冻结其表。
• Oldest transaction ID held back。把钉住冻结地平线（freeze horizon）的原因归因到四类持有者：running_transaction、replication_slot、standby_feedback、prepared_transaction，直接告诉你该终止或清理什么，让 vacuum 能重新推进地平线。

归因逻辑在pgDominantXminHolder中，并带两个经验比例：持有者 age ≥ 冻结 age 的 80%（pgXminHolderDominantRatio）时判定"vacuum cannot freeze past the oldest transaction ID"，并给出对应动作——drop/推进落后槽、结束长事务、提交或回滚 prepared 事务、降低开了hot_standby_feedback的 standby 延迟；若持有者年龄只占 10%（pgXminHolderMaterialRatio）以下，则回落到 "autovacuum is not freezing fast enough" 的通用建议。若是长事务，还会附上最老事务所在库、已开启时长与查询文本。

Autovacuum：vacuum 落后

检测 autovacuum 落后（默认：死元组达到该表 autovacuum 触发阈值的 2 倍以上）。vacuum 跟不上时，膨胀与回绕风险都会增长。

"压力"指标的定义是精髓：死元组数 ÷ (autovacuum_vacuum_threshold + autovacuum_vacuum_scale_factor × reltuples)，即归一化到该表自己的触发阈值。健康表围绕 1 锯齿波动（越过 1 才会触发 vacuum），持续高于 1 说明没被服务到；因为归一化了，大表的正常峰值不会误报。

auditor/postgres.go 的pgAutovacuum实现里还有几个避免误报的门槛：只有死元组字节数 ≥ 512 MiB（pgDeadTupleMinBytes）的表才参与告警排序——这样你关注的是真正持有大量可回收空间的表，而不是一个远超触发阈值的小表。此外计算触发阈值时支持读取表级ALTER TABLE ... SET (autovacuum_vacuum_threshold / scale_factor)覆盖值（pgTableSetting）。

图表判读"是否落后"与"为什么"：

• Autovacuum Pressure。见上。
• Dead tuples by table。以字节计的体量，聚焦真正持有大量可回收空间的表。
• Time since last autovacuum by table。表若很久以前才被 vacuum，说明 autovacuum 没在跑（被禁用、被饿死或参数失当）；若最近刚 vacuum 过死元组却还在堆积，说明有快照钉住了 vacuum 地平线（长事务、prepared 事务或复制槽）——此时看上面 Oldest-xmin holder 图。
• Autovacuum workers与Throttled autovacuum workers。若所有 worker 都忙（代码判定：最近 5 个点均值 ≥autovacuum_max_workers − 0.5），vacuum 在等空闲 worker（提高autovacuum_max_workers）；若 worker 已在表上但处于限流状态（单表 throttled 均值 ≥ 0.5），说明它在 cost-based delay 上睡觉（提高autovacuum_vacuum_cost_limit或降低autovacuum_vacuum_cost_delay）。

源码中最有实战价值的是根因文案：pgAutovacuum会为最严重的表生成具体原因——表上autovacuum_enabled=false、"某类持有者钉住了 vacuum 地平线"（并附最老长事务的库与查询）、"vacuum 在跑但太慢（大表或慢存储）"、"被该表自定义的 cost_delay/cost_limit 限流"、"worker 忙但被 cost 上限限流，加 worker 也没用"、或 "autovacuum last ran N ago"。同时它按根因类型动态挂载对应图表（复制槽问题挂 slots 图、长事务挂 longest transaction 图、限流挂 throttled 图），让报告里出现的就是与诊断结论相关的证据。

Stale statistics：统计信息过期

检测规划器统计信息过期的表（默认：修改行数达到 autoanalyze 触发阈值的 2 倍以上）。统计信息过期会让规划器选错计划，是批量加载或写入突发后延迟突然回归的常见原因。

• Autoanalyze Pressure。修改行数 ÷ 该表自己的 autoanalyze 触发阈值（同样支持表级覆盖参数）。大表持续高于约 2x 说明近期没有 analyze，规划器在用过期行数估算。
• Time since last analyze by table。确认统计过期了多久，以及 autoanalyze 是否在该表上被禁用。修复手段就是执行ANALYZE。

源码中pgStaleStatistics设了一个过滤条件：只有reltuples ≥ 100000（pgStaleStatsMinRows）的表才会触发检查项，小表的统计过期没有实际影响。

Bloat：表与索引膨胀

估算表与索引的浪费空间，标记膨胀超过阈值的库（默认 50%）。膨胀空间只能靠VACUUM FULL、pg_repack或REINDEX归还给操作系统，区别于普通 vacuum 即可回收复用的死行。

• Estimated bloat by database。总估算浪费空间，看哪个库最差、是否在趋势性上涨。
• Top tables by estimated bloat与Top indexes by estimated bloat。具体要处理的关系。膨胀表用VACUUM FULL或pg_repack重写，膨胀索引用REINDEX重建。

pgBloat的判定有个门槛：只有膨胀量 ≥ 1 GiB（pgBloatMinBytes）的库才参与检查，避免小库因高比例产生噪音；超阈值时详情会给出 "is X% bloated (~Y wasted)" 并附上库内膨胀最严重的表/索引，结尾统一建议 "reclaim with pg_repack (online) or VACUUM FULL (locks)"。膨胀图与磁盘使用、最大表同组展示（见下文 Storage & WAL）。

Backups：备份健康

针对 CloudNativePG 或 Percona Operator 管理的集群，报告备份是否健康。告警条件包括：最近一次成功备份早于阈值（默认 24h）、备份失败、连续 WAL 归档损坏、或计划内备份逾期（由 cron schedule 与最近备份推导，调度器停摆也能被抓到）。备份失败时，Coroot 会直接展示 operator 的 condition reason 及可读化提示。

这一节展示备份状态、目标（destination）、计划（schedule）、保留策略（retention）、上次/下次备份、可恢复窗口，以及一个Recent backups列表（最多 20 条，含每次运行的类型、状态、完成时间）。

auditor/postgres.go 的pgBackups实现值得细看：

• 最近成功备份取各 method 的LastSuccessfulBackup与所有成功 run 完成时间的最大值；
• 逾期判定：解析备份的 cron schedule（先按标准 5 段格式，失败再尝试含秒的 6 段格式），从上次成功时间推出"本应发生的下次备份"，若当前时间超过该时点 15 分钟（pgBackupScheduleGrace）且没有备份正在进行，判定调度器可能没在跑；
• 原因聚合：无成功备份记录、"the last successful backup was N ago"、"the last backup attempt failed (reason)"、"continuous WAL archiving is failing"（当 operator 没有ContinuousArchivingcondition 时，回退到逐实例检查pg_stat_archiver状态）、"the cluster is not ready for backups"、"the pgBackRest repo host is not ready"；
• 条件原因可读化：pgConditionHint把StanzaNotCreated翻译为 "the pgBackRest repository isn't initialized - check the backup storage and credentials"，把RepoBackupNotComplete翻译为 "the initial repository backup hasn't completed"，其余原因原文透传——这就是文档中那句 "the pgBackRest repository isn't initialized..." 提示的出处。

Storage & WAL：磁盘空间去哪了

这组图表用于定位磁盘空间去向，尤其是 WAL 为什么释放不掉：

• WAL size, bytes。WAL 目录大小对照max_wal_size参考线（pgSettingBytes会把pg_settings中带单位的值——kB/8kB/MB/GB——换算成字节再画线）。WAL 目录远超max_wal_size几乎总意味着 WAL 删不掉：要么归档失败，要么复制槽在扣留。
• Replication slots retained WAL。每个槽扣留的 WAL。一个 inactive 且 retained WAL 持续爬升的槽是磁盘写满的经典原因，删掉无用的槽即可释放。
• Disk usage与Top tables by size。空间整体去向与最大的表。

auditor/postgres.go 的pgDiskUsageFindings还会做一层增长归因：对表体积与膨胀量序列计算增长率，某表的增长主要由膨胀贡献时会标注 "mostly bloat, consider reclaiming with pg_repack"；WAL 目录或某个复制槽的 retained WAL 增长超速率阈值时会被单列为磁盘增长点，归档失败时还会在 WAL 目录名后追加 "(archiving is failing, WAL cannot be recycled)"。另有pgIOFindings会在 I/O 负载高时输出 "disk writes are mostly WAL / checkpointer flushes" 与最耗 I/O 的查询名，把存储压力与具体来源挂钩。

小结

Coroot 的 Postgres 巡检把"DBA 值班清单"产品化：11 项检查各自有明确默认阈值（集中在 model/check.go，可按项目配置、按应用覆盖），每项检查背后是 auditor/postgres.go 中一套带防误报门槛（最小字节数、最小行数、最近 N 点窗口）的判定逻辑，并尽量把结论落到"具体是哪条查询、哪个表、哪个槽、哪个持有者"。排查时建议按报告顺序：先看总览表的 Role/Status/Lag 判断故障面，再进入对应检查项的图表按本文的判读路径定位根因；遇到 vacuum 相关结论时优先读检查项附带的根因文案，它已替你完成了大部分归因工作。

【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot