ios-ettrace-performance

Capture and analyze symbolicated ETTrace flamegraph profiles from iOS simulator apps.

25|1|Updated Feb 10, 2026
One-click install
npx skills add https://github.com/wisdom-in-a-nutshell/agents --skill ios-ettrace-performance-wisdom-in-a-nutshell
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ios-ettrace-performance
Source: https://github.com/wisdom-in-a-nutshell/agents/tree/main/plugins-source/external/build-ios-apps/skills/ios-ettrace-performance
Command: npx skills add https://github.com/wisdom-in-a-nutshell/agents --skill ios-ettrace-performance-wisdom-in-a-nutshell

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Profiling iOS app launch and runtime latency on the simulator is difficult when traces are unsymbolicated, overwritten between runs, or mixed with idle thread noise. This Skill provides a repeatable workflow to link ETTrace into a simulator app, collect UUID-matched dSYMs, capture one focused trace, and analyze the processed flamegraph JSON for CPU-heavy stacks. ## Core Features & Use Cases - Guided ETTrace Capture: Step-by-step workflow for building a simulator ETTrace.xcframework, linking it into the app target, and capturing launch or runtime traces with the Homebrew ettrace runner. - dSYM Collection and Symbolication Gate: The collect_ios_dsyms.sh script gathers UUID-matched dSYMs for the app executable and embedded frameworks, failing loudly when required symbols are missing. - Flamegraph Analysis: The analyze_flamegraph_json.py script validates the ETTrace v1.1.0 processed JSON shape and reports top active self frames and inclusive stacks, excluding idle and unattributed frames. - Use Case: An engineer investigating slow cold launch links ETTrace into the debug simulator build, captures a launch trace with matched dSYMs, and reads the ranked hotspot summary to find the first-party functions dominating startup time. ## Quick Start Ask the assistant to capture a symbolicated ETTrace profile of one focused flow in your iOS simulator app and report the top CPU-heavy stacks.

Frequently Asked Questions about ios-ettrace-performance

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

FAQPage Schema
How do I profile iOS app launch time on the simulator?▼

Link a simulator-compatible ETTrace.xcframework into your app target, collect matching dSYMs, then run ettrace --simulator --launch --dsyms with your dSYM folder. Analyze the resulting processed output_<thread>.json flamegraph to find the stacks dominating startup.

How do I symbolicate an ETTrace flamegraph for an iOS app?▼

Symbolication requires UUID-matched dSYMs for the app executable and embedded dynamic frameworks. The collect_ios_dsyms.sh script searches build output and DerivedData for matching dSYMs and copies them into a folder passed to ettrace via --dsyms.

Does ETTrace work on physical iOS devices or only the simulator?▼

This workflow is validated for iOS Simulator profiling only, using the Homebrew ettrace runner with the --simulator flag and a simulator-architecture ETTrace.xcframework. Simulator mode listens on a fixed localhost port, so only one instrumented app can be profiled at a time.

Why does my ETTrace flamegraph show unsymbolicated or unattributed frames?▼

Unsymbolicated first-party frames mean the dSYM folder is missing UUID-matched symbols for the exact build being profiled. Rebuild with dSYM generation or add the correct build output directory as a search root; small amounts of system-framework or ETTrace internal noise are acceptable.

What is the difference between ETTrace raw capture JSON and processed flamegraph JSON?▼

Raw capture JSON lives under emerge-output/ with threads and libraryInfo keys and has not been symbolicated. The processed output_<thread>.json files written in the run directory contain the top-level nodes tree that the analyzer validates and summarizes.