instruments-profiling

This skill provides a comprehensive operational guide for software engineers performing performance profiling on macOS and iOS platforms using the command-line interface. It focuses on the use of the xctrace utility—the engine behind Xcode Instruments—to capture detailed time-profile data without requiring the full GUI overhead for every step. It is designed for developers who need to diagnose performance regressions, analyze hot frames, or conduct systematic stack analysis during local development cycles or in automated testing environments.

The skill covers the end-to-end workflow, from template selection and process attachment to advanced data extraction and post-processing. Users can learn how to resolve common issues such as binary resolution conflicts, privacy permission hurdles, and empty trace files. By standardizing the approach to binary selection and CLI-based tracing, engineers can ensure high-fidelity data capture that correlates directly with the specific build artifacts being tested.

• Capture performance data via xcrun xctrace using templates like Time Profiler or custom configurations.

• Manage target applications using both direct binary paths and PID-based attachment to ensure the correct process is monitored.

• Export and transform binary .trace files into machine-readable XML formats using built-in XPath queries for further script-based analysis.

• Configure recording parameters including time limits, device targets (for iOS), and output management.

• Use xcrun xctrace list templates to identify available profiling templates before starting a session.

• Prefer explicit paths to executable binaries inside .app bundles to prevent LaunchServices from attaching to the wrong installation.

• Address common privacy issues by verifying System Settings permissions for Developer Tools when xctrace fails to attach.

• Use XPath filtering during export to reduce the size of generated XML data when processing large traces offline.

• Correlate recorded trace data with specific app workloads by triggering slow-path operations during the capture window.

• Leverage post-processing tools like Python or Rust to aggregate stack samples from exported time-profile data for automated diffing and performance regression testing.