linux-perf

Linux perf

目的

CPU プロファイリングで perf を使うためのガイドです。サンプリング、ハードウェアカウンターの測定、ホットスポットの特定、フレームグラフ生成との連携を扱います。

使用する場面

• 「最も CPU を消費している関数はどれですか？」
• 「キャッシュミス／IPC を測定するにはどうすればよいですか？」
• 「ホットスポットを見つけるために perf を使うにはどうすればよいですか？」
• 「perf のデータからフレームグラフを生成するにはどうすればよいですか？」
• 「perf に [unknown] または [kernel] フレームが表示されます」

ワークフロー

1. 前提条件

# Install
sudo apt install linux-perf    # Debian/Ubuntu (version-matched)
sudo dnf install perf          # Fedora/RHEL

# Check permissions
# By default perf requires root or paranoid level ≤ 1
cat /proc/sys/kernel/perf_event_paranoid
# 2 = only CPU stats (not kernel), 1 = user+kernel, 0 = all, -1 = no restrictions

# Temporarily lower (session only)
sudo sysctl -w kernel.perf_event_paranoid=1

# Persistent
echo 'kernel.perf_event_paranoid=1' | sudo tee /etc/sysctl.d/99-perf.conf
sudo sysctl -p /etc/sysctl.d/99-perf.conf

有用なフレームデータを得るため、デバッグシンボル付きで対象をコンパイルします。

gcc -g -O2 -fno-omit-frame-pointer -o prog main.c
# -fno-omit-frame-pointer: essential for frame-pointer-based unwinding
# Alternative: compile with DWARF CFI and use --call-graph=dwarf

2. perf stat — 手軽なカウンター計測

# Basic hardware counters
perf stat ./prog

# With specific events
perf stat -e cache-misses,cache-references,instructions,cycles,branch-misses ./prog

# Wall-clock comparison: N runs
perf stat -r 5 ./prog

# Attach to existing process
perf stat -p 12345 sleep 10

perf stat の出力を解釈します。

• IPC（サイクルあたりの命令数）が 1.0 未満：メモリがボトルネックになっているか、パイプラインが停止しています
• キャッシュミス率が 5% 超：キャッシュへの負荷が大きい状態です
• 分岐ミス率が 5% 超：分岐予測器がうまく機能していません

3. perf record — サンプリング

# Default: sample at 1000 Hz (cycles event)
perf record -g ./prog

# Specify frequency
perf record -F 999 -g ./prog

# Specific event
perf record -e cache-misses -g ./prog

# Attach to running process
perf record -F 999 -g -p 12345 sleep 30

# Off-CPU profiling (time spent waiting)
perf record -e sched:sched_switch -ag sleep 10

# DWARF call graphs (better for binaries without frame pointers)
perf record -F 999 --call-graph=dwarf ./prog

# Save to named file
perf record -o myapp.perf.data -g ./prog

4. perf report — 対話型分析

perf report                          # reads perf.data
perf report -i myapp.perf.data
perf report --no-children            # self time only (not cumulative)
perf report --sort comm,dso,sym      # sort by fields
perf report --stdio                  # non-interactive text output

TUI での操作：

• Enter — シンボルを展開します
• a — 注釈を表示します（ヒット数付きのアセンブリを表示します）
• s — ソースを表示します（デバッグ情報が必要です）
• d — DSO（ライブラリ）でフィルタリングします
• t — スレッドでフィルタリングします
• ? — ヘルプを表示します

5. perf annotate — ホット命令

# Show assembly with hit percentages
perf annotate sym_name

# From report: press 'a' on a symbol
# Or directly:
perf annotate -i perf.data --symbol=hot_function --stdio

mov または vmovdqa のヒット数が多い場合、そのロード時にキャッシュミスが発生している可能性があります。

6. perf top — ライブプロファイリング

# Live top, like 'top' but for functions
sudo perf top -g

# Filter by process
sudo perf top -p 12345

7. フレームグラフに取り込む

# Generate perf script output
perf script > out.perf

# Use Brendan Gregg's FlameGraph tools
git clone https://github.com/brendangregg/FlameGraph
./FlameGraph/stackcollapse-perf.pl out.perf > out.folded
./FlameGraph/flamegraph.pl out.folded > flamegraph.svg

# Open flamegraph.svg in browser

フレームグラフの読み方と結果の解釈については、skills/profilers/flamegraphs を参照してください。

8. よくある問題

問題	原因	対処方法
Permission denied	perf_event_paranoid の値が高すぎます	paranoid レベルを下げるか、sudo で実行します
[unknown] フレーム	フレームポインターまたはデバッグ情報がありません	-fno-omit-frame-pointer を指定して再コンパイルするか、--call-graph=dwarf を使います
[kernel] が至る所に表示される	カーネルシンボルが見えません	sudo perf record を使い、linux-image-$(uname -r)-dbgsym をインストールします
No kallsyms	カーネルシンボルを利用できません	`echo 0
短いプログラムのレポートが空	プログラムの終了が速すぎます	-F 9999 を使うか、より長いワークロードを計測します
DWARF アンワインドが遅い	DWARF スタックが大きすぎます	--call-graph dwarf,512 で制限します

9. 便利なイベント

# List all available events
perf list

# Common hardware events
cycles
instructions
cache-references
cache-misses
branch-instructions
branch-misses
stalled-cycles-frontend
stalled-cycles-backend

# Software events
context-switches
cpu-migrations
page-faults

# Tracepoints (requires root)
sched:sched_switch
syscalls:sys_enter_read

カウンターのリファレンスと解釈ガイドについては、references/events.md を参照してください。

関連スキル

• SVG フレームグラフの生成と読み方には、skills/profilers/flamegraphs を使います
• キャッシュのシミュレーションとメモリプロファイリングには、skills/profilers/valgrind を使います
• perf データからの PGO（AutoFDO）には、skills/compilers/gcc または skills/compilers/clang を使います