--- name: native-app-profiling description: Profile native macOS/iOS apps using Time Profiler via CLI (xctrace). Use when asked to identify performance hotspots, profile CPU usage, or diagnose slow code paths without opening Instruments. --- # Native App Performance Profiling (CLI) ## Overview Record Time Profiler via `xctrace`, extract samples, symbolicate, and identify hotspots without opening Instruments. ## Quick Start ### 1) Record Time Profiler **Attach to running process:** ```bash # Get the PID first pgrep -x "AppName" # Record for 90 seconds xcrun xctrace record \ --template 'Time Profiler' \ --time-limit 90s \ --output /tmp/App.trace \ --attach ``` **Launch and record:** ```bash xcrun xctrace record \ --template 'Time Profiler' \ --time-limit 90s \ --output /tmp/App.trace \ --launch -- /path/to/App.app/Contents/MacOS/App ``` ### 2) Export Time Samples List available schemas in the trace: ```bash xcrun xctrace export --input /tmp/App.trace --toc ``` Export time profile data: ```bash xcrun xctrace export \ --input /tmp/App.trace \ --xpath '/trace-toc/run/data/table[@schema="time-profile"]' \ --output /tmp/time-profile.xml ``` ### 3) Get Load Address for Symbolication While the app is running, get the `__TEXT` segment load address: ```bash vmmap | grep "__TEXT" ``` Look for the load address (typically starts with `0x1...`). ### 4) Symbolicate Stack Frames Use `atos` to symbolicate addresses: ```bash atos -o /path/to/App.app/Contents/MacOS/App -l 0x100000000
``` ## Workflow Notes - **Correct binary**: Confirm you're profiling the right build (local vs /Applications) - **Trigger the slow path**: During capture, perform the action that's slow - **Capture duration**: If stacks are empty, capture longer or avoid idle time - **Symbol matching**: Binary symbols must match the trace (same build) ## Available Templates List all profiling templates: ```bash xcrun xctrace list templates ``` Common templates: - `Time Profiler` - CPU sampling - `Allocations` - Memory allocations - `Leaks` - Memory leak detection - `System Trace` - System-level activity - `Animation Hitches` - UI performance ## Common Commands | Task | Command | |------|---------| | List templates | `xcrun xctrace list templates` | | List devices | `xcrun xctrace list devices` | | Record help | `xcrun xctrace help record` | | Export help | `xcrun xctrace help export` | | Get PID | `pgrep -x "AppName"` | | Get load address | `vmmap \| grep __TEXT` | | Symbolicate | `atos -o -l
` | ## Analyzing Results ### Manual Analysis 1. Export the trace to XML 2. Parse the call tree data 3. Look for frames with high sample counts 4. Focus on your app's code (filter out system frameworks) ### Identify Hotspots Look for: - Functions with high self-time (time spent in function itself) - Deep call stacks indicating inefficient algorithms - Repeated patterns suggesting optimization opportunities ## Gotchas - **ASLR**: Runtime `__TEXT` load address changes each launch - get it from `vmmap` - **Build mismatch**: Symbols must match the exact build that was profiled - **Idle time**: Profiling idle app produces empty/useless data - **Permissions**: May need to run with `sudo` for some operations ## iOS Profiling For iOS apps on simulator: ```bash xcrun xctrace record \ --template 'Time Profiler' \ --device \ --time-limit 60s \ --output /tmp/iOS-App.trace \ --launch -- ``` Get simulator UDID: ```bash xcrun simctl list devices | grep Booted ``` ## Automation Script Basic recording script: ```bash #!/bin/bash set -e APP_NAME="$1" DURATION="${2:-60}" OUTPUT="${3:-/tmp/$APP_NAME.trace}" if [ -z "$APP_NAME" ]; then echo "Usage: $0 [duration-seconds] [output-path]" exit 1 fi PID=$(pgrep -x "$APP_NAME" || true) if [ -n "$PID" ]; then echo "Attaching to running $APP_NAME (PID: $PID)" xcrun xctrace record \ --template 'Time Profiler' \ --time-limit "${DURATION}s" \ --output "$OUTPUT" \ --attach "$PID" else echo "App not running. Please start $APP_NAME first." exit 1 fi echo "Trace saved to: $OUTPUT" echo "To analyze: xcrun xctrace export --input $OUTPUT --toc" ``` ## Checklist - [ ] Correct binary path identified - [ ] App running or launch command ready - [ ] Slow path reproducible - [ ] Trace recorded during problematic behavior - [ ] Load address captured for symbolication - [ ] Results analyzed for hotspots --- Source attribution: patrickserrano Original project: https://github.com/patrickserrano/skills License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2025 Patrick Serrano Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: patrickserrano Original project: https://github.com/patrickserrano/skills Attribution basis: Original project named by vendored-folder README Fields of work: Development & Engineering Roles: Backend Developer, DevOps / SRE, Mobile Developer, QA / Test Engineer Specialties: Backend, Mobile Tools: Xctrace Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 35e52c4f40a72c41de889d18919f1e25395495e1b034ef2249aecd2785047014 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.