argent-native-profiler

1. ツール

• native-profiler-start：起動済みデバイスでプロファイリングを開始します。iOS：CPU、ハング、リークを対象とした xctrace の記録です。
• native-profiler-stop：プロファイラーを停止し、トレースデータをタイムスタンプ付きの XML ファイルにエクスポートします。
• native-profiler-analyze：エクスポートしたトレースデータを解析し、構造化されたボトルネック情報を返します。
• profiler-stack-query：解析済みデータを詳しく調べます。ハング時のスタック、関数の呼び出し元、スレッドの内訳、リークの詳細を確認できます。
• profiler-load：ディスク上の以前のトレースセッションを一覧表示し、再調査のために再読み込みします。
• 物理 iPhone：サポート対象外です。シミュレーターを使用してください。

---

2. プラットフォームのサポート

• iOS：バックエンドは、起動済みのシミュレーターまたは接続済みのデバイスで xctrace を介して Xcode Instruments を使用します。PATH に Xcode コマンドラインツールが必要です。CPU のホットスポット、UI のハング、メモリリーク（Instruments の Leaks テーブル）を検出します。
• Android：バックエンドは、adb shell perfetto とプロセス内の WASM トレースプロセッサエンジンを介して Perfetto を使用します。CPU のホットスポットと UI のハングを検出し、ハングごとのジャンク理由コード、blocked_function によるメインスレッドの状態の内訳、GC の重複注釈を提供します。また、メモリ負荷を示す RSS 増加シグナルも報告します。これは手動で確認するための手掛かりとして扱い、リークが確定したものとはみなさないでください。perf_sample のコールスタックを取得するには、対象アプリがデバッグ可能であるか、マニフェストに <profileable android:shell="true"/> が含まれている必要があります。

---

3. 調査パターン

native-profiler-analyze で問題が検出された後、profiler-stack-query を使って根本原因を詳しく調べます。

• ハングを検出 → profiler-stack-query の mode=hang_stacks でネイティブのコールチェーン全体を確認 → mode=function_callers で疑わしい関数を確認 → ネイティブのソースコードを読みます。
• CPU ホットスポット → profiler-stack-query の mode=thread_breakdown でスレッドごとの分布を確認 → mode=function_callers で支配的な関数を確認します。
• メモリリーク → profiler-stack-query の mode=leak_stacks を object_type で絞り込み、原因となるフレームとライブラリを確認します。
  • iOS：リークの責任箇所が特定されずに返された場合（responsible frame が <Call stack limit reached>）、malloc_stack_logging: true を指定して native-profiler-start を再実行してください。Malloc Stack Logging を有効にしてアプリをコールド起動することで、リークに実際の割り当てバックトレース（責任フレームとライブラリ）が付与されます。アプリが再起動し、オーバーヘッドも増えるため、CPU／ハングの計測ではなく、リークの責任箇所を特定する必要がある場合にのみ使用してください。

調査結果を提示した後、さらに調査するか、修正を実装するか、終了するかをユーザーに確認してください。修正を適用した後は、必ず同じシナリオを再プロファイリングし、profiler-load で比較してください。対象の指標が改善したか、悪化したか、横ばいだったかを正直に報告してください。修正による実質的な効果がなかった場合や、ほかの箇所にリグレッションが生じた場合は、その旨を伝えて再検討してください。

ヒント： 再現可能な修正前／修正後の比較を行うには、最初のプロファイリング実行前に argent-create-e2e スキルを使って操作手順を e2e テストとして記録してください。以降の実行では e2e-execute で再生し、操作のばらつきをなくします。

注： argent-react-native-profiler は、React のプロファイリングと並行してネイティブのプロファイリングも自動的に開始するよう指示します。このスキルのワークフローと調査パターンは、どちらの場合にも適用されます。

---

4. ワークフロー

すべての手順を順番どおりに完了してください。途中で中断しないでください。

ステップ 0：対象アプリが実行中であることを確認する

native-profiler-start ツールは、デバイス上で実行中のアプリを自動検出します。 app_process を手動で導き出す必要はありません。アプリが起動していることだけを確認してください。

1. アプリがデバイス上ですでに実行中の場合は、ステップ 1 に進んでください（app_process は渡さないでください）。
2. アプリが実行中でない場合は、まず正しいバンドル ID を指定して launch-app を使用してください。
3. 複数の実行中ユーザーアプリがあるとツールから報告され、どれかを区別する必要がある場合にのみ、app_process を明示的に渡してください。

注：複数のビルドフレーバー（dev、staging、prod）がインストールされている場合、ツールは現在実行中のものを検出します。両方が実行中の場合は、指定を求められます。

Step 1: 記録を開始する

native-profiler-start を device_id（iOS UDID または Android シリアル番号）を指定して呼び出します。このツールは実行中のアプリを自動検出し、タイムスタンプ付きのファイル名でトレースを /tmp/argent-profiler-cwd/ に保存します。 ユーザーにアプリを操作してもらうか、シミュレーターツールを使って操作します（argent-device-interact スキルを参照）。

Step 2: 停止してエクスポートする

native-profiler-stop を device_id を指定して呼び出します。iOS では xctrace に SIGINT を送信し、トレースのパッケージ化を待ってから、CPU、ハング、リークのデータを XML にエクスポートします。エクスポートに関する警告がないか、exportDiagnostics を確認してください。Android ではデバイス上の perfetto デーモンに SIGTERM を送信し、終了するまで /proc/<pid> をポーリングしてから、.pftrace を adb pull でホストに転送します。

Step 3: 分析する

native-profiler-analyze を device_id を指定して呼び出します。CPU ホットスポット、UI ハング、メモリリークに分類し、深刻度順に並べた Markdown レポートが返されます。

Step 4: 調査結果を提示し、次のステップについて尋ねる

主な調査結果を簡潔にまとめて提示します。その後、「分析後」のガイドラインに従い、クエリツールでさらに調査するか、修正を実装するか、終了するかを尋ねます。

Step 5: 詳細を調査する

profiler-stack-query を使って、特定の調査結果を詳しく調べます。連鎖させる方法については、§3「調査パターン」を参照してください。

Step 6: 以前のセッションを再読み込みする

以前のトレースを再確認するには、次の手順を実行します。

1. profiler-load を mode=list で呼び出し、利用可能なセッションを確認します。
2. profiler-load を mode=load_native session_id=<timestamp> device_id=<UDID> で呼び出し、XML ファイルを再解析します。
3. profiler-stack-query を使って、再読み込みしたデータを調査します。

---

5. 結果の見方

ボトルネックは深刻度別に分類されます。

• RED：合計時間の 15% を超える CPU 関数、すべての UI ハング、および原因となるフレームを特定できた帰属済みのメモリリークです。早急な対応が必要です。
• YELLOW：合計時間の 3～15% を占める CPU 関数、および帰属未特定のメモリリーク（<Call stack limit reached>、ライブラリ情報なし。以下のメモリリークに関する注意事項を参照）です。調査する価値はありますが、許容できる場合もあります。

各ボトルネックの種類は、それぞれ異なる問題を示します。

• CPU ホットスポット：CPU 時間を過剰に消費するネイティブ関数です。タイトなループ、負荷の高い計算、または重複した処理を探してください。
• UI ハング：メインスレッドが長時間ブロックされ、画面のカクつきや応答停止が発生する状態です。同期 I/O、負荷の高いレイアウト処理、ロック競合などがよくある原因です。
• メモリリーク：割り当て後に解放されないオブジェクトです。一般的な原因には、保持サイクル、閉じ忘れたリソース、登録解除されていないオブザーバーなどがあります。Argent は xctrace --attach を使って記録しますが、これには malloc スタックの履歴がありません。そのため、シミュレーターではほとんどのリークが帰属未特定（<Call stack limit reached>、ライブラリ情報なし）となり、無害なシステム割り当てが大半を占めます。これらは、RED のリークとして確定したものではなく、信頼度の低い YELLOW の概要として報告されます。帰属を特定できるスタックを取得するには、起動時に malloc スタックのロギングを有効にして記録してください。

---

6. 重要な注意事項

• シミュレーターと実機の違い：シミュレーターでのプロファイリングに反映されるのはホスト Mac のパフォーマンスであり、実機のハードウェア性能ではありません。正確な CPU 時間やメモリ動作を把握するには、実機でプロファイリングしてください。
• xctrace の利用可否（iOS）：Xcode のコマンドラインツールがインストールされている必要があります。xcrun xctrace version で確認してください。
• プロファイラーのオーバーヘッド：xctrace の計測によって CPU 負荷が増加します。CPU ホットスポットの結果で JSLexer、JSONEmitter、または Hermes ランタイムの内部処理が JS スレッドの大部分を占めている場合、それらはアプリの処理ではなくプロファイラーのオーバーヘッドを反映しています。調査結果の評価では、これらの項目を割り引いて考えてください。
• 実行ごとのばらつき：実行間で CPU 使用率がわずかに変動するのは正常です。一貫して同じ方向の変化（2 回以上の実行で確認された変化、または 15% を超える差）のみを、対応が必要な兆候として扱ってください。
• ライブデータによる変動：アプリがライブ API データを取得する場合、実行間の応答の違いによって、コード変更とは無関係に描画負荷が変化します。データ依存の画面で変動が見られる場合は、その旨を記録してください。