instruments-profiling

What This Skill Does

The instruments-profiling skill is a specialized toolkit designed to empower developers to capture, analyze, and optimize performance traces for native macOS and iOS applications using the xctrace CLI. It abstracts the complexity of Apple's Instruments suite, allowing for programmatic profiling directly from the command line. This skill is essential for diagnosing CPU spikes, memory leaks, and long-running operations by providing a structured way to record, output, and export trace data for deep analysis.

Installation

You can install this skill by running the following command in your terminal: clawhub install openclaw/skills/skills/steipete/instruments-profiling Ensure you have Xcode Command Line Tools installed and that xcrun is properly configured in your environment to interface with the profiling sub-systems.

Use Cases

• Startup Performance Optimization: Capture early app launch frames to determine what is blocking the main thread during initialization.
• Bottleneck Identification: Use the 'Time Profiler' template to identify high-latency methods in steady-state operations.
• Automated Performance Regression Testing: Integrate xctrace commands into CI/CD pipelines to capture performance data on every build, using exports to compare stack samples over time.
• CLI Tool Profiling: Profile native CLI binaries directly by piping stdout through the --target-stdout argument, ensuring all diagnostic logging is captured alongside the trace.

Example Prompts

1. "OpenClaw, profile my iOS app launch time for 30 seconds and save the trace to /tmp/startup.trace."
2. "I need to analyze why my macOS app is stuttering. Can you show me how to record a Time Profiler trace for an existing process PID 4592?"
3. "After capturing a trace, how do I export the raw time-profile data into an XML format for my custom Python analysis script?"

Tips & Limitations

• Targeting Precision: Always prefer the full absolute path to your binary (/path/To/App.app/Contents/MacOS/App) over app bundles when possible to avoid LaunchServices resolving to the wrong installed version.
• Permissions: Note that profiling requires elevated permissions; you may be prompted for your sudo password when attaching to system-protected processes.
• Data Volume: Profiling is IO intensive. For long-running sessions, be mindful of the disk space consumed by .trace files, as these can quickly grow to gigabytes in size.
• Non-Interactive Analysis: While the GUI (Instruments.app) is excellent for visual exploration, the true power of this skill lies in the export functionality, which allows you to programmatically aggregate and visualize hot frames using scripts.