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+ 中，请使用 --instrument 而不是 --template，以确保可靠导出。模板可能会导致导出时出现“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 并发

分析 Actor 和 Task。

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

架构：swift-task、swift-actor 用途：Task 调度、Actor 隔离和异步性能

所有可用的 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 分析架构

<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. 系统完整性保护（SIP）阻止了操作

修复方法：

# 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）

配套命令行工具

这些工具可满足特定的性能分析需求，作为 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 更轻量——如果只需快速检查 CPU，无需使用完整的 Instruments 工作流，请使用它。

限制

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