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: INLINECODE1
• 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:

- INLINECODE4

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.
• INLINECODE15: everything after -- is the target command (binary or app bundle).
• INLINECODE17: attach to running process.
• INLINECODE18: .trace output. If omitted, file saved in CWD.
• INLINECODE20: set capture duration.
• INLINECODE21: required for iOS device runs.
• INLINECODE22: 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.