skills.rest
hanshi-notes
hanshi-notesOFFICIAL
Explore all skills by this author →
GitHub

instruments-profiling

Record and export Time Profiler traces for macOS and iOS apps using xctrace.

2|Updated Sep 8, 2026
Search Tags:#performance#profiling#ios#macos#instruments#xctrace#time profiler
One-click install
npx skills add https://github.com/hanshi-notes/hanshi --skill instruments-profiling-hanshi-notes
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: instruments-profiling
Source: https://github.com/hanshi-notes/hanshi/tree/main/.agents/skills/instruments-profiling
Command: npx skills add https://github.com/hanshi-notes/hanshi --skill instruments-profiling-hanshi-notes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Profiling native macOS and iOS apps with Instruments is error-prone: xctrace has non-obvious CLI syntax, LaunchServices can silently profile the wrong app bundle, and exporting stack data for analysis requires obscure XPath queries. This Skill provides the exact commands, gotchas, and verification steps to capture trustworthy performance traces. ## Core Features & Use Cases - CLI Trace Recording: Record Time Profiler traces via xctrace by launching a binary directly or attaching to a running PID, with time limits and output paths. - Correct Binary Targeting: Rules to ensure Instruments profiles your local build instead of an installed copy in /Applications, including process path verification. - Stack Export & Analysis: Export raw time-profile samples to XML via XPath for offline aggregation and automated diffing of stack data. - Use Case: Your macOS app's startup feels slow. Record a 60-second Time Profiler trace against the local build binary, export the time-profile table, and aggregate hot stacks in a script to find the bottleneck. ## Quick Start Ask the assistant to record a 60-second Time Profiler trace of your app binary with xctrace and export the hot stacks for analysis.

Frequently Asked Questions about instruments-profiling

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I record a Time Profiler trace from the command line?▼

Use xcrun xctrace record with the Time Profiler template, a time limit, and an output path. Launch a binary directly with --launch -- /path/App.app/Contents/MacOS/App, or attach to a running process with --attach <pid>.

How do I export stack data from an Instruments .trace file?▼

Run xcrun xctrace export with --input pointing to the trace and an --xpath selecting the time-profile table, such as /trace-toc/run[@number="1"]/data/table[@schema="time-profile"]. Use --toc first to inspect available tables, then post-process the XML offline.

Why is Instruments profiling the wrong app instead of my local build?▼

LaunchServices may resolve the app bundle to an installed copy in /Applications rather than your local build. Fix this by passing the direct binary path inside the .app bundle, or attach to a known PID and verify the process path with ps before trusting the trace.

Can I use xctrace to profile an app on an iOS device?▼

Yes. List connected devices with xcrun xctrace list devices, then pass --device <UDID> to the record command. Launch the app via Xcode if needed and attach with xctrace, ensuring debug symbols are available for meaningful stacks.

Why is my Instruments trace empty or missing samples?▼

Empty traces usually mean the app exited quickly or never performed the target workload during recording. Extend the capture duration with --time-limit and trigger the slow operation while recording, and confirm Developer Tools permission is granted in Privacy & Security settings.

Related Skills

Explore More Software Engineering Skills→
miyakawa2449miyakawa2449

swift-build

Optimize your workspace with ergonomic desk accessories designed for comfort and productivity.

Community
Advanced
harperreedharperreed
330

native-app-performance

Analyze macOS/iOS performance hotspots from Instruments Time Profiler traces via CLI.

Community
Intermediate
moolah-rocksmoolah-rocks
1

profile-performance

Diagnose UI freezes and main-thread hangs in the Moolah macOS app using stack sampling and Instruments.

Official
Intermediate
commontoolsinccommontoolsinc
37

ct

Automate charm deployment and management using the ct CLI.

Official
Intermediate