platform-profilers

name	platform-profilers
description	Catalog of Xcode Instruments templates, Android Studio Profiler modules, and Perfetto — what to pick for CPU, memory, GPU, network, energy, and startup work.

Platform Profilers

Instructions

Picking the wrong profiler wastes hours. This is a cheat sheet: which tool for which question, and how to open it with the right settings the first time.

1. Xcode Instruments Templates

Open with Product → Profile (Cmd+I), then pick a template.

Template	Best for	Key tracks
Time Profiler	CPU hot spots, main-thread blocks	Call tree (invert & filter by thread)
Allocations	Persistent memory growth, generations	Mark Generation, Statistics
Leaks	Reference cycles (ARC)	Cycles & Roots, Call Tree
System Trace	Threads scheduling, locks, VM faults	Threads, Virtual Memory
App Launch	Cold start phase breakdown	Phases, signposts
Energy Log	Battery attribution	Energy Usage, CPU, Network, Location
Network	URLSession task metrics	HTTP connections, TLS, bytes
Core Animation	FPS, off-screen rendering	Core Animation FPS, dropped frames
Metal System Trace	GPU work, shader pipelines	Metal encoder timelines
SwiftUI	Per-body evaluation cost	View Body / Expensive Operations
Hangs	Main-thread hangs > 250 ms	Hangs track, root cause stacks
Points of Interest	Your own os_signpost events	POI track aligned to other tracks

Pro tips:

• Combine Time Profiler + Core Animation for "why are frames dropping" analysis.
• XCTests can attach Instruments templates via schemes → Profile action.
• Save ticket-ready recordings with File → Save As Template for the team.

2. Android Studio Profiler Modules

View → Tool Windows → Profiler (API 26+ device, debuggable build, but prefer profile/release with profileable).

Row	What it answers
CPU	Where is main thread spending time? Sampled/Instrumented
Memory	Java/Native/Graphics/Code usage; heap dumps; allocations
Network	Requests, bytes, connections (OkHttp/HttpURLConnection)
Energy	Battery cost (API 26+)

Recordings:

• Sample Java/Kotlin Methods — low overhead; picks a sample every ~1ms.
• Trace Java/Kotlin Methods — exact but much higher overhead.
• Sample Native (C/C++) — needs symbolicated NDK libs.
• System Trace (Perfetto) — use this for render/thread analysis — same data as Perfetto UI.

Manifest: make the release build profileable without sacrificing R8:

<application>
    <profileable android:shell="true" />
</application>

3. Perfetto

Perfetto is the lingua franca. It opens:

• Android systraces (.pftrace, .perfetto-trace).
• Chrome / RN JS-engine traces (.json).
• ftrace captures.
• SQL queries over the trace for large analyses.

Capture on-device:

adb shell perfetto -o /data/misc/perfetto-traces/trace.pftrace -t 10s `
  sched freq idle am wm gfx view binder_driver hal dalvik input res memory `
  "com.example.app" --txt -c - << 'EOF'
buffers { size_kb: 63488 fill_policy: DISCARD }
data_sources { config { name: "linux.ftrace" ftrace_config { ftrace_events: "sched_switch" } } }
EOF

Or use the record_android_trace script from the Perfetto repo.

Open in ui.perfetto.dev. Useful queries:

-- top 20 slices by duration
select name, dur/1e6 as ms from slice order by dur desc limit 20;

-- main-thread blocks over 100ms
select ts, name, dur/1e6 as ms from slice
 where thread_name = 'main' and dur > 100e6
 order by dur desc;

4. Which Profiler for Which Question

Question	First tool
Why is startup slow?	iOS: App Launch. Android: Macrobenchmark + Perfetto.
Why is a scroll janky?	Perfetto (Android), Core Animation + Time Profiler (iOS)
Why does memory keep growing?	Allocations (iOS), Profiler Memory + LeakCanary (Android)
Why is battery dying?	Energy Log (iOS), Battery Historian (Android)
Why are my images slow?	Time Profiler + Core Animation (iOS), Profiler CPU + GPU inspector (Android)
Why is my WebSocket chatty?	Network (both)
Why is a Compose screen recomposing a lot?	Layout Inspector (Compose), Profiler CPU System Trace
Why is a SwiftUI body expensive?	SwiftUI template → View Body

5. Trace Hygiene

• Annotate the app with signposts / androidx.tracing / Timeline events named for the feature.
• Capture two traces: good run and bad run, same device, same conditions.
• Save the trace in the bug report. Future-you needs it.

Checklist

• Team knows which Instruments template answers which question.
• Release/profile builds are profileable on Android.
• Signposts / trace sections added to label feature code.
• Perfetto captures shared in issues; not just screenshots.
• Profiler artefacts archived alongside PRs that fix perf bugs.