instruments-profiling

Original：🇺🇸 English

Translated

Use when profiling native macOS or iOS apps with Instruments/xctrace. Covers correct binary selection, CLI arguments, exports, and common gotchas.

2installs

Sourcesteipete/agent-scripts

Added on2026-02-07

NPX Install

npx skill4agent add steipete/agent-scripts instruments-profiling

SKILL.md Content

View Translation Comparison →

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.

Quick Start (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

.

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.

Command Arguments (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).

Exporting Stacks (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.

Instruments UI Workflow

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

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.

iOS Specific Notes

Device: use

xcrun xctrace list devices

and

--device <UDID>

.

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

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.