instruments-profiling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Instruments Profiling (macOS/iOS)

Use this skill when the user wants performance profiling or stack analysis for native apps. Focus: Time Profiler,

xctrace

CLI, and picking the correct binary/app instance.

当用户需要对原生应用进行性能分析或堆栈分析时，可使用本技能。核心内容：Time Profiler、

xctrace

CLI工具，以及如何选择正确的二进制文件/应用实例。

Quick Start (CLI)

快速入门（CLI）

List templates:
```
xcrun xctrace list templates
```

Record Time Profiler (launch):

xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app

Record Time Profiler (attach):

Launch app yourself, get PID, then:

xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>

Open trace in Instruments:
- ```
open -a Instruments /tmp/App.trace
```

Note:

xcrun xctrace --help

is not a valid subcommand. Use

xcrun xctrace help record

列出模板：
```
xcrun xctrace list templates
```

录制时间分析器（启动应用）：

xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app

录制时间分析器（附加到运行中进程）：

自行启动应用，获取PID，然后执行：

xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>

在Instruments中打开跟踪文件：
- ```
open -a Instruments /tmp/App.trace
```

注意：

xcrun xctrace --help

不是有效的子命令，请使用

xcrun xctrace help record

。

Picking the Correct Binary (Critical)

选择正确的二进制文件（至关重要）

Gotcha: Instruments may profile the wrong app (e.g., one in

/Applications

) if LaunchServices resolves a different bundle. Use these rules:

Prefer direct binary path for deterministic launch:

xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App

If launching
```
.app
```
, ensure it’s the intended bundle:
- ```
open -n /path/App.app
```
- Verify with
```
ps -p <pid> -o comm= -o command=
```
If both
```
/Applications/App.app
```
and a local build exist, explicitly target the local build path.
After launch, confirm the process path before trusting the trace.

常见问题：Instruments可能会分析错误的应用（例如，

/Applications

目录中的版本），如果LaunchServices解析到了不同的应用包。请遵循以下规则：

优先使用直接的二进制文件路径以确保启动的确定性：
- ```
xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App
```

如果启动

.app

包，请确保它是目标包：

```
open -n /path/App.app
```
使用
```
ps -p <pid> -o comm= -o command=
```
验证

如果同时存在
```
/Applications/App.app
```
和本地构建版本，请明确指定本地构建的路径。
启动应用后，在信任跟踪结果之前，请先确认进程路径。

Command Arguments (xctrace)

xctrace命令参数

--template 'Time Profiler'

: template name from

xctrace list templates

```
--launch -- <cmd>
```
: everything after
```
--
```
is the target command (binary or app bundle).
```
--attach <pid|name>
```
: attach to running process.
```
--output <path>
```
:
```
.trace
```
output. If omitted, file saved in CWD.
```
--time-limit 60s|5m
```
: set capture duration.
```
--device <name|UDID>
```
: required for iOS device runs.
```
--target-stdout -
```
: stream launched process stdout to terminal (useful for CLI tools).

--template 'Time Profiler'

：模板名称来自

xctrace list templates

的输出。

```
--launch -- <cmd>
```
：
```
--
```
之后的所有内容都是目标命令（二进制文件或应用包）。
```
--attach <pid|name>
```
：附加到运行中的进程。
```
--output <path>
```
：
```
.trace
```
格式的输出文件路径。如果省略，文件将保存在当前工作目录。
```
--time-limit 60s|5m
```
：设置捕获时长。
```
--device <name|UDID>
```
：在iOS设备上运行时必须指定。
```
--target-stdout -
```
：将启动进程的标准输出流传输到终端（对CLI工具非常有用）。

Exporting Stacks (CLI)

导出堆栈信息（CLI）

Inspect trace tables:

xcrun xctrace export --input /tmp/App.trace --toc

Export raw time-profile samples:

xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml

Post-process in a script (Python/Rust) to aggregate stacks.

查看跟踪文件目录：

xcrun xctrace export --input /tmp/App.trace --toc

导出原始时间分析样本：

xcrun xctrace export --input /tmp/App.trace --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml

使用脚本（Python/Rust）进行后处理以聚合堆栈信息。

Instruments UI Workflow

Instruments UI工作流

Template: Time Profiler
Use “Record” and capture the slow path (startup vs steady-state)
Call Tree tips:
- Hide System Libraries
- Invert Call Tree
- Separate by Thread
- Focus on hot frames and call counts

模板：Time Profiler
点击“录制”并捕获慢路径（启动阶段 vs 稳定运行阶段）
调用树技巧：
- 隐藏系统库
- 反转调用树
- 按线程分离
- 重点关注热点帧和调用次数

Gotchas & Fixes

常见问题与解决方案

Wrong app profiled: LaunchServices resolves installed app instead of local build.
- Fix: use direct binary path or
```
--attach
```
  with known PID.
No samples / empty trace: App exits quickly or never hits work.
- Fix: longer capture, trigger workload during recording.
Privacy prompts:
```
xctrace
```
may need Developer Tools permission.
- Fix: System Settings → Privacy & Security → Developer Tools → allow Terminal/Xcode.
Large XML exports:
```
time-profile
```
exports are huge.
- Fix: filter with XPath and aggregate offline; don’t print to terminal.

分析了错误的应用：LaunchServices解析到了已安装的应用而非本地构建版本。
- 解决方案：使用直接的二进制文件路径，或通过已知PID使用
```
--attach
```
  选项。
无样本/空跟踪文件：应用快速退出或未执行任何工作。
- 解决方案：延长捕获时长，在录制过程中触发工作负载。
隐私提示：
```
xctrace
```
可能需要开发者工具权限。
- 解决方案：系统设置 → 隐私与安全性 → 开发者工具 → 允许终端/Xcode访问。
XML导出文件过大：
```
time-profile
```
导出的文件体积庞大。
- 解决方案：使用XPath过滤并离线聚合；不要直接打印到终端。

iOS Specific Notes

iOS专属注意事项

Device: use

xcrun xctrace list devices

and

--device <UDID>

Launch via Xcode if needed; attach with
```
xctrace --attach
```
.
Ensure debug symbols for meaningful stacks.

设备：使用
```
xcrun xctrace list devices
```
获取设备信息，并使用
```
--device <UDID>
```
指定。
如有需要，可通过Xcode启动应用；使用
```
xctrace --attach
```
附加到进程。
确保存在调试符号以获得有意义的堆栈信息。

Verification Checklist

验证清单

Confirm trace process path matches target build.
Confirm stacks show expected app frames.
Capture covers the slow operation (startup/refresh).
Export stacks for automated diffing if optimizing.

确认跟踪文件中的进程路径与目标构建版本匹配。
确认堆栈信息显示了预期的应用帧。
捕获的内容覆盖了慢操作（启动/刷新）。
若进行优化，可导出堆栈信息以进行自动化对比。