flamegraphs

フレームグラフ

目的

プロファイラーデータから SVG フレームグラフを生成するまでの手順をエージェントに案内し、フレームグラフの解釈方法を教えて、具体的な最適化の判断につなげます。

トリガー

• 「perf データからフレームグラフを生成するにはどうすればよいですか？」
• 「フレームグラフの読み方を教えてください」
• 「フレームグラフに幅の広いフレームがあります。これはどういう意味ですか？」
• 「Callgrind からフレームグラフを生成するにはどうすればよいですか？」
• 「2 つのフレームグラフ（変更前／変更後）を比較したいです」

ワークフロー

1. FlameGraph ツールをインストールする

git clone https://github.com/brendangregg/FlameGraph
# No install needed; scripts are in the repo
export PATH=$PATH:/path/to/FlameGraph

2. perf → フレームグラフ（最も一般的な手順）

# Step 1: record
perf record -F 999 -g -o perf.data ./prog

# Step 2: generate script output
perf script -i perf.data > out.perf

# Step 3: collapse stacks
stackcollapse-perf.pl out.perf > out.folded

# Step 4: generate SVG
flamegraph.pl out.folded > flamegraph.svg

# Step 5: view
xdg-open flamegraph.svg     # Linux
open flamegraph.svg          # macOS

ワンライナー：

perf record -F 999 -g ./prog && perf script | stackcollapse-perf.pl | flamegraph.pl > fg.svg

3. 差分フレームグラフ（変更前／変更後）

# Collect two profiles
perf record -g -o before.data ./prog_old
perf record -g -o after.data ./prog_new

# Collapse
perf script -i before.data | stackcollapse-perf.pl > before.folded
perf script -i after.data  | stackcollapse-perf.pl > after.folded

# Diff (red = regressed, blue = improved)
difffolded.pl before.folded after.folded | flamegraph.pl > diff.svg

4. Callgrind → フレームグラフ

valgrind --tool=callgrind --callgrind-out-file=cg.out ./prog
stackcollapse-callgrind.pl cg.out | flamegraph.pl > fg.svg

5. その他のプロファイラー入力

# Go pprof
go tool pprof -raw -output=prof.txt prog
stackcollapse-go.pl prof.txt | flamegraph.pl > fg.svg

# DTrace
dtrace -x ustackframes=100 -n 'profile-99 /execname=="prog"/ { @[ustack()] = count(); }' \
  -o out.stacks sleep 10
stackcollapse.pl out.stacks | flamegraph.pl > fg.svg

# Java (async-profiler)
async-profiler -d 30 -f out.collapsed PID
flamegraph.pl out.collapsed > fg.svg

6. フレームグラフの読み方

フレームグラフは、コールスタックを視覚化したものです。

• X 軸：CPU 時間（時間の経過順ではありません）。幅が広いほど時間がかかっています
• Y 軸：コールスタックの深さ。高いほど呼び出しチェーンが深くなっています
• 色：ランダム（意味はありません）。ただし、差分モードを使用している場合を除きます

注目する点：

パターン	意味	対応
下部にある幅の広いフレーム	関数自体がホットです	その関数を最適化します
幅の広いフレームと、その上に並ぶ細長い高い塔	多数の異なる呼び出し先を呼び出しています	ディスパッチがホットです。呼び出しのオーバーヘッドを削減します
非常に高いスタックと幅の広い基部	再帰が深くなっています	再帰の深さを確認し、反復処理への変更を検討します
最上部にある台地状の部分	呼び出し先のないリーフ関数です	このリーフが実際のホットスポットです
同じ形状の細いスタックが多数ある	多数のスレッドが同じ処理をしています	並列化またはバッチ処理を検討します

対処可能なホットスポットの特定：

1. 最上部にある最も幅の広いフレーム（その上に子フレームがない、または幅の狭い子フレームしかないフレーム）を探します
2. そこが実際に CPU 時間を消費している箇所です
3. 何が、なぜその処理を呼び出したのかを理解するために、下へたどります

差分フレームグラフ：

• 赤いフレーム：新しいプロファイルで時間が増えています（性能低下）
• 青いフレーム：新しいプロファイルで時間が減っています（改善）
• 一方のプロファイルにしかないフレームは、単色で表示されます

7. flamegraph.pl のオプション

flamegraph.pl --title "My App" \
              --subtitle "Release build, workload X" \
              --width 1600 \
              --height 16 \
              --minwidth 0.5 \
              --colors java \
              out.folded > fg.svg

オプション	効果
--title	SVG のタイトル
--width	ピクセル単位の幅
--height	ピクセル単位のフレームの高さ
--minwidth	N％未満のフレームを省略します（表示の煩雑さを軽減）
--colors	パレット：hot（デフォルト）、mem、io、java、js、perl、red、green、blue
--inverted	アイスクルチャート（ルートが上部）
--reverse	スタックを反転します
--cp	一貫したパレット（SVG 間で同じフレームに同じ色を使用）

参考資料

ツールのインストール、stackcollapse スクリプト、パレットのオプションについては、references/tools.md を参照してください。

関連スキル

• perf データを収集するには skills/profilers/linux-perf を使用します
• Callgrind データを収集するには skills/profilers/valgrind を使用します
• サンプリングプロファイルから LLVM PGO を行うには skills/compilers/clang を使用します