trace-audit

Chrome DevTools Trace Audit

Chrome DevTools のパフォーマンストレースを分析し、包括的なパフォーマンス監査レポートを作成します。

使用方法

/trace-audit <path-to-trace.json>

引数は、Chrome DevTools のトレース JSON ファイル（Performance パネルからエクスポートしたもの）の絶対パスです。

ワークフロー

以下の手順を順番に実行します。指定されている箇所では、ツール呼び出しを並列で実行してください。

ステップ 1 — トレースファイルを検証する

Read ツールを使用して、ファイルの先頭 100 行を読み取ります。次の点を確認し、有効な Chrome DevTools トレースであることを確かめてください。

• トップレベルに traceEvents 配列がある、または [ で始まる JSON 配列である
• イベントオブジェクトに name、cat、ph、ts フィールドがある
• __metadata または TracingStartedInBrowser イベントが存在する

検証に失敗した場合、これは Chrome DevTools トレースではないようだとユーザーに伝え、処理を中止してください。

ステップ 2 — メタデータを抽出する

Grep を使用してトレースファイルからメタデータを抽出します（以下を並列で実行してください）。

1. サイト URL — TracingStartedInBrowser、navigationStart、または FrameCommittedInBrowser を検索し、args 内の URL を確認します
2. プロセス名 — process_name または thread_name を検索して、レンダラー、ブラウザー、GPU プロセスを特定します
3. トレースの時間範囲 — 最初と最後の "ts": の値を検索し、トレースの所要時間を計算します

ステップ 3 — 検出パスを実行する

パターンとしきい値の全一覧は、detection-heuristics.md を参照してください。Grep を使用して、すべての検出カテゴリを並列で実行します。各カテゴリについて、以下を行ってください。

• 指定された grep パターンをトレースファイルに適用します
• 必要に応じて、前後のコンテキストを含めた一致行を収集します（-C 1 または -C 2）
• 一致数を数え、一致した JSON から所要時間や値を抽出します

検出カテゴリは次のとおりです。

1. ロングタスク（dur > 50000 の RunTask）
2. レイアウトスラッシング（InvalidateLayout → Layout の組み合わせ）
3. 強制リフロー（stackTrace を含む Layout イベント）
4. rAF のティッカーループ（RequestAnimationFrame の頻度）
5. スタイル再計算の集中（dur > 5000 の UpdateLayoutTree）
6. ペイントの集中（dur > 3000 の Paint イベント）
7. GC の負荷（MajorGC / V8.GC_MARK_COMPACTOR）
8. CLS（LayoutShift の累積スコア）
9. INP（EventTiming の最大所要時間）
10. ネットワークエラー（statusCode >= 400 の ResourceReceiveResponse）
11. 重複したフェッチ（同じ URL が複数回フェッチされている場合）
12. スクリプト評価（dur > 50000 の EvaluateScript / CompileScript）
13. 長いアニメーションフレーム（LoAF / LongAnimationFrame）

ステップ 4 — 検出結果を集計する

検出カテゴリごとに、以下を行ってください。

• 問題として検出されたイベントの合計数を計算します
• 最も深刻な事例（所要時間が最長、またはスコアが最高のもの）を抽出します
• detection-heuristics.md のしきい値に基づいて、重大度をCritical（赤）またはWarning（黄）に分類します
• 検出結果がゼロのカテゴリは省略します

ステップ 5 — タイムラインのホットスポットを特定する

検出されたイベントをタイムスタンプごとに時間枠（例：500ms 単位）にグループ化します。複数の問題カテゴリが重なる時間枠を特定してください。これらは、トレース内で最も問題のあるセクションを示すホットスポット範囲です。

ステップ 6 — レポートを作成する

report-format.md で定義された構成に従ってレポートを出力します。レポートは次の要件を満たす必要があります。

• 実行可能 — 各問題に具体的な修正方法を示します
• スキャンしやすい — 表、重大度バッジ、明確な見出しを使用します
• 完全 — 「問題は見つかりませんでした」と示す場合も含め、すべてのカテゴリを網羅します