perfetto-performance-analysis

Perfetto のパフォーマンス分析

ライセンス：AGPL-3.0-or-later。ソース：Perfetto Skills。

症状名から推測するのではなく、証拠に基づいてトレースを分析します。同梱スクリプトを使って決定的なクエリを実行し、選択したワークフローに必要なリファレンスのみを読み込みます。

要件

Python 3.11 以降、ローカルファイルシステムとターミナルへのアクセス、チェックサム検証済みの Perfetto trace_processor_shell を使用します。インストール後は単独で実行できます。SmartPerfetto も上流の Perfetto チェックアウトも必要ありません。

運用契約

1. Skill のルートを、この SKILL.md があるディレクトリとして解決します。スクリプトとリファレンスのパスを実行前に絶対パスに変換してください。クライアント固有の環境変数が存在することを前提にしないでください。
2. 分析の前に、入力するすべてのトレースパス、SHA-256、指定されたプロセス／スレッド、時間範囲、トレース側を記録します。
3. ドメインクエリの前に scripts/perfetto_probe.py を実行します。利用できないテーブル、モジュール、トラック、トレース信号は、否定的な証拠ではなく制約として扱ってください。
4. 以下から主となるワークフローを1つ選択します。その Markdown ファイルを直接読み込み、利用可否の確認手順と証拠の順序に従ってください。
5. エクスポート済みの Skill 全体を実行するには scripts/perfetto_skill.py run を、マニフェストのクエリを1つ実行するには scripts/perfetto_query.py --query-id を使用します。保存する各結果には、クエリのソース、パラメーター、トレースの識別情報、タイムスタンプ、期間、単位、返された行数の範囲を記録してください。
6. 作成または変更した SQL を実行する前に、SQL ガードレールスクリプトを実行します。SQL ガードレールの契約に従って、実行を妨げる指摘を解決し、注意事項を確認してください。
7. 観察事項、相関関係、メカニズム、検証済みの根本原因を区別します。主張するプロセス、スレッド、時間範囲、トレースを裏付ける証拠なしに、仮説を確定事項として扱わないでください。
8. 比較する場合は、差分を計算する前に各トレースを個別に分析します。一方のトレースでメトリックが欠けていることを、もう一方で性能が低下した証拠として扱わないでください。
9. assets/report-schema.json に示された構成で出力します。不足している証拠と未解決の代替説明は、limitations に記載してください。

結論を書く前に、証拠の契約を読み、識別情報のルール、欠損データのルール、主張の検証を確認してください。

ワークフローの案内

• トレースの健全性、範囲、識別、広範なトリアージ：トレースの概要
• コールド、ウォーム、ホット、初回フレームの起動：起動
• フレームの生成と表示、スクロール、カクつき：スクロール
• タッチ、クリック、入力のディスパッチ、応答、ナビゲーション：インタラクション
• ANR、Binder、ロック、futex、ブロッキングチェーン：ANR とブロッキング
• CPU 負荷、トポロジー、周波数、アイドル、IRQ、スケジューラのレイテンシ：CPU スケジューリング
• RSS、ヒープ、GC、LMK、DMA-BUF、割り当て：メモリ
• GPU、SurfaceFlinger、フェンス、VRR、フレーム合成：GPU レンダリング
• Rails、ウェイクロック、バッテリー、温度、スロットリング：電力と温度
• ファイルシステム、ブロック IO、ネットワーク、モデム、メディア、WebView：IO、ネットワーク、メディア
• Compose、Flutter、React Native、ゲーム、ベンダーシグナル：フレームワークとゲーム
• レンダリングアーキテクチャの検出と解説：レンダリングパイプライン
• ドメインをまたぐイベントシーケンスの再構築：シーンの再構築
• 2 つ以上のトレースまたは保存済みの結果セット：トレースの比較

ワークフロー ID の選択または検証には、機械可読なワークフローインデックスを使用してください。

ランタイムコマンド

決定論的でポータブルな Skill グラフを一覧表示または実行します。

python3 <skill-root>/scripts/perfetto_skill.py list
python3 <skill-root>/scripts/perfetto_skill.py run /absolute/trace.pftrace \
  --skill startup_analysis --param 'package="com.example"' \
  --output-dir /absolute/output/run

Skill で宣言されている入力のみを --param で渡してください。ランナーはトレースに触れる前に、それ以外の名前を拒否します。プロセス ID ゲートを持つ Skill では、ID の別名（package、process_name など）も受け付けます。このゲートは process_identity_resolver Skill で指定されたプロセスを検証し、別名を検証済みの process.name に書き換えます。検証できない、または曖昧な対象は理由（identity_blocked）とともに拒否されます。同じ名前で再試行せず、代わりにその Skill の候補から正確なプロセス名を選んでください。検証済みの upid（または UPID が 1 つの pid）を指定すると、そのプロセスのみを対象に Skill が実行されます。その方法では SQL を実行できない Skill は、実行可能な Skill とともに拒否されます。

Skill の完全な実行と --query-id による実行では、SQL の実行前に、選択したプロセッサーのコミット、RPC API、プラットフォーム、SHA-256 をリリースロックと照合して検証します。この識別情報を個別に確認するには、次を実行します。

python3 <skill-root>/scripts/perfetto_doctor.py

明示的にカナリアとラベル付けする場合に限り、--allow-unsupported-processor を使用してください。これを使用しても、結果が検証済みの証拠になるわけではありません。機能ゲート付きクエリは、同じトレースに対する自動プローブで必要なスキーマが確認された後にのみ実行されます。ゲートの結果は証拠のサイドカーに保持されます。--allow-unverified は、未検証と明示的に分類されたクエリに対してのみ使用する別個のオプトインであり、機能が不足している場合にそれを迂回することはありません。

トレースをプローブします。

python3 <skill-root>/scripts/perfetto_probe.py /absolute/path/to/trace.pftrace \
  --output /absolute/path/to/output/probe.json

参照された SQL アセットを実行します。

python3 <skill-root>/scripts/perfetto_query.py /absolute/path/to/trace.pftrace \
  --sql-file <skill-root>/references/generated/sql/<query>.sql \
  --format json --output /absolute/path/to/output/query.json

SmartPerfetto DSL のプレースホルダーをバインドするには、SQL テキストを編集せず、公開ラッパーを使用してください。--param NAME=JSON はスカラー入力と JSON 配列を安全にバインドします（配列は IN (...) 用の SQL リテラルリストとして出力されます）。--module android.example.module は宣言された前提条件を読み込み、--result NAME=/path/prior.json は空でない保存済み行配列を、依存するステップのリレーションとして公開します。${prior_step.data[0].upid} のようなパイプライン式は、これらの行からスカラー値を選択します。${name|default} 形式のプレースホルダーは、name が省略された場合、JSON の null に解決された場合、または保存済み結果の行を超えるインデックスを参照した場合にデフォルト値を使用します。そのため、空の先行ステップを参照するデフォルト値付きのパスには --result は不要です。

python3 <skill-root>/scripts/perfetto_query.py /absolute/trace.pftrace \
  --sql-file <skill-root>/references/generated/sql/<skill>/<step>.sql \
  --module android.frames.timeline \
  --param 'package="com.example"' --param start_ts=123 \
  --result prior_step=/absolute/output/prior-step.json \
  --output /absolute/output/current-step.json

ランタイムは、解決されていないプレースホルダーを拒否します。また、trace-processor の標準出力と標準エラー出力は、デフォルトでそれぞれ 16 MiB に制限されます。上限を引き下げるには --max-output-bytes を使用してください。引き上げるのは、レビュー済みで明示的に上限を定めたクエリに限ってください。

比較を行うには、まず独立して分析した各トレースについて、assets/comparison-input-schema.json を使って片側のサマリーファイルを 1 つずつ作成します。その後、次を実行します。

scripts/perfetto_compare.py --side baseline=a.json --side candidate=b.json --baseline baseline

trace_processor_shell が使用できない場合は、scripts/bootstrap_trace_processor.py を実行するか、--trace-processor または PERFETTO_TRACE_PROCESSOR を使ってロック済みの実行ファイルを指定してください。

参照情報の検索

生成された参照情報は多数あります。カタログ全体を読み込まずに、SmartPerfetto Skill、SQL ステップ、テーブル、またはシグナルを検索できます。

rg -n "<skill-id|table|signal>" <skill-root>/references/generated

直接リンクされた結果と、そのソースの来歴を読み込んでください。ファイル名だけからステップの意味を推測しないでください。

互換性

Python 3.11 以降、ファイルシステムへのアクセス、ターミナルでの実行、および互換性のある Perfetto trace_processor_shell が必要です。ポータブルな手順は、Agent Skills を実装し、これらの機能を公開する Codex、Claude Code、OpenCode、その他のクライアントで使用できます。ローカルファイルやターミナルにアクセスできないクラウド専用エージェントは、手法の参照情報を利用できますが、トレースクエリは実行できません。