benchmark-checklist

来源

这是中文译文，方便对照阅读。本站不发行中文版插件。

对照英文：本站英文页

英文原文出处：cursor/plugins 仓库 pstack/skills/benchmark-checklist/SKILL.md（提交 23e4138）

基准测试检查清单

产出一个性能数字时用这份清单：一次 PR 的前后对比、一次退步主张、一套爬坡优化（hillclimb）的测量工具，或在两个库或两套配置之间做选择。解释这个数字 说明为什么要这样做。下面每个问题都要用一次运行里的证据回答，不要靠读代码来猜。

用户只要一个大概数时，跑一次就够。第 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、即时编译器可以丢掉的结果）和超时，都会给根本没做的工作产出数字。

报告

• 先给结论，只能是这四种之一：更快、更慢、没有可测出的差别、无法下结论。
• 数字要带单位、运行次数、范围和限制因素。例如：「p50 从 41 ms 到 33 ms，每一方 7 次的中位数，改后范围 32 到 35 ms，限制在单核上的 JSON 解析。」
• 你主张有差别，却说不出限制因素，或有一方没调优，或第 4 问、第 7 问没法查，结论必须是无法下结论。把缺口写出来。
• PR 正文只放一个主要数字，按 Opening a PR playbook。运行次数、范围和限制因素的证据放到链接的产物或一份笔记里。

和其他性能材料怎么配合

• Perf issue playbook 负责找到并修好变慢的地方，它的策略族用来产生修复。本 skill 在那份 playbook 据基线做计划之前，先核对基线，之后的每个数字也一样。
• Hillclimb playbook 对着一个指标循环。本 skill 在测量工具冻结之前先核对它。冻结之后，测量工具打印出错次数和完成的工作量，这样每次保留或回退都顺带检查了第 4 问和第 7 问。