axiom-xctrace-ref

xctrace CLI リファレンス

Instruments のプロファイリングを行うコマンドラインインターフェイスです。GUI なしでパフォーマンスを分析できます。

概要

xctrace は Instruments.app の基盤となる CLI ツールです。次の用途に使用できます。

• CI/CD パイプラインでのプロファイリングの自動化
• GUI を使わないトレースの収集
• XML エクスポートによるプログラムからのトレース分析
• パフォーマンスのリグレッション検出

必要条件：Xcode 12 以降（xctrace 12.0 以降）。このリファレンスは Xcode 26.2 でテスト済みです。

クイックリファレンス

# Record a 10-second CPU profile
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output profile.trace

# Export to XML for analysis
xcrun xctrace export --input profile.trace --toc  # See available tables
xcrun xctrace export --input profile.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]'

# List available instruments
xcrun xctrace list instruments

# List available templates
xcrun xctrace list templates

トレースの記録

基本的な記録

# Using an instrument (recommended for CLI automation)
xcrun xctrace record --instrument 'CPU Profiler' --attach 'AppName' --time-limit 10s --output trace.trace

# Using a template (may fail on export in Xcode 26+)
xcrun xctrace record --template 'Time Profiler' --attach 'AppName' --time-limit 10s --output trace.trace

注：Xcode 26 以降では、エクスポートを確実に行うため、--template の代わりに --instrument を使用してください。テンプレートを使用すると、エクスポート時に「Document Missing Template Error」が発生するトレースが生成されることがあります。

ターゲットの選択

# Attach to running process by name
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s

# Attach to running process by PID
xcrun xctrace record --instrument 'CPU Profiler' --attach 12345 --time-limit 10s

# Profile all processes
xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 10s

# Launch and profile
xcrun xctrace record --instrument 'CPU Profiler' --launch -- /path/to/app arg1 arg2

# Target specific device (simulator or physical)
xcrun xctrace record --instrument 'CPU Profiler' --device 'iPhone 17 Pro' --attach 'MyApp' --time-limit 10s
xcrun xctrace record --instrument 'CPU Profiler' --device 947DF45C-4ACB-4B3E-A043-DF2CD59A59B3 --all-processes --time-limit 10s

記録オプション

フラグ	説明
--output <path>	出力する .trace ファイルのパス
--time-limit <time>	記録時間（例：10s、1m、500ms）
--no-prompt	プライバシーに関する警告をスキップします（自動化で使用）
--append-run	既存のトレースに実行結果を追加します
--run-name <name>	記録実行の名前

主要な Instruments

CPU プロファイラー

ホットな関数を見つけるための CPU サンプリングです。

xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output cpu.trace

スキーマ：cpu-profile 列：time、thread、process、core、thread-state、weight（サイクル数）、stack

割り当て

メモリ割り当てを追跡します。

xcrun xctrace record --instrument 'Allocations' --attach 'MyApp' --time-limit 30s --output alloc.trace

スキーマ：allocations 用途：メモリの増加、オブジェクト数、割り当てパターンの特定

リーク

メモリリークを検出します。

xcrun xctrace record --instrument 'Leaks' --attach 'MyApp' --time-limit 30s --output leaks.trace

スキーマ：leaks 用途：解放されていないメモリ、循環参照の検出

SwiftUI

SwiftUI のビュー本文を分析します。

xcrun xctrace record --instrument 'SwiftUI' --attach 'MyApp' --time-limit 10s --output swiftui.trace

スキーマ：swiftui 用途：過剰なビュー更新、本文の再評価の特定

Swift Concurrency

アクターと Task を分析します。

xcrun xctrace record --instrument 'Swift Tasks' --instrument 'Swift Actors' --attach 'MyApp' --time-limit 10s --output concurrency.trace

スキーマ：swift-task、swift-actor 用途：Task のスケジューリング、アクターの分離、非同期処理のパフォーマンス

利用可能なすべての Instruments

Activity Monitor          Audio Client              Audio Server
Audio Statistics          CPU Counters              CPU Profiler
Core Animation Activity   Core Animation Commits    Core Animation FPS
Core Animation Server     Core ML                   Data Faults
Data Fetches              Data Saves                Disk I/O Latency
Disk Usage                Display                   Filesystem Activity
Filesystem Suggestions    Foundation Models         Frame Lifetimes
GCD Performance           GPU                       HTTP Traffic
Hangs                     Hitches                   Leaks
Location Energy Model     Metal Application         Metal GPU Counters
Metal Performance Overview Metal Resource Events    Network Connections
Neural Engine             Points of Interest        Power Profiler
Processor Trace           RealityKit Frames         RealityKit Metrics
Runloops                  Sampler                   SceneKit Application
Swift Actors              Swift Tasks               SwiftUI
System Call Trace         System Load               Thread States
Time Profiler             VM Tracker                Virtual Memory Trace

トレースのエクスポート

目次

# See all available data tables in a trace
xcrun xctrace export --input trace.trace --toc

出力構造：

<trace-toc>
    <run number="1">
        <info>
            <target>...</target>
            <summary>...</summary>
        </info>
        <processes>...</processes>
        <data>
            <table schema="cpu-profile" .../>
            <table schema="thread-info"/>
            <table schema="process-info"/>
        </data>
    </run>
</trace-toc>

XPath エクスポート

# Export specific table by schema
xcrun xctrace export --input trace.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]'

# Export process info
xcrun xctrace export --input trace.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="process-info"]'

# Export thread info
xcrun xctrace export --input trace.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="thread-info"]'

CPU Profile スキーマ

<schema name="cpu-profile">
    <col><mnemonic>time</mnemonic><name>Sample Time</name></col>
    <col><mnemonic>thread</mnemonic><name>Thread</name></col>
    <col><mnemonic>process</mnemonic><name>Process</name></col>
    <col><mnemonic>core</mnemonic><name>Core</name></col>
    <col><mnemonic>thread-state</mnemonic><name>State</name></col>
    <col><mnemonic>weight</mnemonic><name>Cycles</name></col>
    <col><mnemonic>stack</mnemonic><name>Backtrace</name></col>
</schema>

各行には次の情報が含まれます。

• sample-time：ナノ秒単位のタイムスタンプ
• thread：スレッド ID と名前
• process：プロセス名と PID
• core：CPU コア番号
• thread-state：実行中、ブロック中など
• cycle-weight：CPU サイクル数
• backtrace：関数名を含むコールスタック

プロセスの検出

実行中のシミュレーターアプリを探す

# List apps in booted simulator
xcrun simctl spawn booted launchctl list | grep UIKitApplication

# Output format: PID  Status  com.apple.UIKitApplication:com.bundle.id[xxxx][rb-legacy]

デバイス UUID を探す

# List booted simulators (JSON)
xcrun simctl list devices booted -j

# List all devices
xcrun simctl list devices

名前でプロセスを探す

# Get PID of running app
pgrep -f "MyApp"

# List all processes with app name
ps aux | grep MyApp

自動化パターン

CI/CD との統合

#!/bin/bash
# performance-test.sh

APP_NAME="MyApp"
TRACE_DIR="./traces"
TIME_LIMIT="30s"

# Boot simulator if needed
xcrun simctl boot "iPhone 17 Pro" 2>/dev/null || true

# Wait for app to launch
sleep 5

# Record CPU profile
xcrun xctrace record \
    --instrument 'CPU Profiler' \
    --device "iPhone 17 Pro" \
    --attach "$APP_NAME" \
    --time-limit "$TIME_LIMIT" \
    --no-prompt \
    --output "$TRACE_DIR/cpu.trace"

# Export for analysis
xcrun xctrace export \
    --input "$TRACE_DIR/cpu.trace" \
    --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]' \
    > "$TRACE_DIR/cpu-profile.xml"

# Parse and check thresholds
# (Use xmllint, python, or custom tool to parse XML)

実行前後の比較

# Record baseline
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output baseline.trace

# Make changes, rebuild app

# Record after changes
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output after.trace

# Export both for comparison
xcrun xctrace export --input baseline.trace --xpath '...' > baseline.xml
xcrun xctrace export --input after.trace --xpath '...' > after.xml

トラブルシューティング

エクスポート時の「Document Missing Template Error」

原因：Xcode 26 以降で --template フラグを使って記録した 修正方法：代わりに --instrument を使用します。

# Instead of
xcrun xctrace record --template 'Time Profiler' ...

# Use
xcrun xctrace record --instrument 'CPU Profiler' ...

「Unable to attach to process」

原因：

1. プロセスが実行されていない
2. 権限が不足している
3. System Integrity Protection によってブロックされている

修正方法：

# Verify process exists
pgrep -f "AppName"

# For simulator apps, verify simulator is booted
xcrun simctl list devices booted

# Try with --all-processes instead of --attach
xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 5s

空のトレースエクスポート

原因：記録時間が短すぎるか、記録中にアクティビティがなかった 修正方法：--time-limit を増やすか、記録中にアプリが実際に使用されていることを確認します。

シンボリケーションの問題

バックトレースに関数名ではなく、生のアドレス（例：0x18f17ed94）が表示されます。

修正方法：dSYM が利用可能であることを確認します。

# Symbolicate trace (if needed)
xcrun xctrace symbolicate --input trace.trace --dsym /path/to/App.dSYM

filtercalltree による後処理

filtercalltree は、対象を絞った分析を行うためにコールツリーの出力を変換します。sample が生成する形式のテキストファイルを入力として受け取ります。

# 1. Capture a call tree with sample (writes to /tmp/*.sample.txt)
xcrun sample MyApp 5

# 2. Invert the call tree (show hottest leaf frames first)
xcrun filtercalltree -i /tmp/MyApp_*.sample.txt

# 3. Charge library costs to callers (attribute UIKitCore time to your code)
xcrun filtercalltree -chargeLibrary=UIKitCore /tmp/MyApp_*.sample.txt

# 4. Combine: invert + charge system libraries + prune noise
xcrun filtercalltree -i -chargeSystemLibraries -pruneCount 5 /tmp/MyApp_*.sample.txt

フラグ	効果
-i	コールツリーを反転します — 最も負荷の高いリーフフレームを先頭に表示します（Instruments の「Invert Call Tree」と同様）
-chargeLibrary=X	フレームワーク X の時間を呼び出し元のコードに割り当てます（複数回指定可能）
-chargeSystemLibraries	すべての /System および /usr ライブラリの負荷を呼び出し元に割り当てます
-pruneCount N	サンプル数が N 未満のブランチを削除します
-pruneMallocSize S	malloc サイズが S 未満のブランチを削除します（例：500K、1.2M）

関連するCLIツール

これらのツールは、特定のプロファイリングニーズに対応し、xctraceを補完します。

# Quick CPU sample without full trace (5-second sample)
xcrun sample MyApp 5

# Sample by PID, save to file
xcrun sample 12345 5 -file output.txt

sampleはxctraceより軽量です。Instrumentsの全パイプラインが不要な場合に、手早くCPUを確認するために使用します。

制限事項

1. プライバシーの制限：一部のインストゥルメントでは、システム設定でプライバシー権限を付与する必要があります
2. デバイスのサポート：実機のプロファイリングには、開発者モードを有効にする必要があります
3. バックグラウンドアプリ：バックグラウンドに移行したアプリのプロファイリングには制限があります
4. エクスポート形式：XMLのみ（JSONへのエクスポートには非対応）
5. テンプレートとインストゥルメント：Xcode 26以降では、テンプレートが正しくエクスポートされない場合があります

リソース

スキル：axiom-performance-profiling、axiom-memory-debugging、axiom-swiftui-performance

ドキュメント：/xcode/instruments、/os/logging/recording-performance-data