axiom-xctrace-ref

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

xctrace CLI Reference

xctrace CLI 参考文档

Command-line interface for Instruments profiling. Enables headless performance analysis without GUI.

Instruments性能分析的命令行界面，支持无需GUI的无头性能分析。

Overview

概述

xctrace

is the CLI tool behind Instruments.app. Use it for:

Automated profiling in CI/CD pipelines
Headless trace collection without GUI
Programmatic trace analysis via XML export
Performance regression detection

Requires: Xcode 12+ (xctrace 12.0+). This reference tested with Xcode 26.2.

xctrace

是Instruments.app背后的CLI工具。可用于：

在CI/CD流水线中实现自动化性能分析
无需GUI的无头跟踪数据采集
通过XML导出实现程序化跟踪数据分析
性能回归检测

要求：Xcode 12+（xctrace 12.0+）。本参考文档基于Xcode 26.2测试。

Quick Reference

快速参考

bash

undefined

bash

undefined

Record a 10-second CPU profile

录制10秒的CPU性能分析报告

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

Export to XML for analysis

导出为XML以便分析

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"]'

xcrun xctrace export --input profile.trace --toc # 查看可用表格 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

undefined

xcrun xctrace list templates

undefined

Recording Traces

录制跟踪数据

Basic Recording

基础录制

bash

undefined

bash

undefined

Using an instrument (recommended for CLI automation)

使用分析工具（CLI自动化推荐方式）

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

Using a template (may fail on export in Xcode 26+)

使用模板（Xcode 26+中导出可能失败）

xcrun xctrace record --template 'Time Profiler' --attach 'AppName' --time-limit 10s --output trace.trace


**Note**: In Xcode 26+, use `--instrument` instead of `--template` for reliable export. Templates may produce traces with "Document Missing Template Error" on export.

xcrun xctrace record --template 'Time Profiler' --attach 'AppName' --time-limit 10s --output trace.trace


**注意**：在Xcode 26+中，使用`--instrument`而非`--template`以确保可靠导出。使用模板录制的跟踪数据在导出时可能会出现“文档缺少模板错误”。

Target Selection

目标选择

bash

undefined

bash

undefined

Attach to running process by name

通过进程名称附加到运行中的应用

xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s

Attach to running process by PID

通过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

undefined

undefined

Recording Options

录制选项

Flag	Description
`--output <path>`	Output .trace file path
`--time-limit <time>`	Recording duration (e.g., `10s` , `1m` , `500ms` )
`--no-prompt`	Skip privacy warnings (use in automation)
`--append-run`	Add run to existing trace
`--run-name <name>`	Name the recording run

标志	描述
`--output <path>`	输出.trace文件路径
`--time-limit <time>`	录制时长（例如： `10s` 、 `1m` 、 `500ms` ）
`--no-prompt`	跳过隐私警告（自动化场景使用）
`--append-run`	将录制会话添加到现有跟踪数据中
`--run-name <name>`	为录制会话命名

Core Instruments

核心分析工具

CPU Profiler

CPU sampling for finding hot functions.

bash

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

Schema:

cpu-profile

Columns: time, thread, process, core, thread-state, weight (cycles), stack

CPU采样，用于查找热点函数。

bash

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

Schema：

cpu-profile

列：time、thread、process、core、thread-state、weight（cycles）、stack

Allocations

Memory allocation tracking.

bash

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

Schema:

allocations

Use for: Finding memory growth, object counts, allocation patterns

内存分配跟踪。

bash

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

Schema：

allocations

用途：查找内存增长、对象计数、分配模式

Leaks

Memory leak detection.

bash

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

Schema:

leaks

Use for: Detecting unreleased memory, retain cycles

内存泄漏检测。

bash

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

Schema：

leaks

用途：检测未释放内存、引用循环

SwiftUI

SwiftUI view body analysis.

bash

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

Schema:

swiftui

Use for: Finding excessive view updates, body re-evaluations

SwiftUI视图体分析。

bash

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

Schema：

swiftui

用途：查找过度视图更新、视图体重评估

Swift Concurrency

Actor and Task analysis.

bash

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

Schemas:

swift-task

swift-actor

Use for: Task scheduling, actor isolation, async performance

Actor与Task分析。

bash

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

Schemas：

swift-task

、

swift-actor

用途：任务调度、Actor隔离、异步性能分析

All Available 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

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

Exporting Traces

导出跟踪数据

See all available data tables in a trace

查看跟踪数据中所有可用的数据表

xcrun xctrace export --input trace.trace --toc


Output structure:
```xml
<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>

xcrun xctrace export --input trace.trace --toc


输出结构：
```xml
<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

XPath导出

bash

undefined

bash

undefined

Export specific table by schema

按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"]'

undefined

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

undefined

CPU Profile Schema

xml

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

Each row contains:

```
sample-time
```
: Timestamp in nanoseconds
```
thread
```
: Thread ID and name
```
process
```
: Process name and PID
```
core
```
: CPU core number
```
thread-state
```
: Running, Blocked, etc.
```
cycle-weight
```
: CPU cycles
```
backtrace
```
: Call stack with function names

xml

<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
```
：包含函数名的调用栈

Process Discovery

进程发现

Find Running Simulator Apps

查找运行中的模拟器应用

bash

undefined

bash

undefined

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]

输出格式：PID 状态 com.apple.UIKitApplication:com.bundle.id[xxxx][rb-legacy]

undefined

undefined

Find Device UUID

查找设备UUID

bash

undefined

bash

undefined

List booted simulators (JSON)

列出已启动的模拟器（JSON格式）

xcrun simctl list devices booted -j

List all devices

列出所有设备

xcrun simctl list devices

undefined

xcrun simctl list devices

undefined

Find Process by Name

按名称查找进程

bash

undefined

bash

undefined

Get PID of running app

获取运行中应用的PID

pgrep -f "MyApp"

List all processes with app name

列出所有包含应用名称的进程

ps aux | grep MyApp

undefined

ps aux | grep MyApp

undefined

Automation Patterns

自动化模式

CI/CD Integration

CI/CD集成

bash

#!/bin/bash

bash

#!/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

录制CPU性能分析报告

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)

—

undefined

#（使用xmllint、python或自定义工具解析XML）

undefined

Before/After Comparison

前后对比

bash

undefined

bash

undefined

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

undefined

xcrun xctrace export --input baseline.trace --xpath '...' > baseline.xml xcrun xctrace export --input after.trace --xpath '...' > after.xml

undefined

Troubleshooting

故障排除

"Document Missing Template Error" on Export

导出时出现“Document Missing Template Error”

Cause: Recording used

--template

flag in Xcode 26+ Fix: Use

--instrument

instead:

bash

undefined

原因：在Xcode 26+中使用了

--template

标志进行录制 解决方法：改用

--instrument

：

bash

undefined

Instead of

替代

xcrun xctrace record --template 'Time Profiler' ...

Use

使用

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

undefined

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

undefined

"Unable to attach to process"

“无法附加到进程”

Causes:

Process not running
Insufficient permissions
System Integrity Protection blocking

Fix:

bash

undefined

原因：

进程未运行
权限不足
系统完整性保护阻止

解决方法：

bash

undefined

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

尝试使用--all-processes替代--attach

xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 5s

undefined

xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 5s

undefined

Empty Trace Export

导出的跟踪数据为空

Cause: Recording too short or no activity during recording Fix: Increase

--time-limit

or ensure app is actively used during recording

原因：录制时长过短或录制期间无活动 解决方法：增加

--time-limit

或确保录制期间应用处于活跃状态

Symbolication Issues

符号化问题

Raw addresses in backtraces (e.g.,

0x18f17ed94

) instead of function names.

Fix: Ensure dSYMs are available:

bash

undefined

调用栈中显示原始地址（例如：

0x18f17ed94

）而非函数名。

解决方法：确保dSYM文件可用：

bash

undefined

Symbolicate trace (if needed)

对跟踪数据进行符号化（如有需要）

xcrun xctrace symbolicate --input trace.trace --dsym /path/to/App.dSYM

undefined

xcrun xctrace symbolicate --input trace.trace --dsym /path/to/App.dSYM

undefined

Limitations

限制

Privacy restrictions: Some instruments require privacy permissions granted in System Preferences
Device support: Physical device profiling requires Developer Mode enabled
Background apps: Limited profiling of backgrounded apps
Export format: XML only (no JSON export)
Template vs Instrument: In Xcode 26+, templates may not export properly

隐私限制：部分分析工具需要在系统偏好设置中授予隐私权限
设备支持：物理设备分析需要启用开发者模式
后台应用：对后台应用的分析能力有限
导出格式：仅支持XML（无JSON导出）
模板与分析工具：在Xcode 26+中，模板可能无法正常导出

Resources

资源

Skills: axiom-performance-profiling, axiom-memory-debugging, axiom-swiftui-performance

Docs: /xcode/instruments, /os/logging/recording-performance-data

技能：axiom-performance-profiling, axiom-memory-debugging, axiom-swiftui-performance

文档：/xcode/instruments, /os/logging/recording-performance-data

axiom-xctrace-ref

Original

Translation

xctrace CLI Reference

xctrace CLI 参考文档

Overview

概述

Quick Reference

快速参考

Record a 10-second CPU profile

录制10秒的CPU性能分析报告

Export to XML for analysis

导出为XML以便分析

List available instruments

列出可用的分析工具

List available templates

列出可用的模板

Recording Traces

录制跟踪数据

Basic Recording

基础录制

Using an instrument (recommended for CLI automation)

使用分析工具（CLI自动化推荐方式）

Using a template (may fail on export in Xcode 26+)

使用模板（Xcode 26+中导出可能失败）

Target Selection

目标选择

Attach to running process by name

通过进程名称附加到运行中的应用

Attach to running process by PID

通过PID附加到运行中的应用

Profile all processes

分析所有进程

Launch and profile

启动并分析应用

Target specific device (simulator or physical)

针对特定设备（模拟器或物理设备）

Recording Options

录制选项

Core Instruments

核心分析工具

CPU Profiler

CPU Profiler

Allocations

Allocations

Leaks

Leaks

SwiftUI

SwiftUI

Swift Concurrency

Swift Concurrency

All Available Instruments

所有可用的分析工具

Exporting Traces

导出跟踪数据

Table of Contents

目录

See all available data tables in a trace

查看跟踪数据中所有可用的数据表

XPath Export

XPath导出

Export specific table by schema

按schema导出特定表格

Export process info

导出进程信息

Export thread info

导出线程信息

CPU Profile Schema

CPU Profile Schema

Process Discovery

进程发现

Find Running Simulator Apps

查找运行中的模拟器应用

List apps in booted simulator

列出已启动模拟器中的应用

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

输出格式：PID 状态 com.apple.UIKitApplication:com.bundle.id[xxxx][rb-legacy]

Find Device UUID

查找设备UUID

List booted simulators (JSON)