ペルソナ: あなたは Go パフォーマンス測定エンジニアです。単一のベンチマーク実行から結論を導き出すことはありません。統計的厳密さと制御された条件が、あらゆる最適化決定の前提条件です。

思考モード: ベンチマーク分析、プロファイル解釈、パフォーマンス比較タスクには ultrathink を使用してください。深い推論により、プロファイリングデータの誤解釈を防ぎ、統計的に健全な結論を確保します。

Go ベンチマーキング・パフォーマンス測定

パフォーマンス向上は測定なしには存在しません。測定できれば、改善できます。

このスキルは、ベンチマークの作成、実行、結果のプロファイリング、統計的厳密さを持つ前後比較、CI での回帰追跡を含む、完全な測定ワークフローをカバーします。測定後に適用する最適化パターンについては、samber/cc-skills-golang@golang-performance スキルを参照してください。実行中のサービスでの pprof セットアップについては、samber/cc-skills-golang@golang-troubleshooting スキルを参照してください。

ベンチマークの作成

b.Loop() (Go 1.24+) — 推奨

b.Loop() はコンパイラがテスト中のコードを最適化して除去することを防ぎます。これがないと、コンパイラはデッドな結果を検出し、それらを削除して、誤解を招くほど高速な数値を生成できます。また、ループ前のセットアップコードのタイミングを自動的に除外します。

func BenchmarkParse(b *testing.B) {
    data := loadFixture("large.json") // セットアップ — タイミングから除外
    for b.Loop() {
        Parse(data)  // コンパイラはこの呼び出しを除去できない
    }
}

既存の for range b.N ベンチマークはまだ機能しますが、b.Loop() への移行が推奨されます。古いパターンでは、手動の b.ResetTimer() とデッドコード除去を防ぐためのパッケージレベルのシンク変数が必要です。

メモリ追跡

func BenchmarkAlloc(b *testing.B) {
    b.ReportAllocs() // または -benchmem フラグで実行
    for b.Loop() {
        _ = make([]byte, 1024)
    }
}

b.ReportMetric() はカスタムメトリクス(例: スループット)を追加します:

b.ReportMetric(float64(totalBytes)/b.Elapsed().Seconds(), "bytes/s")

サブベンチマークとテーブル駆動

func BenchmarkEncode(b *testing.B) {
    for _, size := range []int{64, 256, 4096} {
        b.Run(fmt.Sprintf("size=%d", size), func(b *testing.B) {
            data := make([]byte, size)
            for b.Loop() {
                Encode(data)
            }
        })
    }
}

ベンチマークの実行

go test -bench=BenchmarkEncode -benchmem -count=10 ./pkg/... | tee bench.txt

フラグ	目的
-bench=.	すべてのベンチマークを実行 (正規表現フィルタ)
-benchmem	アロケーションを報告 (B/op, allocs/op)
-count=10	統計的有意性のために 10 回実行
-benchtime=3s	ベンチマークあたりの最小時間 (デフォルト 1s)
-cpu=1,2,4	異なる GOMAXPROCS 値で実行
-cpuprofile=cpu.prof	CPU プロファイルを書き込み
-memprofile=mem.prof	メモリプロファイルを書き込み
-trace=trace.out	実行トレースを書き込み

出力形式: BenchmarkEncode/size=64-8 5000000 230.5 ns/op 128 B/op 2 allocs/op — -8 サフィックスは GOMAXPROCS、ns/op はオペレーションあたりの時間、B/op はオペレーションあたりのバイト割り当て、allocs/op はオペレーションあたりのヒープ割り当て数です。

コミットでの結果の記録

変更が測定可能なパフォーマンスへの影響を持つ場合、コミット本文に benchstat 出力を貼り付けます。これは最適化がなぜ行われたかを文書化し、将来の読者がそれを元に戻すことを防ぎ、レビュアーがベンチマークを再実行せずに主張を検証できます。

コミット形式:

perf(parser): reduce Parse allocations 50% with sync.Pool

Replace per-call []byte allocation with a pooled buffer.

goos: linux / goarch: amd64 / cpu: AMD Ryzen 9 5950X
          │    old     │              new               │
          │  sec/op    │  sec/op     vs base            │
Parse-32    4.592µ ± 2%  3.041µ ± 1%  -33.78% (p=0.000 n=10)

          │   old    │             new              │
          │   B/op   │   B/op     vs base           │
Parse-32   1.024Ki ± 0%  0.512Ki ± 0%  -50.00% (p=0.000 n=10)

          │ old  │            new             │
          │ allocs/op │ allocs/op  vs base    │
Parse-32   12.00 ± 0%   6.000 ± 0%  -50.00% (p=0.000 n=10)

ルール:

• 変更によって直接影響を受けたベンチマークのみを含める。関連のない行は削除
• ~ (統計的有意性なし) の結果は決して貼り付けない。改善は主張できません
• 結果が再現可能となるようハードウェアコンテキスト行 (goos/goarch/cpu) を含める
• パフォーマンスのみの変更には perf(scope): コミットタイプを使用

ベンチマークからのプロファイリング

ベンチマーク実行から直接プロファイルを生成します。HTTP サーバーは不要です:

# CPU プロファイル
go test -bench=BenchmarkParse -cpuprofile=cpu.prof ./pkg/parser
go tool pprof cpu.prof

# メモリプロファイル (alloc_objects は GC チャーンを示し、inuse_space はリークを示す)
go test -bench=BenchmarkParse -memprofile=mem.prof ./pkg/parser
go tool pprof -alloc_objects mem.prof

# 実行トレース
go test -bench=BenchmarkParse -trace=trace.out ./pkg/parser
go tool trace trace.out

pprof CLI リファレンス全体 (すべてのコマンド、非対話型モード、プロファイル解釈) については、pprof リファレンス を参照してください。実行トレース解釈については、トレースリファレンス を参照してください。統計比較については、benchstat リファレンス を参照してください。

リファレンスファイル

• pprof リファレンス — CPU、メモリ、ゴルーチンプロファイルの対話型および非対話型分析。完全な CLI コマンド、プロファイルタイプ (CPU vs alloc_objects vs inuse_space)、Web UI ナビゲーション、解釈パターン。このファイルを使用して、コード内で時間とメモリがどこに費やされているかを深く掘り下げます。

• benchstat リファレンス — 厳密な信頼区間と p 値検定を使用したベンチマーク実行の統計比較。出力の読み方、古いベンチマークのフィルタリング、視覚的な明確さのための結果のインターリーブ、回帰検出をカバーします。変更が単なる幸運な実行ではなく、意味のあるパフォーマンス差をもたらしたことを証明する必要がある場合に使用してください。

• トレースリファレンス — コードがいつ、なぜ実行されるかを理解するための実行トレーサー。ゴルーチンスケジューリング、ガベージコレクションフェーズ、ネットワークブロッキング、カスタムスパンアノテーションを視覚化します。pprof (CPU がどこに行くかを示す) だけでは不十分で、何が起こったかのタイムラインを見る必要があるときに使用してください。

• 診断ツール — 補助ツールの簡易リファレンス: fieldalignment (構造体パディング浪費)、GODEBUG (ランタイムログフラグ)、fgprof (フレームグラフプロファイル)、race detector (並行性バグ) など。特定の症状があり、焦点を絞った診断が必要な場合に使用してください。より単純なツールが既に質問に答える場合、pprof に頼る必要はありません。

• コンパイラ分析 — 低レベルのコンパイラ最適化洞察: エスケープ分析 (値がヒープに移動するタイミング)、インライニング決定 (どの関数呼び出しが除去されるか)、SSA ダンプ (中間表現)、アセンブリ出力。ベンチマークが予期しないアロケーションを示す場合、またはコンパイラが意図したことを実行したことを確認したい場合に使用してください。

• CI 回帰検出 — CI パイプラインでの自動パフォーマンス回帰ゲーティング。3 つのツール (PR の迅速な比較用 benchdiff、厳密なしきい値ベースのゲーティング用 cob、長期的なトレンドダッシュボード用 gobenchdata)、ノイジーネイバー軽減戦略 (クラウド CI ベンチマークが静かなマシンでも 5～10% 変動する理由)、ベンチマークを再現可能にするための自己ホスト型ランナーチューニングをカバーします。プルリクエストがコードベースを静かに低速化させないようにしたい場合に使用してください。回帰を早期に検出すれば、パフォーマンスデットの出荷を防ぎます。

• 調査セッション — Prometheus ランタイムメトリクス (ヒープサイズ、GC 頻度、ゴルーチン数)、メトリクスをコード変更と相互に関連付けるための PromQL クエリ、ランタイム設定フラグ (GC ログを有効にするための GODEBUG 環境変数)、コスト警告 (パフォーマンスタックスに直面しているとき) を組み合わせた本番パフォーマンス トラブルシューティングワークフロー。本番ベンチマークは良く見えるが実際のトラフィックが異なる場合に使用してください。

• Prometheus Go メトリクスリファレンス — prometheus/client_golang によって Prometheus メトリクスとして実際に公開される Go ランタイムメトリクスの完全なリスト。30 のデフォルトメトリクス、40+ のオプションメトリクス (Go 1.17+)、プロセスメトリクス、一般的な PromQL クエリをカバーします。runtime/metrics (Go 内部データ) と Prometheus メトリクス (/metrics からスクレイプされるもの) を区別します。モニタリングダッシュボードを設定したり、本番アラート用の PromQL クエリを書く場合に使用してください。

クロスリファレンス

• → 測定後に適用する最適化パターン ("X がボトルネックの場合、Y を適用") については、samber/cc-skills-golang@golang-performance スキルを参照してください
• → 実行中のサービスでの pprof セットアップ (有効化、セキュア化、キャプチャ)、Delve デバッガ、GODEBUG フラグ、根本原因方法論については、samber/cc-skills-golang@golang-troubleshooting スキルを参照してください
• → 日常的な常時オンモニタリング、継続的プロファイリング (Pyroscope)、分散トレーシング (OpenTelemetry) については、samber/cc-skills-golang@golang-observability スキルを参照してください
• → 一般的なテスト実装については、samber/cc-skills-golang@golang-testing スキルを参照してください
• → ベンチマーク結果の検証のために本番で Prometheus ランタイムメトリクスをクエリするには、samber/cc-skills@promql-cli スキルを参照してください