instruments-profiling

gmcabrita's avatarfrom gmcabrita

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

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

When & Why to Use This Skill

This Claude skill provides a comprehensive guide and toolset for performance profiling and stack analysis of native macOS and iOS applications. It streamlines the complex workflow of using Apple's Instruments and the xctrace CLI, helping developers identify performance bottlenecks, automate trace recordings, and resolve common binary selection issues to ensure accurate debugging data.

Use Cases

  • Performance Bottleneck Identification: Using the Time Profiler to capture and analyze hot frames, call counts, and execution paths to optimize app responsiveness.
  • Automated Trace Recording: Utilizing xctrace CLI commands to record performance data via terminal or scripts, including time-limited captures and process attaching.
  • Accurate Binary Targeting: Implementing specific rules and verification steps to ensure Instruments profiles the intended local build rather than cached or installed app bundles.
  • Data Export and Analysis: Exporting raw trace tables to XML format for automated post-processing, stack aggregation, and custom performance reporting.
  • iOS Remote Profiling: Configuring device-specific parameters and UDIDs to profile applications running on physical iOS hardware.
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.