xctrace CLI 参考：命令行性能分析工具，用于iOS/macOS应用自动化性能测试与优化

axiom-xctrace-ref by charleswiltgen/axiom

155 周安装量

767 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-xctrace-ref

iOS 命令行工具性能优化

🇨🇳中文介绍

xctrace CLI 参考

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

概述

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

CI/CD 流水线中的自动化性能分析
无需 GUI 的无头跟踪记录
通过 XML 导出进行程序化跟踪分析
性能回归检测

要求 : Xcode 12+ (xctrace 12.0+)。本参考基于 Xcode 26.2 测试。

快速参考

# 记录 10 秒的 CPU 性能分析
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output profile.trace

# 导出为 XML 进行分析
xcrun xctrace export --input profile.trace --toc  # 查看可用表格
xcrun xctrace export --input profile.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]'

# 列出可用的 Instruments
xcrun xctrace list instruments

# 列出可用的模板
xcrun xctrace list templates

记录跟踪

基本记录

# 使用 Instrument（推荐用于 CLI 自动化）
xcrun xctrace record --instrument 'CPU Profiler' --attach 'AppName' --time-limit 10s --output trace.trace

# 使用模板（在 Xcode 26+ 中导出可能失败）
xcrun xctrace record --template 'Time Profiler' --attach 'AppName' --time-limit 10s --output trace.trace

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

标志	描述
`--output <路径>`	输出 .trace 文件路径
`--time-limit <时间>`	记录时长（例如：`10s`, `1m`, `500ms`）
`--no-prompt`	跳过隐私警告（用于自动化）
`--append-run`	将运行添加到现有跟踪
`--run-name <名称>`	为记录运行命名

所有可用 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

# 查看跟踪中所有可用的数据表
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>

# 按模式导出特定表格
xcrun xctrace export --input trace.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]'

# 导出进程信息
xcrun xctrace export --input trace.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="process-info"]'

# 导出线程信息
xcrun xctrace export --input trace.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="thread-info"]'

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

查找正在运行的模拟器应用

# 列出已启动模拟器中的应用
xcrun simctl spawn booted launchctl list | grep UIKitApplication

# 输出格式: PID  Status  com.apple.UIKitApplication:com.bundle.id[xxxx][rb-legacy]

# 列出已启动的模拟器（JSON 格式）
xcrun simctl list devices booted -j

# 列出所有设备
xcrun simctl list devices

按名称查找进程

# 获取正在运行应用的 PID
pgrep -f "MyApp"

# 列出所有包含应用名称的进程
ps aux | grep MyApp

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

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

# 如果需要，启动模拟器
xcrun simctl boot "iPhone 17 Pro" 2>/dev/null || true

# 等待应用启动
sleep 5

# 记录 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"

# 导出进行分析
xcrun xctrace export \
    --input "$TRACE_DIR/cpu.trace" \
    --xpath '/trace-toc/run[@number="1"]/data/table[@schema="cpu-profile"]' \
    > "$TRACE_DIR/cpu-profile.xml"

# 解析并检查阈值
# （使用 xmllint、python 或自定义工具解析 XML）

# 记录基线
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output baseline.trace

# 进行更改，重新构建应用

# 记录更改后
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output after.trace

# 导出两者进行对比
xcrun xctrace export --input baseline.trace --xpath '...' > baseline.xml
xcrun xctrace export --input after.trace --xpath '...' > after.xml

导出时出现“文档缺少模板错误”

原因 : 在 Xcode 26+ 中使用了 --template 标志修复 : 改用 --instrument：

# 不要使用
xcrun xctrace record --template 'Time Profiler' ...

# 请使用
xcrun xctrace record --instrument 'CPU Profiler' ...

“无法附加到进程”

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

# 验证进程是否存在
pgrep -f "AppName"

# 对于模拟器应用，验证模拟器已启动
xcrun simctl list devices booted

# 尝试使用 --all-processes 替代 --attach
xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 5s

原因 : 记录时间太短或记录期间无活动修复 : 增加 --time-limit 或确保应用在记录期间被积极使用

调用堆栈中显示原始地址（例如 0x18f17ed94）而非函数名。

修复 : 确保 dSYMs 可用：

# 符号化跟踪（如果需要）
xcrun xctrace symbolicate --input trace.trace --dsym /path/to/App.dSYM

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

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

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

🇺🇸English

xctrace CLI Reference

Command-line interface for Instruments profiling. Enables headless performance analysis without 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.

Quick Reference

# 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

Recording Traces

Basic Recording

# 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

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

Target Selection

# 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

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

Core Instruments

CPU Profiler

CPU sampling for finding hot functions.

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

Allocations

Memory allocation tracking.

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

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

Leaks

Memory leak detection.

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

Schema : leaks Use for : Detecting unreleased memory, retain cycles

SwiftUI

SwiftUI view body analysis.

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

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

Swift Concurrency

Actor and Task analysis.

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

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

Exporting Traces

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

Output structure:

<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

# 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

<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

Process Discovery

Find Running Simulator Apps

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

Find Device UUID

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

# List all devices
xcrun simctl list devices

Find Process by Name

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

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

Automation Patterns

CI/CD Integration

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

Before/After Comparison

# 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

Troubleshooting

"Document Missing Template Error" on Export

Cause : Recording used --template flag in Xcode 26+ Fix : Use --instrument instead:

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

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

"Unable to attach to process"

Causes :

Process not running
Insufficient permissions
System Integrity Protection blocking

Fix :

# 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

Empty Trace Export

Cause : Recording too short or no activity during recording Fix : Increase --time-limit or ensure app is actively used during recording

Symbolication Issues

Raw addresses in backtraces (e.g., 0x18f17ed94) instead of function names.

Fix : Ensure dSYMs are available:

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

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

Resources

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

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

Weekly Installs

Repository

charleswiltgen/axiom

GitHub Stars

601

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode74

codex69

claude-code68

gemini-cli67

cursor66

github-copilot64

Lark CLI Wiki API 使用指南：获取知识空间节点信息与权限管理

39,100 周安装

xctrace CLI 参考：命令行性能分析工具，用于iOS/macOS应用自动化性能测试与优化

🇨🇳中文介绍

xctrace CLI 参考

概述

快速参考

记录跟踪

基本记录

相关 Skills

目标选择

记录选项

核心 Instruments

CPU Profiler

Allocations

Leaks

SwiftUI

Swift Concurrency

所有可用 Instruments

导出跟踪

目录

XPath 导出

CPU Profile 模式

进程发现

查找正在运行的模拟器应用

查找设备 UUID

按名称查找进程

自动化模式

CI/CD 集成

前后对比

故障排除

导出时出现“文档缺少模板错误”

“无法附加到进程”

空跟踪导出

符号化问题

限制

资源

🇺🇸English

xctrace CLI Reference

Overview

Quick Reference

Recording Traces

Basic Recording

Target Selection

Recording Options

Core Instruments

CPU Profiler

Allocations

Leaks

SwiftUI

Swift Concurrency

All Available Instruments

Exporting Traces

Table of Contents

XPath Export

CPU Profile Schema

Process Discovery

Find Running Simulator Apps

Find Device UUID

Find Process by Name

Automation Patterns

CI/CD Integration

Before/After Comparison

Troubleshooting

"Document Missing Template Error" on Export

"Unable to attach to process"

Empty Trace Export

Symbolication Issues

Limitations

Resources

最新 Skills