benchmark-checklist

ベンチマークのチェックリスト

パフォーマンスの数値を提示する場合は、PR の変更前後の比較、リグレッションの主張、ヒルクライム用ハーネス、ライブラリや設定の選択など、これを使ってください。それぞれの質問には、コードについての推測ではなく、実行結果の証拠に基づいて回答してください。

ユーザーから大まかな目安を求められた場合は、1 回の実行で十分です。それでも質問 4 と 7 は確認し、1 回の実行であることを明記してください。その実行結果に問題がなさそうであれば、ほかの質問は省略してください。選択肢から選ぶ場合は、大まかな目安で済ませることはできません。

実行する前に

• 提示する予定の主張を、実際に公開する文言で書き留めてください（「60k 行のデータセットで、エクスポートは p50 が 30％高速です」など）。以下の質問は、その文が妥当かを確認するものです。
• 計測スクリプトを読んでください。何を計測し、何を数え、何を無視するかを把握してください。
• uptime でロードアベレージを、nproc でコア数を確認してください。マシンに高い負荷がかかっている場合は、何が実行されているかを確認してください。停止できない場合は、両方に同じノイズがかかるよう交互に実行し、そのことをレポートに記載してください。

質問

1. なぜ 2 倍にならないのでしょうか？ ボトルネックを特定してください。プロファイラーやトレーサーは処理を遅くするため、レポートには含めない実行でプロファイルを取得してください。プロセスごとの CPU 使用量（top、pidstat）、ランタイムプロファイラー（node --cpu-prof、py-spy、perf）、I/O 待ち、システムコール数（Linux では strace -c）を調べ、ホットスポットをソースコードに対応付けてください。負荷生成側も確認してください。先に飽和している場合、計測したのは負荷生成側です。変更しても数値が変わらなかった場合、その理由はボトルネックで説明できます。変更に効果がないと判断する前に、ボトルネックを特定してください。
2. 適切にチューニングされていますか？ それぞれの側を、本番環境と同じ条件で実行してください。リリースビルド、本番用のフラグと環境変数、バッチ処理とトランザクションの設定、接続プール、キャッシュのウォーム／コールド状態、本番環境と同じバージョンとデータを使ってください。一方がデフォルト設定で動いている場合、比較しているのは実装ではなく設定です。ボトルネックの原因が設定（行ごとのコミット、デバッグビルド、インデックスの欠落など）であれば、その側はチューニング不足です。勝者を選ぶ前にチューニングして再計測してください。チューニングできない場合は、その実行結果から勝者を選ばないでください。ユーザーが導入するものを選んでいる場合、主張を現在のコードの出荷時点に限定しても解決にはなりません。ユーザーが導入するのは選択肢そのものであり、現在の設定ではないからです。
3. 上限を超えていませんか？ 計算してください。バイト毎秒をディスクとネットワークの帯域幅と比較し、1 秒あたりの操作数に操作ごとのコストを掛けた値をコア数と比較し、節約できた時間を変更対象の処理時間と比較してください。実行時間の 10％を占める処理を取り除いても、実行全体の高速化は最大で約 11％です。上限を超える結果が出た場合は、キャッシュ、何もしない処理、バグなど、対象の処理以外を計測しています。
4. エラーは発生しましたか？ 失敗と成功以外のレスポンスを数え、出力が存在するだけでなく正しいことも確認してください。拒否は速く終わることが多く、タイムアウトやリトライは遅くなります。スクリプトがエラーを数えていない場合は、カウントを追加してください。
5. 再現できますか？ それぞれの側を少なくとも 5 回、A、B、A、B のように交互に実行してください。ウォームアップ、遅延初期化、キャッシュ、経時変化がどちらか一方に有利にならないようにします。中央値と範囲を報告してください。実行ごとのばらつきより小さい差は、測定可能な差ではありません。差が僅差の場合は、順位和検定またはハーネス独自の統計を使ってください。
6. その差は重要ですか？ マイクロベンチマークの結果には、ユーザーが待つエンドツーエンドの処理も、現実的なデータサイズと並行実行数で計測して併記し、全体に占めるマイクロベンチマークの割合を報告してください。あるヘルパーがリクエスト全体の 1％を占めるなら、そのヘルパーがどれほど高速になっても、リクエスト全体の高速化は最大 1％です。
7. 実際に処理が行われましたか？ 対象の処理が計測区間内で実行されたことを確認してください。リクエストがサーバーに届いたか、行が書き込まれたか、バイトが読み込まれたか、コードが結果を使用したかを確認します。遅延実行されるコード（誰も反復しないジェネレーター、誰も await しないプロミス、JIT が破棄できる結果）やタイムアウトは、実際には行われていない処理の数値を生み出します。

レポート

• まず結論を述べます。高速化、低速化、測定可能な差なし、または判定不能のいずれかです。
• 数値と単位、実行回数、範囲、制約要因を示します。たとえば、「p50 は 41 ms → 33 ms、各側 7 回の実行の中央値、実行後の範囲は 32～35 ms、1 コアでの JSON 解析が制約要因です。」
• 差があると主張しているものの制約要因を特定できない場合、片側が未調整で実行された場合、または質問 4 と 7 を確認できなかった場合は、結論を判定不能とします。不足している点を明記してください。
• PR の作成プレイブックに従い、PR の本文には主要な数値を 1 つだけ記載します。実行回数、範囲、制約要因の根拠は、リンク先の成果物またはメモファイルに記載してください。

その他のパフォーマンス資料

• Perf issueプレイブックがベースラインに基づいて計画を立てる前に、そのベースラインを検証し、その後に示されるすべての数値も検証してください。
• Hillclimbプレイブックのハーネスは、凍結する前に検証してください。凍結されたハーネスはエラー数と作業数を出力するため、採用または差し戻しの判断ごとに質問 4 と 7 を確認できます。