iOS ETTrace Performance

iOS ETTrace Performance

Use this skill to capture a focused, symbolicated ETTrace profile from an iOS simulator app. Pair it with the ios-debugger-agent skill when the task also needs simulator build, install, launch, UI driving, logs, or screenshots.

Core Workflow

1. Pick one focused flow and write down the expected start and stop points.
2. Build the exact simulator app that will be installed and profiled.
3. Temporarily link ETTrace into that app target for simulator/debug profiling.
4. Collect UUID-matched dSYMs for the app executable and embedded dynamic frameworks.
5. Capture one launch or runtime trace.
6. Preserve the processed flamegraph JSON immediately after the run.
7. Analyze only the processed JSON and report the flow, artifacts, hotspots, and caveats.

Avoid broad "use the app for a while" captures. One trace should correspond to one user-visible flow.

Setup

Use a writable run folder for each profiling session:

if [ -z "${RUN_DIR:-}" ]; then
  RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/claude-ios-ettrace.XXXXXX")"
fi
mkdir -p "$RUN_DIR"

Install the ETTrace runner CLI if it is not already available:

brew install emergetools/homebrew-tap/ettrace

ettrace is the host-side macOS runner. The app must also link an ETTrace.xcframework for the iOS Simulator architecture. This workflow is validated for ETTrace v1.1.0 processed output_<thread>.json files with top-level nodes.

Link ETTrace Into The App

Wire ETTrace into the exact app target being profiled. Keep the integration in a clearly temporary patch and remove it when the profiling task is done unless the user explicitly asks to keep it.

Preferred options:

• Reuse an existing simulator-compatible ETTrace.xcframework if the repo already vendors one.
• If none exists, build a simulator-only copy into RUN_DIR from the upstream ETTrace package.
• Link the framework directly into the app target, not only into tests, resources, data files, or a nested launcher target.
• Confirm launch logs print Starting ETTrace.
• Profile only one ETTrace-instrumented simulator app at a time because simulator mode listens on a fixed localhost port.

Build a simulator framework when needed:

ETTRACE_TAG="${ETTRACE_TAG:-v1.1.0}"
ETTRACE_SRC="$RUN_DIR/ETTrace-src"
if [ ! -d "$ETTRACE_SRC" ]; then
  git clone --depth 1 --branch "$ETTRACE_TAG" https://github.com/EmergeTools/ETTrace "$ETTRACE_SRC"
fi

rm -rf "$RUN_DIR/ETTrace-iphonesimulator.xcarchive" "$RUN_DIR/ETTrace.xcframework"
pushd "$ETTRACE_SRC" >/dev/null
xcodebuild archive \
  -scheme ETTrace \
  -archivePath "$RUN_DIR/ETTrace-iphonesimulator.xcarchive" \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES \
  INSTALL_PATH='Library/Frameworks' \
  SKIP_INSTALL=NO \
  CLANG_CXX_LANGUAGE_STANDARD=c++17

xcodebuild -create-xcframework \
  -framework "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/Products/Library/Frameworks/ETTrace.framework" \
  -output "$RUN_DIR/ETTrace.xcframework"
popd >/dev/null

Symbolication Gate

Do not draw conclusions from an unsymbolicated flamegraph. Before every capture, prepare a dSYM folder that includes the app dSYM and any embedded first-party dynamic framework dSYMs.

Collect dSYMs after the final build that produced the installed app:

SKILL_DIR="<absolute path to this skill folder>"
APP="<path-to-built-simulator-App.app>"
DSYMS="$RUN_DIR/dsyms"

"$SKILL_DIR/scripts/collect_ios_dsyms.sh" \
  --app "$APP" \
  --out-dir "$DSYMS" \
  --search-root "$(dirname "$APP")" \
  --search-root "$PWD" \
  --extra-dsym "$RUN_DIR/ETTrace-iphonesimulator.xcarchive/dSYMs/ETTrace.framework.dSYM"

Add --require-framework <FrameworkName> for app-owned dynamic frameworks that must symbolicate; use --require-all-frameworks only when every embedded framework is app-owned or expected to have symbols.

Capture

For launch traces:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"
: > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --launch --verbose --dsyms "$DSYMS"

For runtime flow traces:

cd "$RUN_DIR"
CAPTURE_MARKER="$RUN_DIR/.ettrace-capture-start"
: > "$CAPTURE_MARKER"
find "$RUN_DIR" -maxdepth 1 \( -name 'output.json' -o -name 'output_*.json' \) -delete
ettrace --simulator --verbose --dsyms "$DSYMS"

Preserve Outputs

The next ETTrace run can overwrite processed flamegraph files, so preserve fresh output_<thread-id>.json files immediately.

PRESERVED_DIR="$(mktemp -d "$RUN_DIR/run-$(date +%Y%m%d-%H%M%S).XXXXXX")"
: > "$PRESERVED_DIR/summary.txt"
find "$RUN_DIR" -maxdepth 1 -name 'output_*.json' -newer "$CAPTURE_MARKER" -print | while IFS= read -r json; do
  preserved="$PRESERVED_DIR/${json##*/}"
  cp "$json" "$preserved"
  {
    echo "## ${preserved##*/}"
    python3 "$SKILL_DIR/scripts/analyze_flamegraph_json.py" "$preserved"
  } >> "$PRESERVED_DIR/summary.txt"
done

Read The Profile

Start from run-*/summary.txt, then inspect processed JSON directly if needed.

Report:

• exact flow, app build, simulator model/runtime, and run count
• processed flamegraph JSON paths
• top active leaves and inclusive first-party stacks with sample weights or percentages
• whether symbols were complete for app-owned binaries
• caveats such as first-run setup, simulator-only cost, network variance, or low sample count
• before/after deltas only when the same flow was captured with comparable setup

Cleanup

Remove temporary ETTrace app wiring when profiling is complete unless the user asked to keep it. Keep or discard run artifacts based on the active task.