# 建立计划证据基线

LLMS 索引： [llms.txt](/llms.txt)

---

手工 EXPLAIN 回答“这个参数现在怎样”，生产基线还要回答“哪些 query shape 消耗最多、何时变化、影响谁”。`pg_stat_statements`、日志/auto_explain 与 Pigsty 时间序列分别提供聚合、样本与上下文。

## 7.6.1 `pg_stat_statements` 的归一化视角 {#item-7-6-1}

`pg_stat_statements` 按 database、user、toplevel 与 normalized query identity 聚合 calls、rows、planning/execution time、buffers、WAL、JIT/parallel 等累计量。literal 通常归一为 `$1`，所以适合找高总耗时、高均值/方差、高 I/O 或高调用频率的 query family。

使用时保留：

```text
dbid + userid + queryid + toplevel
stats_since / minmax_stats_since
calls / rows
total/min/max/mean/stddev exec time
shared/local/temp blocks + WAL
representative query（权限受控）
```

`queryid` 是 hash，不保证无碰撞，也不保证跨 major version、不同架构或重建对象后永久稳定；相同文本还可能因 search_path 解析到不同对象而分开。把它作为某实例/版本时间窗内的关联键，不作全球业务 ID。

`track_planning` 默认关闭且可能带来并发更新开销；`plans` 与 `calls` 也不必相等，因为 cached plan、规划成功但执行失败等路径不同。reset 会破坏累计基线，生产只由受控 owner 在记录旧窗口后执行，不能为了实验清空全局统计。

## 7.6.2 `auto_explain` 的阈值、采样与日志成本 {#item-7-6-2}

`auto_explain` 能在 query 超过 `log_min_duration` 时写计划，补上“事后再 EXPLAIN 已无法复现”的样本。但默认不做任何事；至少要设置阈值。上线前审查：

- threshold 与 `sample_rate` 是否覆盖目标尾部且可控日志量；
- `log_analyze` 是否需要 actual rows；
- `log_timing` 的逐节点时钟成本；
- buffers/WAL/triggers/nested statements 是否必要；
- `log_parameter_max_length` 是否会泄露 PII/secret；
- log format、保留、访问与脱敏；
- preload/load 权限和配置变更方式。

尤其 `log_analyze=on` 时，per-node instrumentation 对所有被考虑的 statement 生效，即使最终没达到日志阈值；`log_timing=off` 可降低成本但失去节点时间。不要直接在繁忙生产设 threshold 0、sample 1、完整参数。

先在 L1 用代表 workload 测量开销和日志体积，再小比例/较高阈值 canary，最后从实际 signal 调整。auto_explain 样本不是全量分布，仍需 pg_stat_statements/metrics 提供 denominator。

## 7.6.3 从 Pigsty 时间窗保存 SQL、参数、统计、计划与环境上下文 {#item-7-6-3}

Pigsty 的 PGSQL Query/Database/Activity、PGCAT Query、Session/Xacts、Persist 等入口把 query 统计与 cluster/instance/database 资源放在同一时间轴。排查时先固定：

```text
UTC start/end
cluster / instance / primary-replica role
database / user / application
queryid + representative query
calls/latency/rows/buffers/WAL
CPU/I/O/load/connection/wait/lock/replica lag
PostgreSQL/Pigsty/config/schema/statistics version
```

然后选具体参数在等价 L1 采集 machine-readable EXPLAIN。dashboard screenshot 只能证明画面，最好同时导出 query/metric value、过滤条件和 timezone。短查询可能落在 scrape interval 之间；瞬时 blocker 要回到 catalog/log。

参数可能含个人数据，query text 也可能暴露 literal。证据包使用最小权限、脱敏和访问控制，不能把 `pg_read_all_stats` 给业务角色，也不能把 Grafana datasource credential 导出。

一次完整计划证据应能回答：

```text
这是哪个 workload 的哪个时间窗？
聚合上影响多大？
选择了哪个代表参数，为什么？
当时统计、schema、settings 和数据分布是什么？
estimate/actual、buffers/wait 的根因假设是什么？
变更前后结果/SLO/写成本怎样？
怎样回退，何时复查？
```

这套证据将在第 8 章变成慢查询诊断模板；本章暂不把 dashboard panel 名或 metric label 当跨版本稳定接口。

---

[上一节：参数、缓存计划与计划漂移](../05/) · [返回本章目录](../) · [下一节：实战：解释订单查询的计划变化](../07/) ·
[查看全书目录](/toc/) · [查看索引中心](/indexes/)