Ios Ettrace Performance

interface:
  display_name: "iOS ETTrace Performance"
  short_description: "Profile symbolicated iOS simulator flows with ETTrace"
  default_prompt: "Use $ios-ettrace-performance to capture a focused iOS simulator ETTrace profile and identify time-heavy stacks."

#!/usr/bin/env python3
"""Summarize ETTrace processed flamegraph JSON for performance triage.

This helper intentionally accepts only the Homebrew ETTrace v1.1.0 processed
flamegraph shape: one `output_<thread>.json` file with a top-level `nodes`
tree. ETTrace raw capture JSON usually lives under an `emerge-output/` temp
folder and has keys such as `threads` and `libraryInfo`; this script rejects
that shape because it has not been symbolicated into flamegraph nodes.

ETTrace v1.1.0 stores `duration` as inclusive time on every real frame and
appends an empty terminal child with zero duration to preserve same-name stack
buckets. The strict validation here is deliberate: a malformed or legacy file
should fail loudly instead of producing misleading hotspot evidence.
"""

from __future__ import annotations

import argparse
import json
import math
import sys
from collections import defaultdict
from pathlib import Path
from typing import Any


sys.setrecursionlimit(200_000)

IDLE_FRAMES = {
    "mach_msg_trap",
    "__psynch_cvwait",
    "semaphore_wait_trap",
    "kevent_id",
    "__ulock_wait",
    "__workq_kernreturn",
    "__semwait_signal",
    "nanosleep",
    "poll",
    "select",
    "start_wqthread",
}

WRAPPER_FRAME_EXACT = {
    "start",
    "main",
    "libsystem_kernel.dylib",
    "UIApplicationMain",
    "-[UIApplication _run]",
    "GSEventRunModal",
    "_CFRunLoopRunSpecificWithOptions",
    "__CFRunLoopRun",
    "__CFRunLoopDoSource0",
    "__CFRunLoopDoSource1",
    "__CFRunLoopServiceMachPort",
    "__CFMachPortPerform",
    "__CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE0_PERFORM_FUNCTION__",
    "__CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE1_PERFORM_FUNCTION__",
    "__CFRUNLOOP_IS_SERVICING_THE_MAIN_DISPATCH_QUEUE__",
    "_dispatch_client_callout",
    "_dispatch_main_queue_callback_4CF",
    "_dispatch_main_queue_drain",
}

WRAPPER_FRAME_PREFIXES = (
    "runApp<",
    "closure #1 in App.",
)

APP_ENTRYPOINT_SUFFIXES = (
    ".$main()",
    ".main()",
    ".mainApp()",
)


def is_idle(frame: str) -> bool:
    """Return whether a frame represents a blocked or sleeping thread."""
    return frame in IDLE_FRAMES


def is_unattributed(frame: str) -> bool:
    """Return whether ETTrace could not map a sample to a symbol."""
    return frame == "<unattributed>"


def is_wrapper_frame(frame: str) -> bool:
    """Return whether an inclusive frame is generic app/run-loop scaffolding."""
    if frame in WRAPPER_FRAME_EXACT:
        return True

    if any(frame.startswith(prefix) for prefix in WRAPPER_FRAME_PREFIXES):
        return True

    if frame.startswith("static ") and any(frame.endswith(suffix) for suffix in APP_ENTRYPOINT_SUFFIXES):
        return True

    return False


def matches_any_pattern(frame: str, patterns: tuple[str, ...]) -> bool:
    """Return whether a frame matches any case-insensitive focus substring."""
    lowered = frame.lower()
    return any(pattern.lower() in lowered for pattern in patterns)


def display_name(node: dict[str, Any]) -> str:
    """Return the frame name for one processed flamegraph node."""
    return str(node.get("name") or "")


def children_of(node: dict[str, Any]) -> list[dict[str, Any]]:
    """Return child nodes while tolerating ETTrace's singleton-child variant."""
    if "children" not in node:
        raise ValueError("Processed ETTrace node is missing `children`.")

    children = node["children"]
    if isinstance(children, dict):
        return [children]

    if isinstance(children, list):
        if not all(isinstance(child, dict) for child in children):
            raise ValueError("Processed ETTrace node has a non-object child entry.")
        return children

    raise ValueError("Processed ETTrace node has invalid `children`.")


def node_weight(node: dict[str, Any]) -> float:
    """Return the inclusive `duration` stored on one ETTrace v1.1.0 node."""
    if "duration" not in node:
        raise ValueError("Processed ETTrace node is missing `duration`.")

    value = node["duration"]
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        raise ValueError("Processed ETTrace node has invalid `duration`.")

    duration = float(value)
    if not math.isfinite(duration):
        raise ValueError("Processed ETTrace node has invalid `duration`.")

    return duration


def collect_frame_weights(
    node: dict[str, Any],
    self_weights: dict[str, float],
    inclusive_weights: dict[str, float],
) -> tuple[float, float]:
    """Aggregate self and active-inclusive weights from one flamegraph subtree."""
    name = display_name(node)
    weight = node_weight(node)
    children = children_of(node)
    child_weight = 0.0
    child_active_weight = 0.0

    for child in children:
        total_child_weight, active_child_weight = collect_frame_weights(
            child,
            self_weights,
            inclusive_weights,
        )
        child_weight += total_child_weight
        child_active_weight += active_child_weight

    active_weight = child_active_weight

    if name and name != "<root>":
        self_weight = max(weight - child_weight, 0)
        if not children:
            self_weight = weight
        if self_weight > 0:
            self_weights[name] += self_weight

        if not is_unattributed(name) and not is_idle(name):
            active_weight += self_weight
            inclusive_weights[name] += active_weight

    return weight, active_weight


def thread_root_node(payload: dict[str, Any]) -> dict[str, Any] | None:
    """Return the top-level `nodes` tree from ETTrace v1.1.0 processed JSON."""
    root = payload.get("nodes")
    if isinstance(root, dict):
        return root

    return None


def parse_flamegraph(path: Path):
    """Read processed ETTrace JSON and aggregate totals used by the report."""
    with path.open(encoding="utf-8") as file:
        payload = json.load(file)

    if not isinstance(payload, dict):
        raise ValueError("Processed ETTrace JSON must be an object.")

    if "threadNodes" in payload:
        raise ValueError(
            "This looks like an intermediate or legacy ETTrace flamegraph shape with `threadNodes`. "
            "Use Homebrew ETTrace v1.1.0 output_<thread>.json with top-level `nodes`.",
        )

    if "threads" in payload and "libraryInfo" in payload:
        raise ValueError(
            "This looks like ETTrace raw capture JSON, not processed flamegraph JSON. "
            "Use the output_<thread>.json written in the directory where ettrace was run.",
        )

    thread_root = thread_root_node(payload)
    if thread_root is None:
        raise ValueError("Missing processed flamegraph nodes; this does not look like ETTrace flamegraph JSON.")

    self_weights = defaultdict(float)
    active_inclusive_weights = defaultdict(float)
    total = 0.0
    idle = 0.0
    unattributed = 0.0

    thread_summaries = []
    thread_name = path.stem
    thread_self_weights: dict[str, float] = defaultdict(float)
    thread_inclusive_weights: dict[str, float] = defaultdict(float)
    collect_frame_weights(thread_root, thread_self_weights, thread_inclusive_weights)

    thread_total = sum(thread_self_weights.values())
    thread_summaries.append((thread_total, str(thread_name)))
    total += thread_total

    for frame, weight in thread_self_weights.items():
        self_weights[frame] += weight
        if is_unattributed(frame):
            unattributed += weight
            continue

        if is_idle(frame):
            idle += weight

    for frame, weight in thread_inclusive_weights.items():
        if not is_unattributed(frame) and not is_idle(frame):
            active_inclusive_weights[frame] += weight

    return total, idle, unattributed, self_weights, active_inclusive_weights, thread_summaries


def print_top(
    title: str,
    rows: list[tuple[float, str]],
    denominator: float,
    limit: int,
    percentage_label: str,
) -> None:
    """Print a ranked table where percentages use the requested denominator."""
    print(f"\n{title}")
    for weight, frame in rows[:limit]:
        percent = weight / denominator * 100 if denominator else 0
        print(f"{weight:10.6f} {percent:7.2f}%{percentage_label} {frame}")


def main() -> None:
    """Parse arguments, summarize the flamegraph, and print ranked sections."""
    parser = argparse.ArgumentParser(
        description="Summarize ETTrace processed flamegraph JSON, excluding idle self frames from active percentages.",
    )
    parser.add_argument(
        "json",
        type=Path,
        help="Path to ETTrace v1.1.0 processed output_<thread>.json.",
    )
    parser.add_argument("--top", type=int, default=40, help="Number of rows to print per section.")
    parser.add_argument(
        "--pattern",
        action="append",
        dest="patterns",
        help=(
            "Inclusive-frame substring to include in the focused section. Can be repeated. "
            "If omitted, all inclusive frames are shown."
        ),
    )
    parser.add_argument(
        "--show-wrappers",
        action="store_true",
        help="Include app entrypoint, run loop, and other wrapper frames in inclusive output.",
    )
    args = parser.parse_args()

    try:
        total, idle, unattributed, self_weights, active_inclusive_weights, thread_summaries = parse_flamegraph(
            args.json,
        )
    except (OSError, ValueError, json.JSONDecodeError) as error:
        print(f"error: {error}", file=sys.stderr)
        raise SystemExit(1)

    active = total - idle - unattributed
    patterns = tuple(args.patterns) if args.patterns else ()

    print(f"Trace: {args.json}")
    print(f"Total duration:     {total:.6f}")
    print(f"Idle self total:    {idle:.6f}")
    print(f"Unattributed total: {unattributed:.6f}")
    print(f"Active total:       {active:.6f}")

    thread_summaries.sort(reverse=True)
    print_top("Threads", thread_summaries, total, min(args.top, len(thread_summaries)), "total")

    active_self_frames = [
        (weight, frame)
        for frame, weight in self_weights.items()
        if not is_idle(frame) and not is_unattributed(frame)
    ]
    active_self_frames.sort(reverse=True)
    print_top("Top active self frames", active_self_frames, active, args.top, "active")

    inclusive_rows = [
        (weight, frame)
        for frame, weight in active_inclusive_weights.items()
        if not patterns or matches_any_pattern(frame, patterns)
        if args.show_wrappers or not is_wrapper_frame(frame)
    ]
    inclusive_rows.sort(reverse=True)
    section_title = "Top focused inclusive frames" if patterns else "Top inclusive frames"
    print_top(section_title, inclusive_rows, active, args.top, "active")


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat >&2 <<'USAGE'
Usage: collect_ios_dsyms.sh --app App.app --out-dir DIR [options]

Collects UUID-matched dSYMs for a built iOS simulator app into DIR.

Required:
  --app PATH                 Built .app bundle
  --out-dir DIR              Destination dSYM directory

Optional:
  --search-root DIR          Directory to search for .dSYM bundles (repeatable)
  --extra-dsym DIR           Known .dSYM bundle to include in candidates (repeatable)
  --require-framework NAME   Require a matching dSYM for an embedded framework
  --require-all-frameworks   Require matching dSYMs for every embedded framework

Example:
  collect_ios_dsyms.sh --app build/Debug-iphonesimulator/MyApp.app \
    --out-dir /tmp/profile/dsyms \
    --search-root build \
    --search-root ~/Library/Developer/Xcode/DerivedData
USAGE
}

require_value() {
  local flag="$1"
  local value="${2:-}"
  if [[ -z "$value" ]]; then
    echo "$flag requires a value" >&2
    usage
    exit 2
  fi
}

app_path=""
out_dir=""
require_all_frameworks=false
search_roots=()
extra_dsyms=()
required_frameworks=()

while [[ $# -gt 0 ]]; do
  case "$1" in
    --app)
      require_value "$1" "${2:-}"
      app_path="$2"
      shift 2
      ;;
    --out-dir)
      require_value "$1" "${2:-}"
      out_dir="$2"
      shift 2
      ;;
    --search-root)
      require_value "$1" "${2:-}"
      search_roots+=("$2")
      shift 2
      ;;
    --extra-dsym)
      require_value "$1" "${2:-}"
      extra_dsyms+=("$2")
      shift 2
      ;;
    --require-framework)
      require_value "$1" "${2:-}"
      required_frameworks+=("$2")
      shift 2
      ;;
    --require-all-frameworks)
      require_all_frameworks=true
      shift
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      echo "Unknown argument: $1" >&2
      usage
      exit 2
      ;;
  esac
done

if [[ -z "$app_path" || -z "$out_dir" ]]; then
  usage
  exit 2
fi

if [[ ! -d "$app_path" ]]; then
  echo "error: app bundle not found: $app_path" >&2
  exit 1
fi

app_path="$(cd "$(dirname "$app_path")" && pwd)/$(basename "$app_path")"
mkdir -p "$out_dir"
out_dir="$(cd "$out_dir" && pwd)"
candidates_file="$out_dir/dsym-candidates.txt"

if [[ -f "$app_path/Info.plist" ]]; then
  executable="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' "$app_path/Info.plist")"
else
  executable="$(basename "$app_path" .app)"
fi

app_binary="$app_path/$executable"
if [[ ! -f "$app_binary" ]]; then
  echo "error: app executable not found: $app_binary" >&2
  exit 1
fi

default_roots=(
  "$(dirname "$app_path")"
  "$PWD"
  "$PWD/build"
  "$PWD/bazel-bin"
  "$PWD/bazel-out"
)

for root in "${default_roots[@]}"; do
  if [[ -d "$root" ]]; then
    search_roots+=("$root")
  fi
done

if [[ -d "$HOME/Library/Developer/Xcode/DerivedData" ]]; then
  search_roots+=("$HOME/Library/Developer/Xcode/DerivedData")
fi

: > "$candidates_file"
if [[ ${#search_roots[@]} -gt 0 ]]; then
  find -L "${search_roots[@]}" -type d -name "*.dSYM" -prune -print 2>/dev/null >> "$candidates_file" || true
fi

if [[ ${#extra_dsyms[@]} -gt 0 ]]; then
  for dsym in "${extra_dsyms[@]}"; do
    if [[ -d "$dsym" ]]; then
      printf '%s\n' "$dsym" >> "$candidates_file"
    fi
  done
fi

awk '!seen[$0]++' "$candidates_file" > "$candidates_file.tmp"
mv "$candidates_file.tmp" "$candidates_file"

if [[ ! -s "$candidates_file" ]]; then
  echo "error: no dSYM candidates found. Add --search-root pointing at build output or DerivedData." >&2
  exit 1
fi

contains_required_framework() {
  local framework_name="$1"
  if [[ ${#required_frameworks[@]} -eq 0 ]]; then
    return 1
  fi

  for required in "${required_frameworks[@]}"; do
    if [[ "$required" == "$framework_name" || "$required" == "${framework_name%.framework}" ]]; then
      return 0
    fi
  done
  return 1
}

copy_matching_dsym() {
  local binary="$1"
  local label="$2"
  local required="$3"

  if [[ ! -f "$binary" ]]; then
    return 0
  fi

  local binary_uuids=()
  while IFS= read -r uuid; do
    [[ -n "$uuid" ]] && binary_uuids+=("$uuid")
  done < <(dwarfdump --uuid "$binary" 2>/dev/null | awk '{ print $2 }')

  if [[ ${#binary_uuids[@]} -eq 0 ]]; then
    if [[ "$required" == "required" ]]; then
      echo "error: could not read UUID for required $label: $binary" >&2
      return 1
    fi

    echo "warning: could not read UUID for $label: $binary" >&2
    return 0
  fi

  local match=""
  local candidate_uuids=""
  local has_all_uuids=""
  while IFS= read -r candidate; do
    candidate_uuids="$(dwarfdump --uuid "$candidate" 2>/dev/null | awk '{ print $2 }' || true)"
    if [[ -z "$candidate_uuids" ]]; then
      continue
    fi
    has_all_uuids=true
    for uuid in "${binary_uuids[@]}"; do
      if ! grep -Fxq "$uuid" <<< "$candidate_uuids"; then
        has_all_uuids=false
        break
      fi
    done

    if [[ "$has_all_uuids" == "true" ]]; then
      match="$candidate"
      break
    fi
  done < "$candidates_file"

  if [[ -z "$match" ]]; then
    if [[ "$required" == "required" ]]; then
      echo "error: missing required dSYM for $label UUIDs ${binary_uuids[*]}" >&2
      return 1
    fi

    echo "warning: missing dSYM for $label UUIDs ${binary_uuids[*]}" >&2
    return 0
  fi

  local dest="$out_dir/$(basename "$match")"
  rm -rf "$dest"
  cp -R "$match" "$dest"
  printf 'matched %s UUIDs %s -> %s\n' "$label" "${binary_uuids[*]}" "$dest"
}

copy_matching_dsym "$app_binary" "$executable.app" required

if [[ -d "$app_path/Frameworks" ]]; then
  for framework in "$app_path"/Frameworks/*.framework; do
    [[ -d "$framework" ]] || continue

    framework_name="$(basename "$framework")"
    framework_binary="$framework/${framework_name%.framework}"
    required="optional"

    if [[ "$require_all_frameworks" == "true" ]] || contains_required_framework "$framework_name"; then
      required="required"
    fi

    copy_matching_dsym "$framework_binary" "$framework_name" "$required"
  done
fi

cat <<EOF
DSYMS=$out_dir

Use:
  ettrace --simulator --launch --dsyms "$out_dir"
EOF