native-app-profiling

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:

# 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 <pid>

Launch and record:

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:

xcrun xctrace export --input /tmp/App.trace --toc

Export time profile data:

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:

vmmap <pid> | grep "__TEXT"

Look for the load address (typically starts with 0x1...).

4) Symbolicate Stack Frames

Use atos to symbolicate addresses:

atos -o /path/to/App.app/Contents/MacOS/App -l 0x100000000 <address>

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:

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 <pid> | grep __TEXT
Symbolicate	atos -o <binary> -l <load-addr> <address>

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:

xcrun xctrace record \
    --template 'Time Profiler' \
    --device <simulator-udid> \
    --time-limit 60s \
    --output /tmp/iOS-App.trace \
    --launch -- <bundle-id>

Get simulator UDID:

xcrun simctl list devices | grep Booted

Automation Script

Basic recording script:

#!/bin/bash
set -e

APP_NAME="$1"
DURATION="${2:-60}"
OUTPUT="${3:-/tmp/$APP_NAME.trace}"

if [ -z "$APP_NAME" ]; then
    echo "Usage: $0 <app-name> [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