25 望闻问切：监控体系与可观测诊断

“有监控”很容易，“知道发生了什么”很难。

一个看起来成熟的平台可能同时拥有：

26 个 PostgreSQL 仪表盘
3,000 多种指标名
数百条记录规则
几十条告警规则
集中日志
追踪后端
值班通知

事故发生时却仍然只能说：

CPU 高了
连接多了
复制慢了
面板红了

这些句子描述了现象，没有回答五个决定性问题：

1. 用户旅程是否真的失败、变慢、读旧或产生错误结果？
2. 这是首发症状、伴随现象，还是已经被证据支持的机制？
3. 观察数据是零、尚未刷新、被重置、被采样，还是根本缺失？
4. 哪个 owner 应采取什么首个安全动作？
5. 什么证据能够证明恢复，而不是仅仅“面板变绿”？

第 24 章先定义了服务、SLI、SLO、控制目标、缺失语义和告警治理。本章做下一步：

observation contract
  -> 指标、日志、事件和追踪
      -> PostgreSQL 原生统计与 SQL 基线
          -> Pigsty 采集、存储、规则、面板和通知
              -> 可行动告警
                  -> 有界诊断包
                      -> 合成规则与离线路由演练
                          -> 覆盖表、盲区与生产门禁

这条链的重点不是“多收集一些数据”，而是让每个结论都能说明：

question       想回答什么
source         哪个系统产生事实
semantics      值、窗口、标签、reset 和缺失是什么意思
cost           采集、查询和保留会付出什么代价
action         谁可以做什么
verification   怎样证明结论与恢复
boundary       什么仍然不知道

本章目标

完成本章后，你应当能够：

1. 从用户、入口、数据库和主机四层组织观察问题；
2. 区分症状信号、原因信号、控制信号与监控系统自身信号；
3. 说明指标、日志、事件和追踪各自适合回答什么；
4. 为 label cardinality、采样、保留和查询成本建立预算；
5. 把“没有数据”区分为无流量、采集故障、查询错误、延迟与真实零值；
6. 正确读取 pg_stat_activity、pg_locks 与 wait event；
7. 使用 pg_stat_database、pg_stat_io、pg_stat_wal、 pg_stat_checkpointer 和 pg_stat_archiver；
8. 解释累计计数、瞬时状态、估算值和进度视图的不同时间语义；
9. 区分 WAL distance、时间 lag 与 commit-correlated freshness；
10. 观察 autovacuum、冻结年龄、dead tuple、对象增长和维护进度；
11. 正确解释 pg_stat_statements 的聚合键、reset、deallocation 与权限；
12. 解释为什么 normalized query text 仍不能随意进入证据；
13. 为慢语句、锁等待、临时文件和错误日志设置有界政策；
14. 评估 auto_explain 的 ANALYZE、timing、采样和参数泄露成本；
15. 把第 24 章 SLO 合同变成 multiwindow、multi-burn-rate 规则；
16. 区分 page、ticket、diagnostic 与 proposed test route；
17. 为 alert 的 for、分组、抑制、恢复和缺失语义写测试；
18. 防止 fast burn、slow burn 与预算工单形成重复风暴；
19. 防止 metamonitoring 抑制独立用户症状或正确性告警；
20. 理解 Pigsty v4 的 VictoriaMetrics、VictoriaLogs、VictoriaTraces、 VMAlert、Alertmanager、Grafana、pg_exporter 与 Vector；
21. 用 cls、ins、ip、database 与 queryid 在不同粒度间下钻；
22. 从仪表盘回到 PostgreSQL SQL、日志和主机事实复核；
23. 自动保存有界、私密、可复验的诊断包；
24. 区分首发症状、相关现象、候选机制与根因；
25. 限制诊断查询的 timeout、并发、结果量和权限；
26. 用隔离时间序列验证 pending、firing、recovery 与 missing；
27. 用空 receiver 离线验证路由，不触碰真实 pager；
28. 输出覆盖矩阵，诚实标出尚未实现的应用 SLI；
29. 对当前沙箱给出“机制通过、生产待决”的可审计结论。

本章不做什么

本章不是一个“复制几十条 PromQL 就上线”的规则包，也不会：

• 把当前沙箱阈值包装成所有生产环境的通用答案；
• 修改在线 VMAlert、Alertmanager、Grafana 或 PostgreSQL；
• 向在线 Alertmanager 提交合成告警；
• 接入 webhook、邮件、短信、Slack 或真实 pager；
• 运行 EXPLAIN ANALYZE、压测、统计 reset 或数据库故障注入；
• 导出 query text、bind value、日志正文、client address 或凭据；
• 用 pg_up=1 证明订单服务可用；
• 用 pg_lag=0 证明 read-your-writes；
• 用 failed_count>0 直接证明归档仍在失败；
• 用“当前无告警”证明通知链可达；
• 用一次仪表盘相关性宣布 root cause；
• 声称 pg36_shop 已经具有真实应用埋点。

实验使用 pg36_shop 这一 synthetic teaching service。应用层五种信号仍是刻意 保留的缺口：

request outcome counter
request duration histogram
commit-correlated freshness probe
domain reconciliation gauge
restore-evidence age gauge

缺口不是失败的写作，而是本章必须保留的事实。如果没有应用事件，平台不能从 数据库组件指标“推算”出一个看似完整的用户 SLO。

从监控到可观测诊断

监控回答已知问题

监控通常从一个已知条件出发：

if bad_ratio_1h > threshold
and bad_ratio_5m > threshold
for 2m
then page

它适合稳定、可计算、可自动执行的问题：

• SLO 是否快速燃烧；
• exporter 是否持续不可达；
• 规则是否持续报错；
• 恢复证据是否超过政策期限；
• 容量预测是否进入评审窗口。

可观测诊断解释未知状态

诊断从“不知道为什么”出发，需要沿不同证据层缩小假设：

user latency burn
  -> entry queue or rejection?
      -> pool saturation or connection churn?
          -> PostgreSQL active wait or lock?
              -> queryid cost or plan drift?
                  -> storage, WAL, checkpoint, vacuum or host constraint?

可观测性不是一个产品名，也不是“拥有 logs + metrics + traces”自动获得的属性。 它要求系统输出足够的、语义明确的证据，让操作者能区分多个竞争解释。

诊断不等于根因

本章采用四层语言：

“两条线一起升高”最多是相关性。要升级为根因，至少需要：

mechanism
independent corroboration or reproduction
falsification attempts
repair verification

四层问题，而不是四套孤岛面板

本章把信号按问题分为四层：

从下往上推断很危险：

CPU 90%
  therefore users are slow          # 不成立

one replica is down
  therefore service is unavailable  # 不成立

pg_up == 1
  therefore orders are correct       # 不成立

从上往下诊断更稳健：

user symptom is real
  -> locate affected operation and path
  -> correlate entry and database evidence
  -> test competing mechanisms
  -> choose the least harmful action
  -> verify user and control signals

正确性与恢复就绪又是特殊控制：

one unexplained cross-tenant row
  cannot be averaged away

old or missing restore evidence
  cannot be replaced by backup job success

四种信号，各有边界

四者不是竞争关系：

metric detects
event bounds the change window
trace follows one affected request
log explains a discrete failure
SQL verifies PostgreSQL state

同样，也不应强迫每个问题都使用四种信号。一个能够由累计计数精确回答的问题， 不需要先扫描全部日志；一个需要参数上下文的问题，也不应把 error text 做成 metric label。

时间语义比数值更重要

观察数据至少有五种时间性质：

还要处理采集链延迟：

database state time
  -> exporter scrape time
      -> storage ingestion time
          -> rule evaluation time
              -> route grouping delay
                  -> receiver delivery time

如果数据源有意延迟 30 秒，而规则在“当前时刻”查询，最新样本可能尚未可见。 VMAlert 支持 evaluation delay；正确值取决于实际采集和存储延迟，不能机械照抄。

本章的规则分层

实验生成 18 条记录规则和 13 条告警规则。它们分成三类：

第 24 章已经接受的七条

仍待治理接受的六条

latency burn
restore evidence stale
active archive risk
long transaction horizon
freeze-age horizon
expected traffic but SLI missing

它们有完整规则和测试，但统一标记：

route: test
severity: candidate
governance_status: proposed-not-accepted

“代码写好了”不等于“组织接受了 page/ticket 政策”。这个显式不一致检查很重要： 第 24 章定义了 latency SLO，却没有接受 latency alert candidate。本章没有暗中 补齐生产政策，而是把它暴露为待决项。

诊断记录

复制距离、长事务、freeze age、dead tuples、exporter 状态、VMAlert rule error 和 notification failure 首先是诊断或控制输入。它们不会因为“容易写阈值”就 自动变成 page。

当前沙箱的真实快照

正式实验公共摘要： observability-run.json。

采集时间为 2026-07-29T22:48:21Z。快照只代表该时刻：

目标身份通过三层交叉确认：

host            pg-test-1
Patroni scope   pg-test
PostgreSQL      cluster_name=pg-test
role            primary
replication     pg-test-2 + pg-test-3, async streaming
observed WAL gap 0 + 0 bytes

0 bytes 是当时的发送—回放距离，不是 read-your-writes 证明。

pg_stat_statements 快照：

extension version      1.12
schema                 monitor
rows                   194
calls                  122,303
query text exported    false
stats reset            retained

归档快照有一个关键反例：

failed_count           21
last failure           18:57:58Z
last successful archive 22:27:54Z

如果规则只是：

pg_archiver_failed_count > 0

它会在系统已经恢复后永久报警，直到统计被重置。候选规则因此同时检查：

15m 内出现新失败
AND 最近成功归档已经停滞

再回到 pgBackRest 与恢复证据复核。累计 counter、当前故障和恢复就绪是三个 不同结论。

实验为什么分成在线与隔离两部分

在线只读基线

在线部分只做：

• HTTP health/API/metrics 读取；
• VictoriaMetrics 即时查询；
• 通过元节点进入真实 pg-test-1；
• 带 statement_timeout=5s、lock_timeout=500ms 的只读 SQL；
• 聚合 activity、locks、I/O、WAL、checkpointer、archiver、 replication 和 pg_stat_statements；
• 记录版本、reset、freshness 与缺口。

不会 reset、reload、写表、运行计划、制造负载或读取 query text。

隔离规则与路由

规则文件上传到沙箱元节点的：

/tmp/pg36-ch25.XXXXXXXX

随后：

1. vmalert -dryRun 检查规则语法；
2. vmalert-tool 启动 loopback-only VictoriaMetrics；
3. 注入合成时间序列；
4. 验证 normal、pending、firing、recovery 和 missing；
5. amtool check-config 检查 Alertmanager 配置；
6. 用八组标签离线解析到空 receiver；
7. 用五个用例验证抑制边界；
8. 清理临时目录并确认目录不存在。

它不会接触在线 VMAlert 或在线 Alertmanager。

本章目录

25.1 从问题选择可观测信号

• 25.1.1 用户体验、服务入口、数据库与主机四层
• 25.1.2 指标、日志、事件和追踪各回答什么
• 25.1.3 标签基数、采样、保留与缺失数据

25.2 PostgreSQL 核心运行信号

• 25.2.1 会话、事务、等待与锁
• 25.2.2 缓冲、I/O、WAL、检查点与复制
• 25.2.3 vacuum、冻结、膨胀与对象增长

25.3 SQL 可观测基线

• 25.3.1 pg_stat_statements 的统计口径与重置
• 25.3.2 慢语句、锁等待、临时文件与错误日志
• 25.3.3 auto_explain 的采样、嵌套语句与开销
• 25.3.4 日志不得泄漏密码、令牌和敏感参数

25.4 把观察契约变成告警

• 25.4.1 SLO 燃烧率与用户影响
• 25.4.2 阈值、持续时间、去抖、抑制与分组
• 25.4.3 每条告警绑定所有者、证据和首个安全动作
• 25.4.4 用演练验证告警，而不是等生产事故

25.5 Pigsty 可观测体系

• 25.5.1 采集、存储、规则、面板与通知链
• 25.5.2 以指标语义定位集群、实例、数据库和查询
• 25.5.3 面板结论回到 SQL、日志与主机事实复核

25.6 从告警到诊断包

• 25.6.1 自动保存时间窗、拓扑、变更与关键查询
• 25.6.2 区分首发症状、伴随现象与根因证据
• 25.6.3 证据采集本身的负载和权限边界

25.7 实战：实现并演练观察契约

• 25.7.1 为延迟、错误、复制、备份和资源建立规则
• 25.7.2 注入可控症状，验证触发、路由、抑制和恢复
• 25.7.3 输出告警覆盖表、盲区与 ch31 的诊断入口

官方资料

本章技术语义优先回到原始文档：

• PostgreSQL 18 Monitoring Database Activity
• PostgreSQL 18 Cumulative Statistics
• PostgreSQL 18 pg_stat_statements
• PostgreSQL 18 auto_explain
• PostgreSQL 18 Error Reporting and Logging
• PostgreSQL 18 Routine Vacuuming
• Pigsty PostgreSQL Monitoring
• Pigsty PostgreSQL Dashboards
• Pigsty pg_exporter
• VictoriaMetrics VMAlert
• VictoriaMetrics vmalert-tool
• Prometheus Alerting Rules
• Prometheus Unit Testing Rules
• Alertmanager Configuration

下一章 第 26 章 容量规划与压测基线 会在这些观察 语义之上建立需求模型、容量水位和可比较基线；第 28 章 VACUUM、冻结与膨胀治理 再深入维护信号。第 31 章把本章的诊断包作为故障排查入口，处理慢查询、锁、 连接、复制与磁盘等具体事件。

上一章：纲举目张：SLO、SOP 与组织治理 · 返回下卷导读 · 下一章：胸有成竹：容量规划与压测基线 · 查看全书目录 · 查看索引中心

25.1 从问题选择可观测信号

先选指标，再问它能说明什么，是监控系统膨胀的主要原因。

有 PostgreSQL
  -> 收集所有 pg_* 指标
      -> 导入所有 dashboard
          -> 给红色曲线加阈值
              -> 事故时再猜它们与用户有什么关系

更可靠的顺序是：

decision
  -> question
      -> evidence
          -> semantics
              -> collection cost
                  -> action and verification

例如，“副本 lag 多大”不是一个完整问题。它可能对应三种完全不同的决定：

一个 pg_lag 无法同时替代这三个答案。

本节建立一份问题驱动的信号合同。可执行版本见 signal-contract.json。

25.1.1 用户体验、服务入口、数据库与主机四层

第一层：用户是否获得了正确服务

用户层不是浏览器 RUM 的同义词，而是最接近服务承诺的测量点。对 pg36_shop：

journey       place-order
eligible      authorized and valid request admitted by the app
good          success returned and token reconciles to one committed order
timely        final result within 250 ms
fresh         committed token visible on declared read path within 5 s
correct       no unexplained invariant mismatch

这些定义直接决定分子和分母：

$$ \text{availability bad ratio}

\frac{\text{failed or unreconciled eligible attempts}} {\text{all eligible attempts}} $$

如果只收 HTTP 2xx/5xx，会漏掉：

• 返回 200，但事务后来失败；
• 客户端超时，但写入已经提交；
• 重试创建了两个订单；
• 响应成功，但订单属于错误租户；
• primary 写入成功，随后从副本读取不到；
• 应用在 admission 前正确拒绝无效请求。

所以用户层信号常常要组合两个测量点：

application edge outcome
  +
commit outcome / idempotency reconciliation

eligible event 必须先定义

没有 eligible 分母，错误率会随着流量分类任意变化。例如：

all inbound requests
  includes scanners, malformed requests, health checks, unauthorized calls

admitted order attempts
  excludes pre-admission syntax and authorization rejection
  includes server outcomes after admission

“用户断开”是否计入也不能临场决定：

disconnect before admission and no server outcome
  -> may be excluded by a predeclared rule

disconnect after transaction may have committed
  -> unknown outcome, must reconcile

正确性不是可用性的一部分

如果 10,000,000 个订单中有一行串租：

availability could still be 99.99999%
security and correctness are still failed

因此正确性使用 control signal：

pg36_shop_reconciliation_mismatches > 0

它需要：

• invariant 是有界枚举；
• reconciliation 有输入边界；
• 结果有 hash 或不可变运行记录；
• stale/missing 本身是控制失败；
• 修复后由独立核对确认，而不是把 gauge 手工设为零。

第二层：请求在哪个入口发生了什么

入口层回答的是路径问题：

client
  -> application edge
      -> HAProxy service port
          -> PgBouncer pool
              -> PostgreSQL session

每个入口有不同的拒绝、排队和重试语义：

“连接数高”可能代表：

healthy concurrency
idle application connections
pool wait
session leak
long transaction
blocked query fan-out
maintenance workers

如果没有入口身份与状态，单个总数无法区分。

用 operation class，避免用 endpoint 爆炸

应用指标需要能分段，但不能把完整 URL 做标签：

good:
  operation_class="place-order"
  operation_class="read-order"
  operation_class="reconcile-order"

bad:
  path="/tenant/123/order/9a7..."

operation class 是有界业务语义；原始 path 可能包含 tenant、order 和 token， 既造成 cardinality 爆炸，也造成数据泄露。

第三层：PostgreSQL 能否解释用户症状

数据库层分成当前状态与累计事实：

current
  pg_stat_activity
  pg_locks
  progress views
  pg_stat_replication

cumulative
  pg_stat_database
  pg_stat_io
  pg_stat_wal
  pg_stat_checkpointer
  pg_stat_archiver
  pg_stat_statements

它们回答：

• 请求是否在 PostgreSQL 内；
• backend 在 CPU 上运行还是等待；
• 等待是 lock、I/O、client、WAL、buffer pin 还是其他类别；
• transaction 已持续多久；
• 哪个 queryid 消耗时间、I/O、临时块或 WAL；
• checkpoint 写入和同步成本如何变化；
• WAL 生成、发送、归档和回放是否推进；
• vacuum/freeze 是否被阻止；
• dead tuple、对象大小和统计新鲜度如何变化。

它们不直接回答：

• 用户请求是不是 eligible；
• 应用是否返回了正确结果；
• 哪个 tenant 受到影响；
• 用户是否走了 replica read path；
• 恢复点是否被业务接受。

数据库信号是解释层，不是服务层的替代品。

current 与 cumulative 必须分开

下面两个事实可以同时成立：

pg_stat_activity now shows no lock wait
pg_stat_database deadlocks counter increased in the last hour

前者是“现在没有”，后者是“窗口内曾经发生”。不能因为 current view 已经恢复， 就否定累计异常；也不能因为累计 counter 非零，就宣称当前仍在发生。

第四层：主机是否构成资源约束

主机层观察：

• CPU utilization、run queue、steal；
• memory pressure、swap、OOM；
• filesystem capacity、inode、mount state；
• block-device latency、queue、throughput；
• network loss、retransmit、bandwidth；
• clock synchronization；
• process、cgroup、systemd 和 kernel event。

主机指标要与 PostgreSQL 语义交叉：

high CPU
  + PostgreSQL active non-waiting backends
  + queryid execution time rises
  -> consistent with compute saturation

high CPU
  + user SLI healthy
  + batch window declared
  -> may be expected work

disk latency rises
  + pg_stat_io read_time rises
  + shared reads rise
  -> storage path becomes a stronger candidate

disk latency rises
  + PG reads unchanged
  -> investigate other processes or filesystem activity

主机指标很适合 falsify 假设。例如，若 PostgreSQL 认为 I/O 时间增加，而设备 层没有对应变化，可能是 OS cache、采集时间窗、虚拟化层或统计口径不同，而不是 直接得出“磁盘坏了”。

四层不是固定下钻顺序

通常从用户症状向下，但也有例外：

durability control
  archive stopped before user impact
  -> page is justified by imminent durability loss

metamonitoring
  rule evaluation failed
  -> health becomes unknown
  -> establish independent observation first

freeze-age horizon
  no current impact
  -> ticket before emergency anti-wraparound work

正确原则不是“永远只看用户”，而是：

page requires current user impact,
integrity/durability emergency,
or loss of the observation path.

原因和容量信号默认进入 diagnostic 或 ticket。

建立问题卡

每个新信号先填一张问题卡：

question: 已知 commit 是否在 replica read path 五秒内可见？
decision: 是否临时把 read-after-write journey 路由到 primary？
layer: user
source: commit-correlated synthetic probe
good: token visible within 5s
bad: token not visible within 5s
missing: unknown and probe-path failure
dimensions: [service, read_path, environment]
fallback: direct primary-path probe
owner: service
first_safe_action: preserve tokens and use primary path
verification: new tokens meet bound on declared path

若填不出 decision、missing 和 action，这个信号还不适合变成告警。

反例：从副本时间戳推用户新鲜度

常见快捷方式：

clock_timestamp() - pg_last_xact_replay_timestamp()

在一个空闲副本上，最近没有 WAL，它可能显示“很久以前”；但副本其实完全 追平。持续写入时，它又只能说明最后一次 replay 的时间，不知道用户关心的 commit 是否已经可见。

新鲜度需要：

write unique token
capture commit outcome
poll declared read path
measure until token visible

WAL distance 和 replay timestamp 仍有诊断价值，但不能替代 commit correlation。

25.1.2 指标、日志、事件和追踪各回答什么

metric：把总体变成可计算时间序列

metric 最适合：

• event ratio；
• latency distribution；
• rate、increase 和 trend；
• 容量 horizon；
• 规则自动评估；
• 多实例聚合。

四种常见类型：

counter 要转成窗口

rate(pg_db_xact_total[5m])
increase(pg_archiver_failed_count[15m])

不要：

pg_archiver_failed_count > 0

除非语义明确要求“生命周期内从未失败”。大多数运行告警关心的是新失败与当前 推进，而不是历史存在。

gauge 需要稳定条件

pg36_shop_restore_evidence_age_seconds > 90 * 24 * 60 * 60

evidence age 是 gauge，但它不是“数据库坏了”。它是恢复控制未满足，应进入 change gate 或 ticket，除非业务政策另有紧急定义。

histogram 要从 bucket 算事件比率

延迟 SLO 目标是 99% 在 250 ms 内：

$$ \text{latency bad ratio}

1 - \frac{\text{rate}(\text{bucket}_{le=0.25})} {\text{rate}(\text{count})} $$

它与 p99 不完全等价。event-based SLO 直接计算“多少 eligible events 超标”； quantile 是分布位置，适合探索，但不一定能直接算错误预算。

metric contract 的最小字段

name
type and unit
producer
labels and cardinality bound
counter reset or gauge freshness
scrape interval
retention
missing semantics
query examples
owner
deprecation plan

没有 type，就不知道能否 rate()；没有 reset，就不知道突然下降是改善还是 重启；没有 missing，就可能把 absence 变成健康。

log：保存离散上下文

日志适合回答：

• 哪个错误类别发生；
• 状态何时迁移；
• lock wait 在 deadlock_timeout 后是否被记录；
• 哪个 temporary file 被创建；
• Patroni 何时改变角色；
• pgBackRest 哪一步失败；
• 配置 reload 或连接认证发生什么。

日志不适合作为默认总体统计：

scan all PostgreSQL logs
count matching strings
divide by all lines

因为：

• 日志行不等于 eligible event；
• multiline 和格式变化影响计数；
• sampling 会丢事件；
• rotation/retention 改变分母；
• 查询成本随数据量增长；
• 原始 SQL、参数和用户信息可能泄露。

structured log 仍然需要 schema

推荐将字段分为：

stable dimensions
  cluster / instance / database / severity / error_code

bounded correlation
  release / operation_class / incident_id

restricted payload
  message / statement / detail / parameter

restricted payload 不应自动复制到 alert annotation、ticket 或公开 evidence。 “JSON 格式”只解决解析，不解决敏感性。

event：把变化放进时间线

发布、切换、配置和容量变化最好是结构化 event：

{
  "event_id": "change-20260729-017",
  "kind": "application-release",
  "target": "pg36_shop/l2-sandbox",
  "actor_role": "shop-release-operator",
  "started_at": "...",
  "completed_at": "...",
  "result": "success",
  "rollback_ref": "..."
}

它能帮助回答：

symptom started at 10:02
release completed at 09:58
pool config changed at 10:01
failover did not occur

event 本身仍不证明因果。一个发布接近事故，只是强候选，需要机制和修复验证。

event 的 clock 与 identity

事件至少记录：

• stable event id；
• actor role，而不是随意字符串；
• exact target；
• UTC 时间和时间源；
• request、approval、execution、result；
• rollback/roll-forward reference；
• source integrity。

若主机时钟相差两分钟，所谓“先发生”会被颠倒。诊断包要同时保存：

collector clock
database clock
rule evaluation clock

trace：跟随单次路径

trace 能展示：

edge span
  -> service span
      -> pool wait
          -> database call
              -> downstream service

它适合：

• 一次请求在哪里耗时；
• 重试和 fan-out 如何展开；
• 哪个 dependency 返回错误；
• sampled slow path 与正常 path 有何不同。

它不适合单独算完整 SLO：

• 采样意味着不是全部事件；
• tail sampling 会改变总体；
• trace backend 丢失不能解释为“无慢请求”；
• baggage 可能携带 tenant、token 或 PII；
• 数据库 span 未必包含真实执行等待。

不要把 SQL 文本塞进 span

推荐：

db.system=postgresql
db.namespace=test
db.operation.name=SELECT
db.query.summary=read-order
db.queryid=<bounded hash identity if policy allows>

谨慎或禁止：

db.statement=<raw SQL with literals>
bind.parameters=<customer data>
connection.string=<credential>

queryid 也不是绝对安全身份：它是 hash，可能冲突；相同文本在不同 search_path 下语义也可能不同。它的价值是聚合和关联，不是授权或数据分类。

四种信号如何组合

一个 latency fast burn 的调查：

metric
  availability healthy, latency bad ratio burns

event
  pool size changed four minutes before onset

trace
  sampled requests spend time waiting for a server connection

log
  PgBouncer reports pool saturation but no auth errors

SQL
  PostgreSQL active sessions and query cost are stable

host
  CPU and storage are stable

这组证据支持“入口池排队”而不是“数据库执行变慢”。如果回滚池配置后：

• queue 恢复；
• trace pool wait 恢复；
• user latency windows 恢复；
• 没有 correctness mismatch；

因果证据才明显增强。

选择最便宜的充分信号

同一问题可能有多种来源：

count transaction commits
  pg_stat_database counter        cheap, aggregate
  parse every log line            expensive, context-rich
  trace every transaction         very expensive, sampled

如果只需要总体 rate，优先 counter；若要解释一类错误，再查询有界日志；若要 追单次跨服务路径，再使用 trace。不要因为存储便宜就永久收集一切。

25.1.3 标签基数、采样、保留与缺失数据

cardinality 是维度乘积

一个 metric 的 series 数近似为：

假设：

service             20
environment         3
operation_class     30
status_class        6
release             10 retained concurrently
histogram bucket    15

则：

如果再加：

tenant_id  100,000
order_id   unbounded

系统不仅会爆炸，还会把业务标识复制到监控存储。

bounded label allowlist

本章允许：

Pigsty identity
  cls / ins / ip

service identity
  service / operation_class / environment

bounded optional
  read_path / invariant / recovery_class / objective_id / release

禁止：

customer_id / tenant_id / order_id / idempotency_token
trace_id / raw_sql / raw query text / error_message
client_addr / password / token

release 虽然有界，也要限制同时保留多少版本；滚动发布若不断产生唯一 commit SHA，而旧 series 长期不消失，仍会增长。

Pigsty 的 pg_query_* 指标有一个需特别说明的例外：label 名为 query，值是 数值型 queryid，而不是 SQL 文本。它的上限受 pg_stat_statements.max 约束； 仍要结合 database，并禁止把 raw query text 填进同名 label。

label 与 annotation 的边界

label 用于：

• series identity；
• query aggregation；
• alert grouping/routing；
• silence matcher。

annotation 用于人读的说明，不参与 series identity。但 annotation 也不能放 秘密。一个安全模式：

labels:
  service: pg36_shop
  operation_class: place-order
  environment: production
  objective_id: SLO-AVAILABILITY

annotations:
  summary: availability budget burning
  runbook: RB-USER-SYMPTOM
  dashboard: dashboard://pg36-shop-slo

不要：

labels:
  order_id: 8f...
  query: SELECT ...
annotations:
  error: password authentication failed for ...

先测 cardinality，再加维度

增加 label 前回答：

1. 值域是否有硬上限？
2. 谁控制它？
3. 每个值保留多久？
4. query 与 dashboard 是否真实使用？
5. alert 是否需要它来路由？
6. 是否能在日志/trace 中按需查，而不进入 metric？
7. 该字段是否是 PII、secret 或业务主键？

若只是“以后可能有用”，默认不加。

sampling 必须改变措辞

日志或 trace 被采样后，允许说：

sampled slow requests show pool wait

不允许说：

all slow requests are caused by pool wait

采样合同至少包括：

• head、tail 或 probabilistic；
• sample rate；
• error 是否强制保留；
• rate 随流量是否变化；
• dropped count；
• decision point；
• 是否能重建总体；
• 变更历史。

PostgreSQL log_min_duration_sample 与 log_statement_sample_rate 也是采样政策。 如果前者关闭，后者值为 1 并不代表所有语句都会被采样记录。

retention 决定能否回答窗口问题

若 SLO 是 rolling 28d，而原始 SLI 只保留 7d：

cannot recompute 28d objective from raw data

可以使用长期 recording rule，但必须记录：

• 原始数据保留多久；
• 聚合数据保留多久；
• rule expression 的版本；
• label 是否在聚合时丢失；
• reset/缺口如何进入结果；
• 回填是否发生。

诊断与治理保留期也不同：

“永久保存以备万一”通常同时违反成本和隐私原则。

缺失数据至少有七种解释

1. 真实没有事件
2. producer 没有初始化零 series
3. exporter 失败
4. scrape/ingestion 延迟
5. storage/query 失败
6. label 或 metric rename
7. service / instance 已按计划退役

还有 counter reset、staleness marker 和查询窗口不足。

absent() 不是万能答案

判断 SLI missing 需要一个独立期望：

pg36_expected_service_traffic == 1
unless on (service, environment)
pg36_sli_sample_fresh == 1

如果服务夜间没有流量，request counter 没新样本不一定故障。可以用：

• 独立 synthetic probe；
• admission counter；
• deployment/inventory declaration；
• scrape target freshness；
• expected schedule。

关键是不能用被监控对象自身同时证明“应该有数据”和“数据存在”。

zero、empty、NaN、stale 与 error

把 empty vector 用 or vector(0) 填零可能很危险：

bad_ratio or vector(0)

如果 bad ratio 消失是 exporter 故障，这会把“未知”变成“100% 健康”。只有在 零值语义、identity join 与独立 freshness 都被证明时，才能安全补零。

低流量与分母

本章记录规则没有用一个任意常数把分母抬高：

bad_rate / total_rate

低流量时要显式决策：

• 使用更长窗口；
• 同时要求 minimum event count；
• 使用 synthetic probe；
• 保持 unknown；
• 用 ticket 而不是 page；
• 聚合到更稳定的 operation class。

若写：

bad_rate / clamp_min(total_rate, 1)

每秒不到一个请求时，会改变真实 event ratio。clamp_min 可以防数值问题， 不能免费替代低流量政策。

counter reset

对 counter 使用 rate()/increase() 可以处理正常 reset，但仍要观察：

• reset 是否过于频繁；
• target identity 是否变化；
• scrape window 是否跨越长缺口；
• process restart 是否是事故的一部分；
• 历史 recording rule 是否有断点。

PostgreSQL 统计也有 reset：

pg_stat_* stats_reset
pg_stat_statements_info.stats_reset
per-row stats_since
minmax_stats_since

数值突然变小，必须先问 reset，而不是直接说“负载下降”。

监控系统也要被监控

至少观察：

• exporter/scrape freshness；
• VictoriaMetrics query 与 ingestion；
• VMAlert group/rule error；
• missed evaluation；
• Alertmanager notification failure；
• 独立 canary 的 receipt；
• external blackbox。

本章现场快照显示：

VMAlert rule errors                  0
VMAlert missed iterations nonzero   0
Alertmanager notification failures  0
current alerts                      0

这只能证明计数器当前没有记录失败。没有一条最近被 receiver 确认收到的 canary， 不能宣称真实通知链可达。

current lab cardinality snapshot

同一快照中：

VictoriaMetrics total series            44,842
total label-value pairs                 387,724
distinct metric names                   3,078
vmalert recording-rule series           698

这些是容量基线，不是目标上限。应当记录随时间的：

series growth rate
top metric by series
top label by values
unused/high-cost metric
query latency and cache pressure
retention impact

一个新 exporter 可能“工作正常”，但在一周内把 series 增长十倍。

信号引入评审

上线前用下面的表：

本节验收

你应当能够对任意一个候选指标回答：

它服务于哪一个决定？
属于用户、入口、数据库还是主机层？
它是症状、原因、控制还是 metamonitoring？
数值是 current、counter、window、estimate 还是 progress？
哪些 label 有界，哪些绝对不能进入？
缺失、reset、NaN 与低流量分别怎么处理？
采集和保留成本是多少？
谁看到它后可以安全地做什么？
哪个独立事实可以复核？

如果只能回答“Grafana 上有这条线”，信号合同还没有建立。

返回本章目录 · 下一节：PostgreSQL 核心运行信号 · 查看全书目录 · 查看索引中心

25.2 PostgreSQL 核心运行信号

PostgreSQL 自带两类观察接口：

dynamic current state
  当前 backend、锁、复制、进度

cumulative statistics
  自 reset 以来的 transaction、I/O、WAL、maintenance、statement

查询视图很简单，正确解释并不简单。以下事实可以同时成立：

pg_stat_activity 当前没有 lock wait
过去五分钟 lock wait 曾导致用户超时

pg_stat_archiver.failed_count = 21
当前归档已经恢复并持续成功

pg_stat_io.read_time 增加
物理磁盘没有等量读取，因为 OS page cache 参与

replica WAL distance = 0
应用仍可能因为路由、事务快照或缓存读到旧结果

n_dead_tup = 0
表仍可能存在已分配但未归还给操作系统的空间

本节目标不是记住所有列，而是掌握一套读法：

view
  -> source and update path
      -> current/cumulative/estimate/progress
          -> reset and snapshot
              -> independent corroboration
                  -> safe action

完整视图以当前版本官方文档为准： PostgreSQL 18 Monitoring Stats。

25.2.1 会话、事务、等待与锁

先确认统计功能是否开启

关键设置：

SELECT name, setting, unit, source
FROM pg_settings
WHERE name IN (
  'track_activities',
  'track_counts',
  'track_functions',
  'track_io_timing',
  'track_wal_io_timing',
  'stats_fetch_consistency'
)
ORDER BY name;

它们不是同一个开关：

统计有开销，timing 尤其依赖平台时钟成本；但关闭后必须把“未测量”保留下来。 绝不能把：

track_wal_io_timing=off
wal_write_time=0

解释为 WAL 写入没有花时间。

本章沙箱：

track_activities       on
track_counts           on
track_functions        all
track_io_timing        on
track_wal_io_timing    off
stats_fetch_consistency cache

pg_stat_activity 是当前 backend 视图

先使用不导出 query text 的聚合：

SELECT
  backend_type,
  state,
  wait_event_type,
  count(*) AS sessions,
  max(clock_timestamp() - xact_start)
    FILTER (WHERE xact_start IS NOT NULL) AS max_xact_age,
  max(clock_timestamp() - query_start)
    FILTER (WHERE query_start IS NOT NULL) AS max_query_age
FROM pg_stat_activity
GROUP BY backend_type, state, wait_event_type
ORDER BY backend_type, state NULLS LAST, wait_event_type NULLS LAST;

为什么带 backend_type？PostgreSQL 18 里不只有 client backend：

autovacuum launcher / worker
background writer
checkpointer
walwriter / walsender / walreceiver
io worker
slotsync worker
logical replication worker

如果把后台进程与 client backend 混在一起，某个长期运行的 background worker 可能被误判为“用户 SQL 运行几小时”。

state 与 wait_event 独立

常见错误：

state = active
  therefore CPU is executing

实际：

state=active, wait_event is null
  -> backend 正在运行，或刚好未被采样到等待

state=active, wait_event is not null
  -> SQL 仍是 active，但正在等待

state=idle, wait_event_type=Client
  -> 等客户端发下一条命令

state=idle in transaction
  -> 事务仍开着，可能保留 snapshot/lock/xmin

所以等待查询写成：

SELECT
  pid,
  backend_type,
  state,
  wait_event_type,
  wait_event,
  clock_timestamp() - xact_start AS xact_age,
  clock_timestamp() - query_start AS query_age
FROM pg_stat_activity
WHERE backend_type = 'client backend'
  AND state = 'active'
  AND wait_event IS NOT NULL
ORDER BY query_start;

这条查询没有读取 query 列。需要 SQL 上下文时，应在受限交互会话中按 queryid、application、database 和 owner 缩小范围，避免把全文复制进工单。

wait event 是“正在等什么”，不是“根因”

wait_event_type 先把等待分大类：

Lock
LWLock
IO
Client
IPC
Activity
Timeout
BufferPin
Extension

同一种等待可能有多种机制：

Lock
  application transaction contention
  DDL conflicting with queries
  idle in transaction retaining locks

IO
  cache miss
  sequential scan
  checkpoint-related work
  WAL read/write
  extension access

Client
  server waits for client
  slow consumer
  application not reading results

因此：

wait type
  -> affected backend/queryid
  -> blocker/resource
  -> user path
  -> corroborating counter/host evidence

才形成诊断。

PostgreSQL 18 的异步 I/O 引入 io worker 等 backend type 和相应等待。升级后 不要假设旧版 wait event 列表仍完整；dashboard 和规则要按当前版本校验。

当前统计在一个事务里可能保持不变

累计统计不是每次访问都无条件读取最新值。PostgreSQL 会把统计写入共享内存， 各进程最迟按一定节奏 flush；访问者又可能在当前事务内缓存读取结果。

这段会造成困惑：

BEGIN;
SELECT xact_commit FROM pg_stat_database WHERE datname = current_database();
-- 等待或在其他连接产生工作
SELECT xact_commit FROM pg_stat_database WHERE datname = current_database();
COMMIT;

在 stats_fetch_consistency=cache 下，同一事务后续读取可能继续看到缓存值。 诊断时优先：

每次采样使用短事务
不要在长事务里刷新 dashboard 数据
必要时调用 pg_stat_clear_snapshot()
记录采样时间和 stats_fetch_consistency

pg_stat_clear_snapshot() 清的是当前 session 的统计 snapshot，不是重置全局 统计；不要与 pg_stat_reset* 混淆。

统计更新也有时间边界

累计统计通常在 transaction 完成后才反映：

active transaction
  current activity can show it
  cumulative table/database changes may not yet be flushed

因此调查进行中的大事务：

• activity 看当前 transaction age；
• locks 看当前持有/等待；
• progress 看支持的维护动作；
• WAL/IO counter 看累计变化；
• 不等待累计表统计“先证明它存在”。

crash、恢复与复制会改变统计历史

PostgreSQL 正常关闭会保存累计统计；非正常关闭、从 base backup 恢复或 PITR 可能导致统计 reset。跨 failover 比较时：

same metric name
  does not imply same counter history

必须同时保存：

• member/timeline；
• stats reset；
• postmaster start；
• role transition；
• source instance；
• sampling window。

long query 与 long transaction 不同

query_age = now - query_start
xact_age  = now - xact_start

场景：

因此不要用 query_start 对所有 state 排序然后自动 cancel。

idle in transaction 为什么危险

它可能：

• 保留 row/table lock；
• 持有旧 snapshot；
• 阻碍 dead tuple 回收；
• 拉长 backend_xmin；
• 占用 connection/pool slot；
• 让后续应用错误更难定位。

诊断字段：

SELECT
  pid,
  datname,
  usename,
  application_name,
  state,
  clock_timestamp() - xact_start AS xact_age,
  wait_event_type,
  wait_event,
  backend_xid,
  backend_xmin
FROM pg_stat_activity
WHERE backend_type = 'client backend'
  AND state = 'idle in transaction'
ORDER BY xact_start;

取消或终止是变更动作，不属于本章 L0 采集。先确认：

• owner/application；
• transaction 是否仍有不可重试副作用；
• pool mode；
• unknown commit outcome；
• cancel 与 terminate 的差异；
• rollback/重连影响；
• 用户症状是否关联。

pg_locks 是锁申请，不是完整业务解释

安全聚合：

SELECT locktype, mode, granted, count(*) AS locks
FROM pg_locks
GROUP BY locktype, mode, granted
ORDER BY locktype, mode, granted;

找 blocker 可使用 pg_blocking_pids()：

SELECT
  a.pid AS waiting_pid,
  a.datname,
  a.usename,
  a.application_name,
  a.wait_event_type,
  a.wait_event,
  clock_timestamp() - a.query_start AS wait_age,
  pg_blocking_pids(a.pid) AS blocking_pids
FROM pg_stat_activity AS a
WHERE cardinality(pg_blocking_pids(a.pid)) > 0
ORDER BY a.query_start;

这个函数给出 blocker PID，但仍要判断：

direct blocker or blocker behind blocker?
transaction or prepared transaction?
DDL, row lock, advisory lock, relation extension?
which user journey?
is blocker making progress?
what is safe to cancel?

锁图而不是最长列表

事故中更有用的是：

waiting backend
  -> direct blocker
      -> root blocker
          -> owner / transaction age / state

并保存：

• edge 采样时刻；
• blocker state；
• backend_xid/xmin；
• queryid，而不是默认 query text；
• application/release；
• lock type/mode；
• user impact。

一条锁边可能瞬间消失。诊断包应保存有界快照，而不是事后只看当前视图。

deadlock 与普通阻塞

普通 lock wait 可以持续；deadlock 是一个等待环，PostgreSQL 会检测并中止其中 一个 transaction。

观察：

pg_stat_database.deadlocks       cumulative
log_lock_waits                   waits beyond deadlock_timeout
deadlock error log               discrete event
application retry/outcome        user semantics

log_lock_waits=on 只在等待超过 deadlock_timeout 后记录，短等待不会出现。 日志“没有 lock wait”不能证明没有短暂锁竞争。

权限边界

普通用户只能看到其他 session 的有限信息。pg_read_all_stats 能读取全库统计和 其他 session 的更多信息，但这仍然是高敏感可观测权限：

• query text 可能含业务值；
• application name 可能带身份；
• client address 暴露拓扑；
• activity 能推断业务行为。

建议：

exporter role
  stable, narrow, machine-only

interactive diagnostic role
  time-bounded, reviewed, pg_read_all_stats or narrower

evidence export
  aggregate and redact, no query text/client address

不要因为它不是 superuser 就把它当低风险权限。

查询本身也会进入观察结果

读取 pg_stat_activity 时，你自己的查询也是 active；访问许多系统视图也会拿 AccessShareLock。本章正式快照出现的 relation locks 就包括采集查询本身。

因此：

• 标识 collector application；
• 从结果中区分自身；
• 限制 statement timeout；
• 不在 tight loop 高频轮询；
• 避免一次展开所有 query text；
• 将 observer effect 写进证据。

25.2.2 缓冲、I/O、WAL、检查点与复制

数据路径不是“内存或磁盘”二选一

一个 PostgreSQL page 读取可能经过：

PostgreSQL shared buffers
  -> operating-system page cache
      -> filesystem / block layer
          -> physical or virtual storage

所以：

PostgreSQL read()
  may be satisfied by OS cache

shared buffer hit
  does not require an OS read

device read
  may be caused by another process

pg_stat_io 明确不区分物理磁盘和 OS page cache。必须结合 node/block-device 证据。

pg_stat_database 给出数据库级累计轮廓

常用字段：

SELECT
  datname,
  numbackends,
  xact_commit,
  xact_rollback,
  blks_read,
  blks_hit,
  temp_files,
  temp_bytes,
  deadlocks,
  blk_read_time,
  blk_write_time,
  stats_reset
FROM pg_stat_database
WHERE datname IS NOT NULL
ORDER BY datname;

它适合：

• database-level rate；
• hit/read 变化；
• temp spill 趋势；
• rollback/deadlock 变化；
• reset-aware baseline。

不适合：

• 归因到具体 query；
• 直接推物理 IOPS；
• 用 blks_hit / (blks_hit + blks_read) 单独判断内存是否足够；
• 比较不同 reset 区间的裸总数。

cache hit ratio 不是性能分数

$$ \text{hit ratio}

\frac{\Delta hits} {\Delta hits + \Delta reads} $$

即使正确用窗口增量，也受 workload 影响：

• 大表顺序扫描天然产生 reads；
• 小表热点容易高命中；
• OS cache 命中仍记为 PostgreSQL read；
• 低 hit 可能是合理批处理；
• 高 hit 不代表 CPU、lock 或 plan 健康。

把它作为 workload 特征，不要设一个跨服务的“低于 99% 就 page”。

pg_stat_io 按谁、什么对象、什么上下文拆分

PostgreSQL 18 可按：

backend_type
object
context

观察：

reads / read_bytes / read_time
writes / write_bytes / write_time
extends / extend_bytes / extend_time
hits / evictions / reuses
fsyncs / fsync_time

先聚合非零工作：

SELECT
  backend_type,
  object,
  context,
  sum(reads) AS reads,
  sum(read_bytes) AS read_bytes,
  sum(read_time) AS read_ms,
  sum(writes) AS writes,
  sum(write_bytes) AS write_bytes,
  sum(write_time) AS write_ms,
  sum(fsyncs) AS fsyncs,
  sum(fsync_time) AS fsync_ms
FROM pg_stat_io
GROUP BY backend_type, object, context
HAVING
  coalesce(sum(reads), 0)
  + coalesce(sum(writes), 0)
  + coalesce(sum(fsyncs), 0) > 0
ORDER BY backend_type, object, context;

窗口诊断需要两次快照求 delta 或 exporter counter rate。裸累计值只说明 reset 以来总量。

timing 要与 byte/count 一起读

read_time rises, read_bytes rises
  -> more work or slower work

read_time per read rises
  -> average operation cost rises, but distribution unknown

read_bytes rises, device reads stable
  -> OS cache may serve more reads

timing is zero and tracking is off
  -> unknown, not free

平均值会掩盖 tail。需要时结合：

• block-device latency histogram；
• request latency histogram；
• trace sampled tail；
• queryid-level I/O；
• workload mix。

buffer、backend 与 checkpoint 写入

dirty buffer 可能由 backend、background writer、checkpointer 等路径写出。 pg_stat_io 帮助按 backend type 区分；pg_stat_checkpointer 给 checkpoint 累计结果。

PostgreSQL 18：

SELECT *
FROM pg_stat_checkpointer;

重要字段包括：

num_timed
num_requested
num_done
restartpoints_*
write_time
sync_time
buffers_written
slru_written
stats_reset

解释：

requested checkpoint rate rises
  -> workload/config/administrative events may force checkpoints

write_time dominates
  -> checkpoint spreads writes

sync_time spikes
  -> fsync phase or storage path needs correlation

buffers_written rises
  -> more dirty data, not automatically a problem

不要只看一次 write_time 总值。计算每窗口的 checkpoint count、buffer、write 和 sync delta，再与用户 latency、WAL rate 和 host I/O 对齐。

checkpoint 不是越少越好

过频可能增加写入压力和 full-page image；过稀可能：

• 增加 crash recovery 时间；
• 需要更多 WAL；
• 在 checkpoint 集中更多工作；
• 改变恢复和容量特征。

任何调参要结合：

checkpoint completion
WAL generation
dirty buffer path
storage latency
recovery objective
memory and workload

本章只观察，不修改 checkpoint_timeout、max_wal_size 或 completion target。

pg_stat_wal 是 WAL 生成轮廓

SELECT
  wal_records,
  wal_fpi,
  wal_bytes,
  wal_buffers_full,
  stats_reset
FROM pg_stat_wal;

用途：

• WAL byte rate；
• full-page image 比例变化；
• WAL buffer full；
• 与 write workload、checkpoint、replication、archive 对齐。

不能直接说明：

• 哪个 query 产生 WAL；
• WAL 是否已归档；
• replica 是否已回放；
• recovery 能否成功。

query 归因需要 pg_stat_statements.wal_bytes 等；归档与恢复需要另外的证据。

full-page image 的上下文

checkpoint 后 page 首次修改可能记录 full-page image，以支持恢复。wal_fpi 变化与：

• checkpoint 频率；
• 工作集；
• full_page_writes；
• page 修改模式；
• compression；
• backup/recovery policy

相关。不要看到 FPI 高就关闭安全机制。

pg_stat_archiver 同时有 counter 和最后事件

SELECT
  archived_count,
  last_archived_wal,
  last_archived_time,
  failed_count,
  last_failed_wal,
  last_failed_time,
  stats_reset
FROM pg_stat_archiver;

三种不同问题：

历史是否失败过？
  failed_count since reset

最近是否出现新失败？
  increase(failed_count[window])

当前是否推进？
  last success age + WAL generation + archive queue

沙箱快照：

failed_count           21
last_failed_time       18:57:58Z
last_archived_time     22:27:54Z

最近成功晚于失败，说明历史 counter 非零不能证明当前仍失败。

候选告警：

pg36:archive_failures:increase15m > 0
and on (cls, ins, ip)
(time() - pg_archiver_finish_time) > 900

这仍只是 recovery risk candidate。下一步要复核：

• 当前 WAL 是否继续生成；
• archive command/pgBackRest 状态；
• repository；
• latest archive；
• backup/WAL coverage；
• 最近 restore drill。

“归档恢复”不等于“恢复就绪”。

replication 有位置、时间、状态三套语义

primary：

SELECT
  application_name,
  state,
  sync_state,
  sent_lsn,
  write_lsn,
  flush_lsn,
  replay_lsn,
  pg_wal_lsn_diff(sent_lsn, replay_lsn) AS sent_replay_gap_bytes,
  write_lag,
  flush_lag,
  replay_lag
FROM pg_stat_replication
ORDER BY application_name;

replica：

SELECT
  status,
  sender_host,
  sender_port,
  written_lsn,
  flushed_lsn,
  latest_end_lsn,
  last_msg_send_time,
  last_msg_receipt_time,
  latest_end_time
FROM pg_stat_wal_receiver;

公开/长期证据不一定应保存 sender/client address；可以保留 member identity、 state、sync_state 和位置差。

位置 gap

sent - write    network/receiver write path
write - flush   replica flush path
flush - replay  replay/apply path

位置差按 WAL byte 计，不是秒：

因为 replay throughput、workload、conflict、I/O 和 future WAL 都会变化。它可 用于容量与趋势，不应直接承诺 RTO。

时间 lag 可能是 NULL

write_lag、flush_lag、replay_lag 是最近同步交互产生的测量，并不保证 持续给出“当前落后秒数”。空闲系统可能为 NULL；这不等于零，也不等于故障。

使用：

• LSN distance；
• connection/state；
• last message；
• known commit probe；
• workload/WAL generation

共同解释。

本章正式 SQL 快照中，两条 streaming async replica 的 LSN gap 都为 0，而 lag interval 为 NULL。这正好说明：

NULL time lag
  can coexist with zero position gap in an idle/current sample

sync_state 与 commit durability

sync_state=async 表示它不是当前同步确认的一部分。即使 gap 为零：

• 后续 commit 仍可能尚未复制；
• primary 立即丢失会有 write gap 风险；
• 应用 commit acknowledgment 语义取决于 synchronous_commit 和配置；
• user freshness 取决于读取路径。

把 pg_stat_replication 与第 20 章 HA 合同一起读，不要从瞬时 gap 倒推出 durability guarantee。

replication slot 与 WAL retained risk

除了 replica gap，还要观察：

SELECT
  slot_name,
  slot_type,
  active,
  wal_status,
  safe_wal_size,
  pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)
    AS retained_bytes
FROM pg_replication_slots
ORDER BY slot_name;

slot identity 可能属于 extension/consumer；不要自动删除 inactive slot。风险：

• WAL retention 填满磁盘；
• logical consumer 落后；
• slot 失效；
• consumer 被误认作废弃。

容量规则默认 ticket，动作需 owner 和 consumer 证据。

复制冲突

hot standby 查询可能与 replay 冲突。观察：

• pg_stat_database_conflicts；
• replica activity；
• query cancellation log；
• feedback/delay 设置；
• retained xmin/WAL；
• user read path。

降低冲突的设置可能增加 bloat 或 freshness lag，不能只优化一张图。

25.2.3 vacuum、冻结、膨胀与对象增长

vacuum 有四个主要目的

常规 vacuum 不是“清空表”，而是：

1. 回收 dead row version，使空间可在表内复用；
2. 更新 visibility map，支持 index-only scan 等；
3. 防止 transaction ID wraparound；
4. 维护统计/冻结等运行状态。

ANALYZE 更新 planner statistics；它与 vacuum 可以一起运行，但目的不同。

autovacuum 依赖统计

track_counts=on 不只是“多收指标”。autovacuum 使用累计活动决定何时处理表。 关闭它会影响维护机制。

每表触发近似由：

vacuum threshold
  base threshold + scale factor * relation tuples

analyze threshold
  base threshold + scale factor * relation tuples

决定，并受 insert threshold、per-table storage parameter、cost limit、worker 数、 全局设置等影响。

不能只看“autovacuum process 存在”。要看：

• table change pressure；
• last vacuum/autovacuum；
• dead tuples；
• analyze freshness；
• blockers；
• progress；
• freeze age；
• runtime/duration。

表级统计是 estimate + counter

SELECT
  schemaname,
  relname,
  n_live_tup,
  n_dead_tup,
  n_mod_since_analyze,
  n_ins_since_vacuum,
  last_vacuum,
  last_autovacuum,
  last_analyze,
  last_autoanalyze,
  vacuum_count,
  autovacuum_count,
  analyze_count,
  autoanalyze_count
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC NULLS LAST
LIMIT 50;

n_live_tup、n_dead_tup 是估算；count 是自 reset 累计。它们适合找候选，不 适合直接计算“精确 bloat 百分比”。

dead tuple 不等于 bloat

dead tuple
  an old row version no longer visible to current snapshots

reusable free space
  vacuum processed space available for future tuples

table bloat
  allocated pages exceed what current data/layout needs

filesystem size
  file blocks currently allocated

vacuum 后 n_dead_tup 可能下降，但文件通常不缩小，因为普通 vacuum 将空间 留给表内复用。需要归还操作系统的操作通常更重，涉及 rewrite/lock/extra disk； 不能因为文件没缩就说 vacuum 失败。

长事务如何阻止回收

MVCC 需要保留旧版本给仍可能看见它的 snapshot。长 transaction、prepared transaction、replication slot/feedback 等可能拉住 xmin：

updates/deletes create dead versions
  -> vacuum evaluates global visibility horizon
      -> old xmin still needs them
          -> cannot remove
              -> dead tuples/object size grow

观察：

SELECT
  pid,
  datname,
  usename,
  application_name,
  state,
  backend_xid,
  backend_xmin,
  clock_timestamp() - xact_start AS xact_age
FROM pg_stat_activity
WHERE xact_start IS NOT NULL
ORDER BY xact_start;

还要查：

• prepared transactions；
• replication slots；
• replica feedback；
• vacuum progress；
• table-level age。

“找到最老 PID 就 terminate”不是安全策略。

freeze age 是剩余空间，不是普通 latency

transaction ID 是有限循环空间。旧 tuple 必须被 freeze，避免 wraparound 后 可见性灾难。

数据库级：

SELECT
  datname,
  age(datfrozenxid) AS xid_age,
  mxid_age(datminmxid) AS multixact_age
FROM pg_database
ORDER BY xid_age DESC;

表级：

SELECT
  n.nspname,
  c.relname,
  age(c.relfrozenxid) AS xid_age,
  mxid_age(c.relminmxid) AS multixact_age,
  pg_total_relation_size(c.oid) AS total_bytes
FROM pg_class AS c
JOIN pg_namespace AS n ON n.oid = c.relnamespace
WHERE c.relkind IN ('r', 'm')
  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
ORDER BY xid_age DESC
LIMIT 50;

不要把阈值写成与配置无关的魔法数字。应比较：

current age
autovacuum_freeze_max_age
table override
consumption rate
vacuum throughput
blocker
remaining time with uncertainty

本章候选 PG36FreezeAgeHorizon 使用固定数字只是 isolated lab 的测试输入， 明确标为 proposed；生产规则应由当前配置和容量政策生成。

anti-wraparound autovacuum 的特殊性

为防 wraparound 启动的 autovacuum 通常不会像普通 autovacuum 那样轻易被冲突 动作自动打断。不要把它当“可以随时 kill 的后台噪声”。

如果已经进入紧急区：

• 停止增加风险的长事务；
• 找出不能推进的表与 blocker；
• 评估 I/O/空间/锁；
• 按 runbook 控制维护；
• 不并行执行未经评估的 rewrite；
• 保留 evidence。

最优策略是在容量 horizon 阶段用 ticket 解决，而不是等 emergency page。

progress view 是当前进度，不是历史

vacuum：

SELECT
  pid,
  datid,
  relid,
  phase,
  heap_blks_total,
  heap_blks_scanned,
  heap_blks_vacuumed,
  index_vacuum_count,
  num_dead_item_ids,
  max_dead_item_ids
FROM pg_stat_progress_vacuum;

PostgreSQL 还为：

• ANALYZE；
• CREATE INDEX / REINDEX；
• CLUSTER / VACUUM FULL；
• COPY；
• base backup

提供相应 progress view，具体列按版本文档。

没有行只表示当前没有该动作被报告，不表示：

• 从未运行；
• 上次成功；
• 下一次会成功；
• 没有被瞬间启动后失败。

历史需要日志、事件和累计 count。

progress 百分比可能不单调

不同 phase 使用不同总量；并行、索引清理和 dead item cycle 也会改变解释。 不要把：

heap_blks_scanned / heap_blks_total

当成整个 vacuum 的精确完成百分比。应同时显示 phase 和相关量。

analyze freshness

planner statistics 变旧会导致估算偏差。候选信号：

n_mod_since_analyze
last_analyze / last_autoanalyze
table size
query plan estimate vs actual
statistics target
column distribution

n_mod_since_analyze 是估算/累计线索，不是每行精确 change counter。对热点、 分区和高度偏斜列，需要 workload-aware 策略。

对象增长要拆分

SELECT
  n.nspname,
  c.relname,
  pg_relation_size(c.oid) AS heap_bytes,
  pg_indexes_size(c.oid) AS index_bytes,
  pg_total_relation_size(c.oid) AS total_bytes
FROM pg_class AS c
JOIN pg_namespace AS n ON n.oid = c.relnamespace
WHERE c.relkind IN ('r', 'm')
  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
ORDER BY total_bytes DESC
LIMIT 50;

增长可能来自：

• 正常业务数据；
• index 数量；
• TOAST；
• dead/reusable space；
• fillfactor；
• 分区保留；
• 临时/中间对象；
• rewrite；
• 失控 batch。

不要只按总大小 page。需要：

growth rate
retention expectation
free-space horizon
maintenance/rewrite headroom
business volume
owner plan

容量是预测和计划问题，默认 ticket。

partition 会改变聚合方式

父表和各分区的：

• size；
• table stats；
• autovacuum；
• analyze；
• index；
• freeze age

需要分别观察，再按业务分区策略聚合。只看父表可能近乎空；只列每个分区又会 产生巨大 cardinality。

推荐：

metric
  aggregate by parent / age band / size band

dashboard
  top-N and drill-down

SQL
  on-demand exact partition inventory

不要把每个临时分区名永久做成高基数 alert label。

bloat estimate 的边界

extension 或 SQL 估算 bloat 常依赖：

• row width；
• null bitmap；
• alignment；
• fillfactor；
• statistics；
• page sample；
• index type。

它是排序候选，不是字节级财务账。要做重操作前：

1. 复核对象大小与增长趋势；
2. 判断空间能否复用；
3. 找出生成机制和 blocker；
4. 评估 rewrite/lock/replication/WAL/backup 影响；
5. 准备额外磁盘和回退/前滚；
6. 在维护窗口验证。

本章不会自动 VACUUM FULL 或 REINDEX。

把三类维护信号分开

它们的 severity、owner 和时间尺度不同。一个“表大”告警不能同时代表三者。

沙箱快照如何读

正式采集在 pg-test-1 观察到：

user tables             1
estimated dead tuples   0
max table freeze age    1,050

这不是“vacuum 永远健康”的证明：

• synthetic workload 很小；
• 只有一次瞬时快照；
• 没有长期增长率；
• 没有生产 transaction rate；
• 没有生产配置与 margin；
• estimate 可能变化。

可以得出的结论只有：

at captured_at,
the declared sandbox target reported this small current baseline.

PostgreSQL 信号最小关联表

本节验收

你应当能解释：

1. active 为什么仍可能在等待；
2. 同一 transaction 为什么可能读到缓存的累计统计；
3. track_wal_io_timing=off 为什么不能把时间解释为零；
4. pg_stat_io 为什么不等于物理磁盘 I/O；
5. failed_count>0 为什么不等于当前归档失败；
6. time lag NULL 与 WAL gap 0 为什么可以同时出现；
7. WAL gap 0 为什么不能证明用户新鲜度；
8. n_dead_tup 为什么不等于精确 bloat；
9. 普通 vacuum 为什么通常不缩小文件；
10. progress view 没有行为什么不证明历史成功；
11. query、lock、vacuum 和 freeze 信号分别对应哪种动作；
12. 任何取消、终止、reset、vacuum 或配置变更为什么不属于 L0 观察。

上一节：从问题选择可观测信号 · 返回本章目录 · 下一节：SQL 可观测基线 · 查看全书目录 · 查看索引中心

25.3 SQL 可观测基线

数据库“忙”只是结果，SQL workload 才是来源之一。

要回答：

哪类语句消耗了时间？
调用量还是单次成本改变？
时间花在执行、计划、I/O、JIT、WAL 还是临时块？
慢是一直慢，还是 tail 中少量异常？
统计从什么时候开始？
query identity 是否稳定？
日志和计划采集付出了多少额外成本？
证据是否泄露业务值？

需要组合三个接口：

pg_stat_statements
  聚合 workload population

bounded logging
  离散慢语句、错误、锁等待、临时文件

auto_explain
  对满足政策的一部分执行自动记录计划

三者都有盲区，也都有成本。最危险的做法是为了“可观测”无界记录所有 SQL 和 参数，结果既拖慢系统，又制造一份高密度敏感数据库。

25.3.1 pg_stat_statements 的统计口径与重置

它不是默认自动完整可用

pg_stat_statements 需要：

1. 出现在 shared_preload_libraries；
2. PostgreSQL 重启后模块被加载；
3. 每个需要查询视图的 database 安装 extension；
4. query identifier 可用；
5. 查询角色有足够权限；
6. 容量、track policy 和 reset 被声明。

检查：

SELECT name, setting, source
FROM pg_settings
WHERE name IN (
  'shared_preload_libraries',
  'compute_query_id',
  'pg_stat_statements.max',
  'pg_stat_statements.track',
  'pg_stat_statements.track_utility',
  'pg_stat_statements.track_planning',
  'pg_stat_statements.save'
)
ORDER BY name;

extension 可能不在 public：

SELECT
  e.extname,
  e.extversion,
  n.nspname AS extension_schema
FROM pg_extension AS e
JOIN pg_namespace AS n ON n.oid = e.extnamespace
WHERE e.extname = 'pg_stat_statements';

Pigsty 沙箱中的结果：

shared_preload_libraries        pg_stat_statements, auto_explain
compute_query_id                auto
pg_stat_statements.max          10000
pg_stat_statements.track        all
pg_stat_statements.track_utility off
pg_stat_statements.track_planning off
pg_stat_statements.save         on
extension version              1.12
extension schema               monitor

所以查询使用：

monitor.pg_stat_statements
monitor.pg_stat_statements_info

不要硬编码成 public.pg_stat_statements。

聚合键不是 query text

一行主要按以下身份聚合：

dbid
userid
queryid
toplevel

这意味着：

• 同一 queryid 在不同 database 分开；
• 不同执行角色分开；
• top-level 与 nested statement 分开；
• query text 是一个代表性 normalized text，不是主键；
• 同一可见文本仍可能因语义环境不同获得不同 queryid；
• hash collision 在理论和实践上都可能发生。

因此关联时保留：

cluster / instance
dbid
userid or role class
queryid
toplevel
stats_since

只保存 queryid 而丢掉 database/user/toplevel，会把不同 workload 合并。

normalization 不是脱敏承诺

常量通常会被替换：

SELECT * FROM orders WHERE order_id = 123;

-- representative normalized form
SELECT * FROM orders WHERE order_id = $1;

但不能据此认为 query 列可以公开：

• object 名可能包含客户或项目身份；
• comment 可能含敏感上下文；
• dynamic SQL 结构可能暴露值；
• utility statement 的行为不同；
• query text 与日志/错误组合可能重新识别业务；
• 权限边界本身说明它被视为敏感。

本章 evidence 明确：

query text exported   false
bind values exported  false
client address        false

queryid 是关联键，不是密码学身份

queryid 是内部 hash：

• 算法可能随 major version 改变；
• collision 可能发生；
• object identity 与 search_path 会影响语义；
• 相同显示文本可能代表不同解析对象；
• failover/upgrade 前后要重新建立 baseline。

不要用 queryid：

• 做访问控制；
• 证明 SQL 完全相同；
• 做永久跨版本业务 ID；
• 取代 plan fingerprint；
• 取代 application operation class。

它适合：

• workload 聚合；
• before/after 比较；
• dashboard 下钻；
• 与受限日志/plan 关联；
• top-N 诊断。

从总时间拆成频率与单次成本

$$ \text{total execution time}

\text{calls} \times \text{mean execution time} $$

top total time 可能来自：

very frequent cheap query
rare extremely slow query
both

基本查询不要一开始读 text：

SELECT
  dbid,
  userid,
  queryid,
  toplevel,
  calls,
  round(total_exec_time::numeric, 2) AS total_exec_ms,
  round(mean_exec_time::numeric, 3) AS mean_exec_ms,
  round(min_exec_time::numeric, 3) AS min_exec_ms,
  round(max_exec_time::numeric, 3) AS max_exec_ms,
  rows,
  shared_blks_hit,
  shared_blks_read,
  temp_blks_written,
  wal_bytes,
  stats_since,
  minmax_stats_since
FROM monitor.pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 50;

注意：

• min/max 易受单次异常影响；
• mean 掩盖分布；
• row count 的语义随 statement 类型变化；
• block 是 PostgreSQL block，不是任意存储 byte；
• I/O timing 依赖开关；
• WAL byte 不等于 commit durability；
• top-N 会漏掉排名外 workload。

用 delta，而不是跨 reset 比裸值

两个采样点：

t0: calls_0, total_exec_0, stats_since_0
t1: calls_1, total_exec_1, stats_since_1

只有 identity 与统计窗口连续时才计算：

$$ \text{window mean}

\frac{\Delta total_exec_time} {\Delta calls} $$

如果：

• row 消失；
• stats_since 改变；
• postmaster restart；
• extension reset；
• entry deallocated 后重新创建；
• failover 到另一成员；

就不能直接减。

pg_stat_statements_info 是解释入口

SELECT *
FROM monitor.pg_stat_statements_info;

核心：

dealloc
stats_reset

dealloc 增长表示 statement entry 因容量压力被丢弃。此时 top workload 可能 被 churn 影响；应评估：

• pg_stat_statements.max；
• query shape 数量；
• dynamic SQL；
• reset；
• 内存成本；
• 是否需要更稳定的 application query pattern。

沙箱正式快照：

dealloc              0
stats_reset          2026-07-29T18:57:02Z
statement rows       194
calls                超过 100,000

这是一次窗口基线，不是永久容量结论。

每行还有自己的时间边界

PostgreSQL 18 的 statement 行包含：

stats_since
minmax_stats_since

如果只 reset 某条或只 reset min/max，不同 entry 的窗口可能不同。一个 dashboard 不能只在标题写全局“过去 24 小时”，却忽略每行实际开始时间。

reset 是破坏性观察动作

函数可以全局或选择性 reset；当前版本还支持只 reset min/max。它很有用，但 会销毁比较基线。

原则：

incident capture
  never reset to make the graph easier

planned benchmark
  may reset in an isolated target with explicit evidence

production baseline
  prefer snapshots/deltas and recording rules

本章 L0 采集明确禁止：

pg_stat_statements_reset
pg_stat_reset*

如果必须 reset：

• 记录 request/approval；
• exact target；
• old reset time；
• snapshot/hash；
• reason；
• expected observation gap；
• downstream dashboard impact；
• new baseline start。

planning 与 execution 并非一一对应

pg_stat_statements.track_planning=on 可以收集 plan count/time，但：

• 默认通常为 off；
• 对高并发相同 query，plan 统计更新会有明显开销；
• prepared/cached plan 改变 plan/execute 次数关系；
• 执行失败与计划失败的记录条件不同；
• utility 和 nested track policy 影响 population。

沙箱 track_planning=off，所以：

total_plan_time = 0

表示未收集，而不是规划不耗时。不要为了填满 dashboard 直接在生产开启；先做 负载测试和决策评审。

track=all 的语义

top 只跟踪 top-level；all 还跟踪 nested statement。沙箱设置 all，再用 toplevel 区分。否则 stored procedure 或 function 内 SQL 可能看不见，或被 误与 top-level 混合。

top-N 查询要保护系统

观察查询也消耗：

• shared memory lock；
• sort；
• format/round；
• dashboard 并发；
• network；
• 结果存储。

生产查询建议：

SET LOCAL statement_timeout = '5s';
SET LOCAL lock_timeout = '500ms';

-- 只读、限制列、限制行、先 aggregate identity

不要每 5 秒在每个 database：

SELECT * FROM pg_stat_statements ORDER BY total_exec_time DESC;

尤其不要自动导出完整 query text。

建立 workload baseline

基线至少分：

calls rate
total/mean/max execution
rows per call
shared hit/read/write
temp blocks
WAL bytes
JIT time/count
planning if explicitly enabled
stats reset / entry age

按：

service operation
database
role class
queryid
release/change window

关联。不要仅按 instance；failover 后 workload 会移动。

25.3.2 慢语句、锁等待、临时文件与错误日志

慢日志是离散样本

核心设置：

SELECT name, setting, unit, source
FROM pg_settings
WHERE name IN (
  'log_min_duration_statement',
  'log_min_duration_sample',
  'log_statement_sample_rate',
  'log_duration',
  'log_statement',
  'log_lock_waits',
  'deadlock_timeout',
  'log_temp_files',
  'log_min_error_statement',
  'log_parameter_max_length',
  'log_parameter_max_length_on_error'
)
ORDER BY name;

log_min_duration_statement

记录执行时间达到阈值的语句；0 表示记录全部，-1 关闭。

优点：

• 对超过阈值的 population 较完整；
• 可以看到离散 tail；
• 能与 queryid、错误和时间线关联。

代价：

• I/O 与格式化；
• log volume；
• SQL/参数泄露；
• 高频略慢语句形成洪水；
• 日志系统成为新瓶颈。

log_min_duration_sample

达到 sample threshold 后，再按 log_statement_sample_rate 采样。它适合控制 高流量环境的日志量，但“未出现”不能解释为“未发生”。

如果：

log_min_duration_sample = -1
log_statement_sample_rate = 1

采样路径仍是关闭的。不要只看 rate。

duration 的边界

语句 duration 与用户 end-to-end latency 不同。用户时间可能包括：

network
application queue
pool wait
server execution
result transfer
application processing
retry
commit reconciliation

PostgreSQL 慢日志只覆盖 server 侧语句范围。

lock wait 日志

log_lock_waits=on 在等待超过 deadlock_timeout 时记录。沙箱：

log_lock_waits   on
deadlock_timeout 50ms

这意味着：

• 超过约 50 ms 的 lock wait 有机会被记录；
• 更短等待可能很多但没有日志；
• deadlock detection cadence 与日志量相关；
• 不能为了更多日志随意降低 timeout；
• 日志是离散事件，当前 lock view 是即时状态。

调查组合：

user latency window
pg_stat_activity current wait
pg_locks / pg_blocking_pids
lock wait logs
deadlock counter
application transaction boundary

temporary file

log_temp_files 在临时文件删除时记录超过阈值的文件。沙箱为：

1024 kB

这类日志说明：

• 某操作产生了 temp file；
• 大小达到记录政策；
• 日志时刻可能是删除时刻，不是创建/峰值时刻。

关联：

• pg_stat_database.temp_files/temp_bytes；
• pg_stat_statements.temp_blks_read/written；
• queryid；
• plan；
• sort/hash/window；
• workload concurrency；
• work_mem policy。

不要看到 temp 就全局提高 work_mem。它按 operation/node/worker 使用，高并发 会把一个小改动放大成内存风险。

error log 与用户 outcome

PostgreSQL error 包含 SQLSTATE、severity、detail、context 等；应用可能：

• retry 后成功；
• 返回失败；
• 超时但 commit；
• 屏蔽错误；
• 将一个 DB error 映射成不同业务 outcome。

所以错误日志要与应用 outcome 关联，而不是用 log line 数直接做 availability 分子。

稳定聚合维度：

cluster / instance / database
severity / SQLSTATE class
application / operation class
release

不适合作 label：

full message
detail
statement
parameter
customer/order/tenant

structured CSV/JSON 不会自动安全

沙箱使用：

logging_collector on
log_destination csvlog
log_directory /pg/log/postgres
log_filename postgresql-%a.log

CSV 方便 Vector 解析，但：

• statement 字段仍可能敏感；
• detail/context 可能含值；
• file permission/collector group 需要评审；
• 集中存储扩大读取面；
• retention 必须独立设置。

从 metric 到 log，而不是无界 log query

正确流程：

metric identifies:
  service, environment, operation, time window

event identifies:
  release/change boundary

log query:
  bounded window + stable fields + maximum rows

result:
  aggregate error classes, do not export bodies

本章诊断包规定：

log query limit  1000
body export      forbidden

需要正文时，应在受限界面临时查看并按事件政策处理，而不是复制进公共工单。

日志缺失也有语义

没有日志可能是：

• 事件未发生；
• threshold 未达到；
• sampling 丢失；
• collector/Vector 失败；
• rotation/retention；
• parse schema drift；
• 权限或查询错误；
• 日志写入阻塞；
• service 在另一 instance。

必须同时观察 log pipeline。

25.3.3 auto_explain 的采样、嵌套语句与开销

auto_explain 解决什么

pg_stat_statements 告诉你：

which queryid is costly

EXPLAIN/EXPLAIN ANALYZE 告诉你：

how one plan is structured and executed

auto_explain 在满足政策时自动把 plan 写入日志，适合捕捉难以手工复现的慢 执行。

它不是零成本“打开即可”。

最重要的开关

SELECT name, setting, unit, source
FROM pg_settings
WHERE name LIKE 'auto_explain.%'
ORDER BY name;

log_analyze 的隐藏成本

官方文档特别警告：启用 log_analyze 后，即使最终语句没有达到 log_min_duration 而不写日志，也可能需要为所有语句做 per-plan-node timing。

如果同时：

log_analyze=on
log_timing=on
sample_rate=1

开销可能非常高，尤其是大量短 node 的 workload。

log_timing=off 可以保留 rows 等实际统计并减少逐节点时钟调用，但仍需实测。

沙箱的真实设置

本章只读检查发现：

auto_explain.log_min_duration       1000 ms
auto_explain.log_analyze            on
auto_explain.log_timing             on
auto_explain.log_nested_statements  on
auto_explain.sample_rate            1
auto_explain.log_parameter_max_length -1

这不是推荐模板。它是一个需要单独 overhead 与泄露评审的真实基线：

• sample_rate=1 没有限制 eligible statement；
• log_analyze + log_timing 有全局计时成本；
• nested 可能显著放大日志量；
• parameter length -1 允许完整参数；
• 阈值 1 秒只限制最终写 plan，不一定消除 instrumentation cost。

本章不 reload、不改参数，只把风险记录下来。

BUFFERS 与 WAL 依赖 ANALYZE

自动计划中的实际 buffer/WAL 信息要求 analyze path。不能关闭 analyze 后仍假装 获得运行时资源。

设计取舍：

plan shape only
  lower runtime detail, lower cost

analyze without timing
  actual rows/buffer possibility, less per-node clock cost

analyze with timing
  richer node time, potentially high overhead

必须在代表性 workload 上量化。

nested statement

function、trigger、procedure 内可能包含真正慢的 SQL：

top-level CALL
  cheap wrapper
  nested SQL expensive

log_nested_statements=on 能看见，但会：

• 增加 volume；
• 重复上下文；
• 暴露更多 query/parameter；
• 让一个 top-level 请求产生多份 plan。

同时使用 pg_stat_statements.track=all 与 toplevel 关联。

采样测试应覆盖 tail

开启前在隔离 workload 回答：

baseline TPS / p50 / p99
CPU and system time
log bytes per second
collector lag
plan count
short statement overhead
long statement capture probability
nested amplification
parameter redaction
rollback path

不要只跑一条慢查询说“开销不大”。

不要在事故中临时全开

事故中：

log_min_duration=0
log_analyze=on
log_timing=on
sample_rate=1

可能：

• 进一步降低吞吐；
• 加剧 disk/log pipeline；
• 泄露参数；
• 改变被观察 workload；
• 制造新的故障。

更安全顺序：

1. 用现有 SLI、activity、wait、queryid 缩小范围；
2. 使用已有日志与 plan；
3. 评估只对 session/role/database 的受控方法；
4. 明确 timeout、采样、持续时间和 rollback；
5. 由变更政策批准；
6. 观察 overhead；
7. 到期自动撤销并验证。

auto_explain 不是 plan history 系统

计划只在满足政策时进入日志；sampling、rotation、retention、parse 都会造成 缺口。若要做 plan regression：

• 在测试/发布流程保存 EXPLAIN (FORMAT JSON)；
• 记录 schema/statistics/version/settings；
• 与 queryid/plan fingerprint 关联；
• 不要把生产日志当完整 plan catalog；
• 不要在没有参数与数据分布语义时做机械 diff。

25.3.4 日志不得泄漏密码、令牌和敏感参数

SQL observability 是高敏感数据面

可能出现：

password in connection/DDL statement
API token in INSERT/UPDATE
tenant/customer/order identity
email/phone/address
medical/payment attributes
session variable
RLS predicate context
error detail containing row values
dynamic SQL comment
connection URI

PostgreSQL 文档明确警告，statement logging 可能暴露敏感数据，甚至明文密码。

参数记录的两套限制

log_parameter_max_length
  非错误 statement 的参数记录限制

log_parameter_max_length_on_error
  错误发生时的参数记录限制

一般语义：

0    disable
-1   no length limit
N    truncate to N bytes

auto_explain.log_parameter_max_length 又是独立设置。

沙箱：

log_parameter_max_length           -1
log_parameter_max_length_on_error   0
auto_explain.log_parameter_max_length -1

这表示错误路径参数被禁用，但普通慢 statement/auto_explain 仍可能完整记录参数。 是否安全取决于 protocol、query 和应用，不能因为“一项为 0”宣布无泄露。

log_statement 的风险

log_statement=all 会记录每条 statement；DDL 中尤其可能出现：

CREATE ROLE app LOGIN PASSWORD '...';
ALTER ROLE app PASSWORD '...';

即使参数化 DML 避免 literal，DDL、utility、comment 和 dynamic SQL 仍可能带 秘密。生产不得把“排障方便”当默认充分理由。

文件模式：0600 不是唯一安全答案

PostgreSQL log_file_mode 控制 collector 创建文件的 mode。

0600
  PostgreSQL OS owner only

0640
  owner read/write + restricted collector group read

Pigsty 使用 Vector 收集日志时，受控 group read 可能是合理实现。安全要求是：

not world-readable
collector group explicitly declared
membership minimal
no interactive user by default
directory traversal restricted
rotation preserves mode
central storage ACL reviewed

沙箱为 0640。本章没有证明 collector group membership 已完成生产审批，因此 将其作为待评审事实，而不是自动判定安全或不安全。

传输到 VictoriaLogs 扩大了边界

原本只有 database host 上的日志，集中后可能被：

• Grafana data source；
• log query API；
• incident automation；
• backup/export；
• 多个 operator

访问。

必须重新定义：

ingestion TLS/auth
tenant isolation
query role
retention
deletion
export
redaction
audit
backup

“源文件权限正确”不能证明集中日志安全。

metric label、alert annotation、ticket 是二次泄露面

最常见事故不是直接开放 log file，而是自动化复制：

log body
  -> alert annotation
      -> chat webhook
          -> ticket
              -> email
                  -> postmortem

本章诊断包只导出：

• error class/count；
• queryid；
• database/role class；
• time window；
• release/change id；
• source link without credentials。

不导出：

• statement；
• bind value；
• log body；
• client address；
• tenant/order/customer。

redaction 要在尽量靠近 source 的位置

优先级：

1. 应用不把 secret 放进 SQL/comment；
2. 参数化查询；
3. PostgreSQL logging policy 限制；
4. collector parse/redact；
5. storage ACL/retention；
6. alert/evidence allowlist。

最后一步 regex 不是万能防线：

• 数据格式会变化；
• 编码/截断会绕过；
• 新字段未被匹配；
• secret 可能已进入上游缓存/备份。

query text 的受控交互查看

真正排障有时需要 SQL text。正确做法不是绝对禁止人看，而是区分：

machine evidence
  no query text

interactive diagnosis
  time-bounded pg_read_all_stats or narrower role
  approved operator
  restricted UI/session
  no casual copy
  audit and expiry

public/reference summary
  queryid and aggregates only

这既保留诊断能力，也控制扩散。

prepared statement 不自动消除泄露

参数化可以让 statement text 不含 literal，但：

• bind parameter logging 仍可能记录值；
• 错误 detail/context 可能包含；
• 应用 comment/baggage 可能包含；
• object/table/schema 名仍可能敏感；
• auto_explain parameter logging 是独立开关。

所以要检查完整链路，不只看应用 ORM。

慢日志与审计日志不是一回事

慢日志回答 performance sample；审计回答谁在何时对什么对象做了什么。两者：

• 目的不同；
• 保留不同；
• 访问不同；
• 完整性要求不同；
• 敏感性不同。

不要让 log_statement=all 同时冒充性能、审计、合规和安全检测。需要审计时， 使用明确的审计政策、对象范围和审阅流程。

安全基线查询

SELECT name, setting, source
FROM pg_settings
WHERE name IN (
  'logging_collector',
  'log_destination',
  'log_directory',
  'log_filename',
  'log_file_mode',
  'log_statement',
  'log_min_duration_statement',
  'log_min_duration_sample',
  'log_statement_sample_rate',
  'log_parameter_max_length',
  'log_parameter_max_length_on_error'
)
OR name LIKE 'auto_explain.%'
ORDER BY name;

这只是配置事实，还要复核：

• actual file mode/owner/group；
• directory mode；
• Vector identity/config；
• VictoriaLogs access/retention；
• sample log 是否被正确 parse/redact；
• alert/template 是否复制 body；
• backup 是否包含日志。

本章 L0 只记录配置，不读取日志正文。

SQL 可观测基线清单

extension
  preload / version / schema / query id

population
  track / utility / nested / max

time
  global reset / per-row stats_since / minmax_stats_since

cost
  planning / timing / auto_explain / logging volume

security
  query visibility / parameters / file group / central log ACL

diagnosis
  calls / exec / rows / blocks / temp / WAL

correlation
  service / operation / release / database / role / queryid

boundary
  no query text in automatic evidence

本节验收

你应当能够解释：

1. 为什么 extension schema 不能假设是 public；
2. 一行 pg_stat_statements 的四个核心聚合维度；
3. normalization 为什么不是脱敏保证；
4. queryid 为什么不能做永久或安全身份；
5. calls、total、mean、max 各说明什么；
6. dealloc、global reset、stats_since、minmax_stats_since 的差异；
7. track_planning=off 时 plan time 为零意味着什么；
8. 慢语句、采样慢语句、lock wait 和 temp file 日志各何时产生；
9. auto_explain.log_analyze + log_timing 为什么可能给所有语句带来成本；
10. nested statement 为什么同时增加诊断价值与泄露/volume；
11. 0640 如何在受控 collector group 下成立；
12. 为什么自动 evidence 只保留 queryid 与聚合，而交互查看另行授权。

上一节：PostgreSQL 核心运行信号 · 返回本章目录 · 下一节：把观察契约变成告警 · 查看全书目录 · 查看索引中心

25.4 把观察契约变成告警

规则语法正确，只证明 parser 接受了它。

一条生产告警还必须同时通过：

semantic
  expression 真正测量合同定义的事件吗？

temporal
  window / scrape / eval delay / for / recovery 正确吗？

governance
  page、ticket 还是 diagnostic？谁接受了这个政策？

actionability
  owner 能执行首个安全动作吗？

routing
  grouping / inhibition / receiver 会制造风暴或静默吗？

exercise
  正常、异常、缺失、错误和恢复都被测试了吗？

本章生成的文件：

• 记录规则
• 告警规则
• 合成时序测试
• 空 receiver 路由
• 路由与抑制用例

它们是教学候选，不是在线配置。

25.4.1 SLO 燃烧率与用户影响

从 error ratio 到 burn rate

若 SLO target 为：

允许的 bad ratio：

某窗口实际 bad ratio 为 $E$，燃烧率：

例如：

actual bad ratio  1.44%
budget ratio      0.1%
burn rate         14.4x

若持续 28 天，会花掉 14.4 倍预算；若只持续 1 小时，约花掉：