axiom-xctrace-ref by charleswiltgen/axiom
npx skills add https://github.com/charleswiltgen/axiom --skill axiom-xctrace-ref用于 Instruments 性能分析的命令行界面。支持无需 GUI 的无头性能分析。
xctrace 是 Instruments.app 背后的 CLI 工具。可用于:
要求 : 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 开发者,精准高效
注意 : 在 Xcode 26+ 中,请使用 --instrument 替代 --template 以确保可靠导出。模板可能在导出时产生“文档缺少模板错误”。
# 按名称附加到正在运行的进程
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s
# 按 PID 附加到正在运行的进程
xcrun xctrace record --instrument 'CPU Profiler' --attach 12345 --time-limit 10s
# 分析所有进程
xcrun xctrace record --instrument 'CPU Profiler' --all-processes --time-limit 10s
# 启动并分析
xcrun xctrace record --instrument 'CPU Profiler' --launch -- /path/to/app arg1 arg2
# 定位特定设备(模拟器或物理设备)
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 <路径> | 输出 .trace 文件路径 |
--time-limit <时间> | 记录时长(例如:10s, 1m, 500ms) |
--no-prompt | 跳过隐私警告(用于自动化) |
--append-run | 将运行添加到现有跟踪 |
--run-name <名称> | 为记录运行命名 |
用于查找热点函数的 CPU 采样。
xcrun xctrace record --instrument 'CPU Profiler' --attach 'MyApp' --time-limit 10s --output cpu.trace
模式 : cpu-profile 列 : time, thread, process, core, thread-state, weight (cycles), 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 视图主体分析。
xcrun xctrace record --instrument 'SwiftUI' --attach 'MyApp' --time-limit 10s --output swiftui.trace
模式 : swiftui 用途 : 查找过多的视图更新、主体重新评估
Actor 和 Task 分析。
xcrun xctrace record --instrument 'Swift Tasks' --instrument 'Swift Actors' --attach 'MyApp' --time-limit 10s --output concurrency.trace
模式 : swift-task, swift-actor 用途 : 任务调度、Actor 隔离、异步性能
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: 进程名称和 PIDcore: 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
技能 : axiom-performance-profiling, axiom-memory-debugging, axiom-swiftui-performance
文档 : /xcode/instruments, /os/logging/recording-performance-data
每周安装次数
89
仓库
GitHub 星标数
601
首次出现
2026年1月21日
安全审计
安装于
opencode74
codex69
claude-code68
gemini-cli67
cursor66
github-copilot64
Command-line interface for Instruments profiling. Enables headless performance analysis without GUI.
xctrace is the CLI tool behind Instruments.app. Use it for:
Requires : Xcode 12+ (xctrace 12.0+). This reference tested with 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
Note : In Xcode 26+, use --instrument instead of --template for reliable export. Templates may produce traces with "Document Missing Template Error" on export.
# 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
| 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 |
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
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
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 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
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
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
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>
# 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"]'
<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 nanosecondsthread: Thread ID and nameprocess: Process name and PIDcore: CPU core numberthread-state: Running, Blocked, etc.cycle-weight: CPU cyclesbacktrace: Call stack with function names# 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]
# 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
#!/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
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' ...
Causes :
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
Cause : Recording too short or no activity during recording Fix : Increase --time-limit or ensure app is actively used during recording
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
Skills : axiom-performance-profiling, axiom-memory-debugging, axiom-swiftui-performance
Docs : /xcode/instruments, /os/logging/recording-performance-data
Weekly Installs
89
Repository
GitHub Stars
601
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubFailSocketPassSnykPass
Installed on
opencode74
codex69
claude-code68
gemini-cli67
cursor66
github-copilot64
Lark CLI Wiki API 使用指南:获取知识空间节点信息与权限管理
39,100 周安装
Claude Code历史文件查找器:恢复丢失代码、搜索会话历史、分析文件操作的工具
221 周安装
AI图像增强器 - 智能提升截图清晰度,锐化模糊照片,优化社交媒体图片
216 周安装
CLIP模型:OpenAI图像文本对比预训练,零样本分类与跨模态检索指南
215 周安装
Angular SignalStore 最佳实践 - NgRx 信号状态管理规则与技巧
222 周安装
lp-agent:自动化流动性提供策略工具 | Hummingbot API 与 Solana DEX 集成
217 周安装
SkyPilot 多云编排指南:跨 AWS/GCP/Azure 自动优化机器学习成本与分布式训练
215 周安装
--run-name <name>| Name the recording run |