--- name: benchmark-checklist description: "报告性能测量或依据它行动前,核验限制因素、调优、物理上限、错误、可复现性、实际相关性和工作是否真的执行。运行基准或报告亲自测得的加速与回退时使用。" disable-model-invocation: true --- # 基准测量检查清单 产生性能数字时使用,包括 PR 的前后比较、回退判断、持续优化测量驱动,以及库或配置选择。每个问题都用实际运行证据回答,不猜代码。 用户只要求快速大致估计时,运行一次就够。仍检查第 4、7 题,并说明只运行一次。除非该次结果异常,否则跳过其余问题。在选项之间作选择,永远不属于大致估计。 ## 运行任何东西之前 - 写下准备对外报告的结论,使用实际交付时的措辞,例如“在 6 万行数据集上,导出的 p50 快了 30%”。这些问题检验的就是这句话。 - 阅读测量脚本,记下它计时什么、计数什么、忽略什么。 - 用 `uptime` 查看平均负载,用 `nproc` 查看核心数。机器繁忙时,查明正在运行什么。不能停止时,让两侧交错运行,承受相同噪声,并在报告中说明。 ## 七个问题 1. **为什么不能再快一倍?** 指出限制因素。在一次不纳入报告的运行中剖析,因为剖析器与追踪器会拖慢工作。使用每进程 CPU(`top`、`pidstat`)、运行时剖析器(`node --cpu-prof`、`py-spy`、`perf`)、I/O 等待与系统调用计数(Linux 上的 `strace -c`),再把热点映射到源码。也观察负载生成器:它先饱和时,你测的是生成器。变更没有改变数字时,限制因素能解释原因;先找出它,再说变更无用。 2. **调优了吗?** 两侧都按生产实际运行:发布构建、生产标志和环境、批处理与事务设置、连接池、符合生产情况的冷暖缓存,以及相同版本和数据。一侧保留默认值时,你比较的是配置,不是实现。限制因素若是一个设置,例如每行一次提交、调试构建、缺少索引,就说明该侧未调优。选赢家前调优并重测。不能调优,就不能凭该次运行选赢家。用户正在选择采用什么时,把结论缩到“目前交付代码的表现”也不能解决问题,因为他们采用的是选项,不是今天的设置。 3. **违反上限了吗?** 做计算。比较每秒字节数与磁盘、网络带宽,每秒操作数乘以每次操作成本与核心数,以及节省时间与被改部分原本耗时。移除占整次运行 10% 的部分,最多让整体约快 11%。超过上限的结果测到了别的东西,例如缓存、空操作或缺陷。 4. **出错了吗?** 统计失败与非成功响应,检查输出正确,而不只是存在。拒绝通常很快,超时和重试很慢。脚本不统计错误,就添加计数。 5. **能复现吗?** 每侧至少运行 5 次,交替执行 A、B、A、B,避免预热、延迟初始化、缓存和漂移偏向一侧。报告中位数与范围。差距小于各次运行变化幅度时,没有可测差异。结果接近时,使用秩和检验或测量驱动自己的统计方法。 6. **有实际意义吗?** 每个微观结果旁边,都测量用户等待的端到端路径,使用真实数据规模和并发,并说明微观部分占整体多少。一个辅助函数只占请求的 1%,无论它变多快,都最多让请求耗时缩短 1%。 7. **工作真的发生了吗?** 确认工作发生在计时区间内:请求到达服务端、行被写入、字节被读取,代码使用了结果。惰性代码,例如无人遍历的生成器、无人等待的 Promise、JIT 可丢弃的结果,以及超时,都会为没有发生的工作生成数字。 ## 报告 - 先给结论:更快、更慢、没有可测差异,或无结论。 - 数字带单位、运行次数、范围和限制因素。例如“p50 从 41 ms 到 33 ms,每侧 7 次运行的中位数;修改后范围 32 至 35 ms,受限于单核 JSON 解析”。 - 声称有差异却不能指出限制因素、一侧未调优,或无法检查第 4、7 题时,把结论标为无结论,并指出缺口。 - 按 **Opening a PR** 手册,让 PR 正文只保留一个主要数字。各次运行、范围和限制因素证据放进链接产物或笔记文件。 ## 其他性能材料 - **Perf issue** 手册依据基线规划前,先核验基线,并核验之后每个数字。 - **Hillclimb** 手册冻结测量驱动前,先核验驱动。冻结驱动随后会输出错误与完成工作量,让每次保留或回滚都顺便检查第 4、7 题。