How do I ensure I'm profiling the correct binary?

Prefer a direct binary path for deterministic launch and verify the process path after launch (ps -p -o comm= -o command=). If profiling an app from a local build, explicitly target that path instead of a installed app.

How do I export stacks from a trace?

Use xcrun xctrace export --input /tmp/App.trace --toc to inspect, and export raw time-profile samples with a specific XPath, e.g. ... --xpath '/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]' --output /tmp/time-profile.xml.

What if there are no samples or the app exits quickly?

Increase or adjust --time-limit, ensure workload is active during recording, and consider attaching to a running process so profiling occurs during work rather than idle startup.

Instruments Profiling

Verified

@steipete

npx machina-cli add skill @steipete/instruments-profiling --openclaw

Files (1)

SKILL.md

3.7 KB

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.

Source

git clone https://clawhub.ai/steipete/instruments-profilingView on GitHub

Overview

Use this skill to performance-profile native macOS and iOS apps with Time Profiler and the xctrace CLI. It covers choosing the correct binary, CLI arguments, exporting stacks, and handling common gotchas to ensure accurate traces.

How This Skill Works

You run xcrun xctrace to record Time Profiler traces either by launching the app or attaching to an existing process, then export or inspect the resulting .trace. A critical step is verifying the traced process path to avoid profiling the wrong binary or installed app.

When to Use It

Profiling startup-time and initialization behavior of a native macOS/iOS app
Attaching to a running process to profile during an active workload
Exporting time-profile data or stacks for automated analysis or diffing
Verifying and forcing the correct binary/app is profiled to avoid LaunchServices mismatches
Handling privacy prompts or large XML exports during profiling

Quick Start

Step 1: List templates: xcrun xctrace list templates
Step 2: Record Time Profiler (launch): xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --launch -- /path/To/App.app
Step 3: Record Time Profiler (attach): xcrun xctrace record --template 'Time Profiler' --time-limit 60s --output /tmp/App.trace --attach <pid>

Best Practices

Prefer launching via a direct binary path for deterministic results: xcrun xctrace record ... --launch -- /path/App.app/Contents/MacOS/App
Always verify the launched process path (e.g., with ps) to ensure you’re profiling the intended build
Set a defined capture duration with --time-limit to prevent overly large traces
Use --output to control trace location and consider exporting with XPath to limit data size
In the Instruments UI, hide system libraries, invert the call tree, separate by thread, and focus on hot frames

Example Use Cases

Startup profiling of a macOS app to identify slow initialization paths
Attaching to a long-running process to pinpoint hot paths under load
Profiling an iOS app on a device using a UDID and --device for device runs
Exporting time-profile data to XML for automated diffing between builds
Verifying the traced process path to ensure profiling of the local build rather than a installed app

Frequently Asked Questions

Add this skill to your agents