--- name: benchmark-checklist description: "在你报告或依据一次性能测量行动之前,先核它(限制因素、调优、上限、错误、可重复性、相关性,以及工作到底发生了没有)。跑基准,或报告你测到的加速或回退时使用。" disable-model-invocation: true --- # 基准核对清单 你产出一个性能数字时用这个:一个 PR 的前后对比、一条回退声称、一套 hillclimb harness,或一次库或配置的选择。每个问题都用一次运行的证据来回答,不要靠对代码的猜测。 用户要的是一个粗略估计时,跑一次就够。仍然检查问题 4 和 7,并说明这是一次运行。其余的跳过,除非这次运行看起来不对。在选项之间做选择,永远不是粗略估计。 ## 跑任何东西之前 - 把你预期要做的声称写下来,用你会交出去的那种话(「在 6 万行的数据集上,导出的 p50 快了 30%」)。这些问题检验的就是这句话。 - 读测量脚本。记下它计时什么、计数什么、忽略什么。 - 用 `uptime` 看负载均值,用 `nproc` 看核数。机器忙的话,查清在跑什么。停不掉的话,把两侧交错开,让两边看见同样的噪声,并在报告里说明。 ## 问题 1. **为什么不是两倍?** 点名限制因素。在一次你不拿来报告的运行里做 profile,因为 profiler 和 tracer 会把工作拖慢。用每个进程的 CPU(`top`、`pidstat`)、运行时 profiler(`node --cpu-prof`、`py-spy`、`perf`)、I/O 等待,以及系统调用计数(Linux 上的 `strace -c`),然后把热点映射到源码。负载发生器也要看:它先饱和的话,你量到的是负载发生器。一次改动没有挪动数字时,限制因素解释为什么,所以先找到它,再称这次改动没用。 2. **调过了吗?** 每一侧都按生产运行它的方式来跑:发布构建、生产的旗标和环境、批处理和事务设置、连接池、缓存的冷热和生产里看到的一样,以及相同的版本和数据。一侧跑在默认值上时,你比较的是配置,不是实现。限制因素是一项设置时(一行一个 commit、调试构建、缺索引),那一侧就没调过。先调它,再测一次,然后再选赢家。调不了的话,不要从这次运行里选赢家。用户在选要采用什么时,把声称收窄成「代码以今天这样交付」补不上这一点,因为他们采用的是这个选项,不是今天的设置。 3. **有没有撞破上限?** 做算术。用每秒字节数对比磁盘和网络带宽,用每秒操作数乘每次操作的成本对比你的核,用省下的时间对比改动的那一块本身花的时间。去掉一块占运行 10% 的部分,最多能让运行快大约 11%。结果越过了上限,量到的就不是这项工作,例如缓存、空操作,或一个 bug。 4. **出错了吗?** 数失败和非成功响应,并检查输出是正确的,不只是在场。拒绝往往很快,超时和重试很慢。脚本不数错误的话,把计数加上。 5. **能复现吗?** 每一侧至少跑 5 次,交替进行(A、B、A、B,以此类推),这样预热、懒初始化、缓存和漂移不偏向任何一侧。报告中位数和范围。差距小于运行之间的波动时,没有可测差异。结论很接近时,用秩和检验,或 harness 自己的统计。 6. **要紧吗?** 任何微结果旁边,测量用户真正等待的端到端路径,用真实的数据规模和并发,并把微结果报告成占整体的份额。一个占请求 1% 的辅助,最多能让请求快 1%,无论这个辅助自己变得多快。 7. **它到底发生了吗?** 确认工作跑在计时区间里面:请求到达了服务器,行写进去了,字节读到了,代码用上了结果。懒代码(没人迭代的生成器、没人 await 的 promise、JIT 可以丢掉的结果)和超时,会给从未发生的工作产出数字。 ## 报告 - 先给结论:更快、更慢、没有可测差异,或无结论。 - 给出带单位的数字、运行次数、范围,以及限制因素。例如:「p50 41 ms → 33 ms,每侧 7 次运行的中位数,之后的范围是 32 到 35 ms,受单核上的 JSON 解析所限。」 - 你声称有差异,却点不出限制因素时,一侧没调过时,或者问题 4 和 7 查不了时,把结论叫成无结论。点名这个缺口。 - PR 正文只留一个主要数字。把运行、范围和限制因素的证据放进链接的产物或笔记文件。 ## 其他性能材料 - playbook 据此做计划之前,先核 **性能** playbook 的基线,以及之后的每一个数字。 - harness 冻结之前,先核 **hillclimb** playbook 的 harness。冻结后的 harness 会打印错误数和工作数,这样每一次留下或回退都免费检查了问题 4 和 7。