instruments-profiling

steipete's avatarfrom steipete

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

⭐648stars🔀53forks📁View on GitHub🕐Updated Jan 1, 2026
[Debugging]

When & Why to Use This Skill

This Claude skill provides expert-level guidance for profiling native macOS and iOS applications using Apple's Instruments and the xctrace command-line utility. It simplifies complex performance analysis workflows by offering precise CLI arguments, deterministic binary selection strategies to avoid common path resolution errors, and advanced techniques for exporting stack data for automated analysis.

Use Cases

  • Performance Bottleneck Identification: Using the Time Profiler to locate hot frames and optimize CPU usage in native Apple platform apps.
  • Automated Performance Testing: Implementing xctrace CLI commands within CI/CD pipelines to record and export performance traces automatically.
  • Troubleshooting Build Conflicts: Resolving 'wrong binary' issues where Instruments targets an installed app version instead of the local development build.
  • Custom Data Analysis: Exporting raw trace data to XML via XPath for post-processing in Python or Rust to generate custom performance reports.
nameinstruments-profiling
descriptionUse when profiling native macOS or iOS apps with Instruments/xctrace. Covers correct binary selection, CLI arguments, exports, and common gotchas.
short-descriptionInstruments profiling for macOS/iOS apps

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.