instruments-profiling

Instruments プロファイリング（macOS/iOS）

ユーザーがネイティブアプリのパフォーマンスプロファイリングやスタック分析を希望する場合に、このスキルを使用します。 重点：Time Profiler、xctrace CLI、適切なバイナリ／アプリインスタンスの選択。

クイックスタート（CLI）

• テンプレートを一覧表示します：xcrun xctrace list templates
• Time Profiler を記録します（起動）：
  • xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app
• Time Profiler を記録します（アタッチ）：
  • アプリを自分で起動して PID を取得し、次を実行します：
  • xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>
• Instruments でトレースを開きます：
  • open -a Instruments /tmp/App.trace

注：xcrun xctrace --help は有効なサブコマンドではありません。xcrun xctrace help record を使用してください。

適切なバイナリの選択（重要）

注意点：Instruments が誤ったアプリ（たとえば /Applications 内のアプリ）をプロファイリングする場合があります。これは、LaunchServices が別のバンドルを解決するためです。 次のルールに従ってください。

• 起動を確実にするため、バイナリのパスを直接指定します：
  • xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App
• .app を起動する場合は、対象のバンドルであることを確認します：
  • open -n /path/App.app
  • ps -p <pid> -o comm= -o command= で確認します
• /Applications/App.app とローカルビルドの両方がある場合は、ローカルビルドのパスを明示的に指定します。
• 起動後、トレースを信頼する前にプロセスのパスを確認します。

コマンド引数（xctrace）

• --template 'Time Profiler'：xctrace list templates で取得したテンプレート名です。
• --launch -- <cmd>：-- 以降はすべて対象のコマンド（バイナリまたはアプリバンドル）です。
• --attach <pid|name>：実行中のプロセスにアタッチします。
• --output <path>：.trace の出力先です。省略すると、ファイルは CWD に保存されます。
• --time-limit 60s|5m：記録時間を設定します。
• --device <name|UDID>：iOS デバイスで実行する場合に必要です。
• --target-stdout -：起動したプロセスの stdout をターミナルに出力します（CLI ツールに便利です）。

スタックのエクスポート（CLI）

• トレースのテーブルを確認します：
  • xcrun xctrace export --input /tmp/App.trace --toc
• Time Profile の生サンプルをエクスポートします：
  • xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml
• スクリプト（Python/Rust）で後処理し、スタックを集計します。

Instruments の UI ワークフロー

• テンプレート：Time Profiler
• 「Record」を使用して、遅い処理（起動時か定常状態か）を記録します
• コールツリーのヒント：
  • システムライブラリを非表示にする
  • コールツリーを反転する
  • スレッドごとに分ける
  • 処理時間の長いフレームと呼び出し回数に注目する

注意点と対処方法

• 誤ったアプリがプロファイリングされる：LaunchServices がローカルビルドではなく、インストール済みアプリを解決しています。
  • 対処方法：バイナリのパスを直接指定するか、既知の PID を使って --attach します。
• サンプルがない／トレースが空：アプリがすぐ終了するか、処理が実行されていません。
  • 対処方法：記録時間を延長し、記録中に処理を実行します。
• プライバシー関連の確認ダイアログ：xctrace に開発者ツールのアクセス許可が必要な場合があります。
  • 対処方法：システム設定 → プライバシーとセキュリティ → 開発者ツールで、Terminal/Xcode を許可します。
• XML エクスポートのサイズが大きい：time-profile のエクスポートは非常に大きくなります。
  • 対処方法：XPath でフィルターし、オフラインで集計します。ターミナルには出力しないでください。

iOS 固有の注意事項

• デバイス：xcrun xctrace list devices と --device <UDID> を使用します。
• 必要に応じて Xcode 経由で起動し、xctrace --attach でアタッチします。
• 意味のあるスタックを得るには、デバッグシンボルが必要です。

確認チェックリスト

• トレースのプロセスパスが対象ビルドと一致していることを確認します。
• スタックに想定どおりのアプリフレームが表示されることを確認します。
• 記録が遅い処理（起動／更新）をカバーしていることを確認します。
• 最適化する場合は、自動差分比較用にスタックをエクスポートします。