Goランタイムの「ランタイム・トレース解析」完全ガイド：実行時間のミリ秒単位の停滞を追い込む手法
「昨夜、リクエストの一部が200msほど遅延した。しかし、CPU使用率もメモリ消費も正常範囲内だった」
SREやバックエンドエンジニアが最も頭を抱えるのが、この「再現性の低いスパイク」です。通常の`pprof`によるCPUプロファイリングは「どの関数が計算資源を使っているか」を教えてくれますが、「なぜその処理が開始されなかったのか」という待機（Latency）の正体までは教えてくれません。
世界最高峰のGoエンジニアが、数ミリ秒の謎の停滞を徹底的に破壊するために手にする武器。それが`go tool trace`です。本稿では、Goランタイムの内部挙動を可視化し、スケジューラやGCの微細な挙動を制御するための「真の解析術」を伝授します。
—
1. なぜ「CPUプロファイリング」だけでは不十分なのか
多くの開発者は、パフォーマンス低下に直面するとまず`go tool pprof`を実行します。しかし、pprofは「実行中の状態」を統計的にサンプリングするツールです。
一方で、マイクロサービスのレスポンスを悪化させる真犯人は、往々にして「何もしていない時間（Off-CPU）」に潜んでいます。
- スケジューラの遅延: ゴルーチン(G)は実行準備ができているのに、論理プロセッサ(P)が割り当てられない。
- GCのMark Assist: GCのマーク処理が追いつかず、アプリケーションのゴルーチンが強制的にGCを手伝わされている。
- システムコールのブロック: ネットワークIOやディスクIOの完了を待つOSスレッドの挙動。
これらをミリ秒以下の精度で時系列に並べて可視化できるのは、`runtime/trace`だけです。
—
2. 現場で即戦力となる「トレース取得」の実装パターン
本番環境でトレースを取得する際、最も避けるべきは「トレース取得自体のオーバーヘッドでサービスを落とすこと」です。トレースはイベントベースで記録されるため、高負荷なサービスでは数秒で数百MBのデータが生成されます。
実践的なHTTPエンドポイントの実装
標準の`net/http/pprof`をそのまま使うのも良いですが、チーム開発では「誰が、いつ、どれだけの期間トレースを取得するか」を制御するラッパーを用意するのがプロの鉄則です。
import (
“net/http”
“runtime/trace”
“time”
)
// TraceHandler は指定された秒数だけ実行トレースを取得し、レスポンスとして返す
func TraceHandler(w http.ResponseWriter, r http.Request) {
// 1. セキュリティ：認証チェックなどをここに実装（本番では必須）
// 2. 取得時間の決定（デフォルト5秒、最大30秒に制限してバーストを防ぐ）
secStr := r.URL.Query().Get(“seconds”)
duration, _ := time.ParseDuration(secStr + “s”)
if duration == 0 || duration > 30time.Second {
duration = 5 time.Second
}
// 3. トレースの開始
// トレースは内部的にバイナリ形式のバッファに書き込まれる
w.Header().Set(“Content-Type”, “application/octet-stream”)
w.Header().Set(“Content-Disposition”, `attachment; filename=”trace.out”`)
if err := trace.Start(w); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
// 4. 指定時間待機
time.Sleep(duration)
// 5. トレース停止
trace.Stop()
}
—
3. `go tool trace` を極める：隠れた操作と解析の勘所
取得した `trace.out` を解析する際、大半のエンジニアは `go tool trace trace.out` を実行してブラウザを眺めるだけで終わります。しかし、ここからがアーキテクトの腕の見せ所です。
3.1. 画面操作のキーボードショートカット（生産性の鍵）
ブラウザで表示されるトレースビューア（Catapult）は、非常に強力なショートカットを備えています。これを知らずにマウスでスクロールするのは時間の無駄です。
- `W` / `S`: ズームイン / ズームアウト（ミリ秒からマイクロ秒単位へ潜る）
- `A` / `D`: 左に移動 / 右に移動（時系列の移動）
- `1`: 選択モード（イベントをクリックして詳細を見る）
- `2`: パンモード（画面を掴んで移動）
- `Shift + ?`: ヘルプ表示（全てのコマンドを確認）
3.2. 解析のチェックポイント：どこに「停滞」が隠れているか
ビューアを開いたら、以下の3点を重点的にチェックしてください。
1. Goroutine Analysis (ゴルーチン解析):
特定の処理が「Runnable（実行可能だが待機中）」の状態で長く留まっていないか？ もし長いなら、`GOMAXPROCS`の設定不足か、特定のゴルーチンがCPUを占有している可能性があります。
2. Minimum Mutator Utilization (MMU) グラフ:
GCによってアプリケーション（Mutator）が利用可能なCPUリソースの割合を示すグラフです。急激に落ち込んでいるポイントがあれば、そこが「GCによる停止（STW）」あるいは「Mark Assist」が発生している瞬間です。
3. Syscall Blocking:
「Network Wait」ではなく「Syscall」で止まっている場合、ファイルIOや、CGO呼び出しによるランタイム外での停滞を疑います。
—
4. プロのテクニック：User Annotation でビジネスロジックを紐付ける
`go tool trace` の唯一の弱点は、低レイヤすぎて「どのビジネスロジックが実行されているか」が直感的に分かりにくい点です。これを解決するのが User Annotation です。
func ProcessOrder(ctx context.Context, orderID string) {
// Taskを作成：一連の処理をグループ化する
ctx, task := trace.NewTask(ctx, “processOrder”)
defer task.End()
trace.Log(ctx, “orderID”, orderID) // ログをトレースに埋め込む
// Regionを作成：特定のフェーズを区切る
trace.WithRegion(ctx, “validateCart”, func() {
// バリデーション処理
validateCart()
})
trace.WithRegion(ctx, “dbUpdate”, func() {
// DB更新処理
updateDB()
})
}
これを仕込んでおくと、`go tool trace` の “User-defined tasks” メニューから、特定の `orderID` に紐づく処理がどのP（プロセッサ）で、いつ、どれだけ待機したかを完璧に追跡できるようになります。
—
5. チーム開発における「計測の標準化」
個々のエンジニアがバラバラに計測しても知見は溜まりません。チーム全体でパフォーマンス文化を根付かせるための設定を共有しましょう。
VS Code / GoLand での設定
IDEのデバッグ設定に、常にプロファイリング用エンドポイントを有効化する環境変数を仕込んでおくことを推奨します。
`.vscode/settings.json` の例:
{
“go.toolsEnvVars”: {
“GODEBUG”: “gctrace=1,schedtrace=1000”
},
“go.testFlags”: [
“-v”,
“-trace=trace.out” // テスト実行時に常にトレースを取得する（CIでの回帰テストに有用）
]
}
Makefile による共通化
「誰でも1コマンドでプロファイリング結果を取得し、解析を開始できる」状態を作ります。
プロダクションの特定のPodから5秒間トレースを取得し、ブラウザで開く
.PHONY: trace-remote
trace-remote:
curl -o trace.out “http://api-service-internal/debug/pprof/trace?seconds=5”
go tool trace trace.out
ローカルでのベンチマークとトレース解析を一気に行う
.PHONY: bench-trace
bench-trace:
go test -bench . -trace trace.out
go tool trace trace.out
—
結論：ミリ秒の遅延を「勘」で直す時代は終わった
Goランタイムは非常に優秀ですが、ブラックボックスではありません。`go tool trace` を使いこなし、スケジューラやGCの挙動を可視化できるようになれば、勘に頼ったチューニングから卒業できます。
1. サンプリング(pprof)で「何が重いか」を知る。
2. トレース(trace)で「なぜ待たされているか」を突き止める。
3. アノテーション(NewTask)で「ビジネスロジック」と紐付ける。
この3ステップをマスターしたエンジニアがいるチームは、いかなるスパイクにも動じない強固なマイクロサービスを構築できるはずです。今日から、あなたのサービスに `trace.NewTask` を一行、忍ばせてみてください。その一行が、将来の深刻なトラブルを解決する鍵になります。