magic-trace - Intel PT 高解像度トレース チートシート
magic-trace (Jane Street による) は Intel Processor Trace (Intel PT) を使用して高解像度実行トレースをキャプチャして表示します。サンプリングプロファイラーは平均的に時間がどこに行くか告知し、magic-trace は実際の制御フロー — すべての関数エントリと終了 — を記録します。ナノ秒解像度で最後のミリ秒間。これは希な、低遅延感応イベントに対して独自に適しています: 万のうち 1 つのリクエストが 40ms かかり、平均プロファイルは何も示さない場所。
要件
- Intel PT をサポートする Intel CPU (ほとんどの最新 Intel)
- perf と PT が有効な Linux
- ルートまたは適切な
perf_event_paranoid 設定
- フレームポインター/シンボル付きバイナリ読みやすい出力用
インストール
| 方法 | コマンド |
|---|
| バイナリ | GitHub リリースから magic-trace をダウンロード |
| opam (OCaml) | opam install magic_trace |
| パーミッション | sysctl kernel.perf_event_paranoid=-1 (または 1) |
| 確認 | magic-trace --help |
2 つのキャプチャモード
| モード | コマンド | 使用 |
|---|
| 実行中にアタッチ | magic-trace attach -pid <pid> | ライブサービス |
| コマンド実行 | magic-trace run ./my-program | 再現可能な実行 |
# アタッチ、Ctrl-C でキャプチャ、トレースを書き込み
sudo magic-trace attach -pid $(pgrep -n myservice)
スナップショットトリガー
コア考え: ローリングバッファを保持し、何か興味深いことが起きたときにスナップショット。
| トリガー | 方法 |
|---|
| 手動 | アタッチ中に Ctrl-C を押す |
| Magic ブレークポイント | アプリがスナップショットをトリガーする指定シンボルを呼び出す |
| タイマー | 固定期間後キャプチャ |
| シンボルトリガー | -trigger <symbol> で関数呼び出しでスナップショット |
# 特定の関数がヒットするたびにスナップショット
sudo magic-trace attach -pid <pid> -trigger 'handle_slow_path'
バッファは前のミリ秒を保つため、イベント自体ではなくイベント前の内容が見えます。
トレース表示
magic-trace は Perfetto UI で見られるトレースを放出。
| ステップ | アクション |
|---|
| 1 | キャプチャは trace.fxt (または類似) を生成 |
| 2 | ui.perfetto.dev を開く |
| 3 | トレースファイルをロード |
| 4 | マイクロ秒範囲に関心をズーム |
| 5 | 正確な呼び出しシーケンスと期間を読む |
| Perfetto コントロール | 実行 |
|---|
W/S | ズーム イン/アウト |
A/D | パン |
| スライスをクリック | 期間と関数詳細 |
| 範囲を選択 | 実行された内容の概要 |
見える内容
| 質問 | magic-trace 答え |
|---|
| どの関数がこの 40ms スパイクを引き起こしたか? | 正確な呼び出し、正確な期間 |
| 予期しないブランチを取ったか? | 完全な制御フロー、見える |
| 1 つのリクエスト内で時間がどこに行ったか? | ナノ秒レベルの分解 |
| syscall、ロック、または計算か? | 呼び出しシーケンスが示す |
知る価値のあるオプション
| フラグ | 目的 |
|---|
-multi-thread | すべてのスレッド追跡 |
-duration | キャプチャウィンドウの長さ |
-trigger SYMBOL | シンボルでスナップショット |
-full-execution | 短い実行全体のトレース |
-output FILE | トレース出力パス |
制限事項
| 制限 | 注釈 |
|---|
| Intel のみ | Intel PT が必要 (AMD/ARM なし) |
| 短いウィンドウ | ミリ秒、分単位ではない |
| シンボル品質 | ストリップ済みバイナリはトレース不正確 |
| オーバーヘッド | 低いが非ゼロ トレース中 |
magic-trace 対 関連ツール
| 側面 | magic-trace | perf | Perfetto |
|---|
| データ | 完全な制御フロー (Intel PT) | サンプル スタック | システム全体タイムライン |
| 解像度 | ナノ秒 | サンプル間隔 | イベントレベル |
| ウィンドウ | 最後のミリ秒 | 全実行 | 設定可能 |
| 最適用途 | 希なレイテンシースパイクの正確な記事 | 平均ホットパス | システム全体の相関 |
平均ホットパス用 perf、システム全体タイムライン用 Perfetto、1 つの希なスロー イベントの正確なストーリーが必要なときに magic-trace を使用。
リソース
