perf-triage

Perf triage (browser runtime, CDP profiling)

Diagnose a runtime perf problem from a real profile, fix it with measurement discipline, and prove the win. Source-reading produces plausible-but-wrong theories; the profile names the actual cost.

Non-negotiables

• Reproduce and measure before proposing any fix. No baseline profile, no diagnosis.
• Pick the metric by symptom (see the metric table). The wrong metric leads to the wrong fix.
• Measure every change against a clean before/after profile. Revert anything that does not measurably help — even changes that "should" work. Plausible is not measured.
• Verify correctness, not just speed. A faster wrong render is still wrong.

Phase 1 — Get a running, reproducing target

1. Ask the user three things you cannot infer: which URL/surface reproduces it, the exact interaction that triggers it (the control to click), and whether it is a recent regression (bisect) or longstanding (cold profile).
2. Launch a CDP-enabled Chrome yourself. It must be a separate instance with its own profile dir, so it works even while the user's normal Chrome is running:

   open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-perf-profile" "<APP_URL>"
   

   Confirm the port is live: curl -s http://localhost:9222/json/version.
3. The fresh profile is not logged in. Ask the user to log in in that window and land on the pre-interaction state, then say "ready". You must not enter credentials yourself. Confirm the loaded tab: curl -s http://localhost:9222/json (look for the app URL, not /login).

The login persists in that profile dir, so subsequent captures skip it.

Phase 2 — Capture a CPU profile over CDP (not the DevTools panel)

The DevTools Performance panel and the chrome-devtools MCP stop_trace both choke on big traces (a 20s, 100%-CPU, dev build produces 200MB+; DevTools crashes rendering the flame chart). Capture over CDP Profiler to a compact .cpuprofile (JS sampling) instead — nothing renders it, so nothing crashes.

• Use scripts/capture-cpuprofile.js. It connects to :9222, reloads to pick up recompiled code, drives the interaction over CDP itself (clicks the trigger button by text — deterministic, no reliance on user click timing), records, and saves.

  node scripts/capture-cpuprofile.js --url "<APP_URL>" --trigger "<button text that triggers it>" --reset "<tab to return to first>" --seconds 22 --out baseline.cpuprofile
  

• Capture short windows. The pathological work repeats, so 15-25s covers it and keeps the file small.
• If you need task boundaries (for a freeze / longest-task), capture a full trace via CDP Tracing with transferMode: ReturnAsStream instead — the .cpuprofile has samples but not RunTask events.

Phase 3 — Analyze offline

• Parse with scripts/parse-cpuprofile.js <file>: total duration, idle %, active CPU, per-function self-time and inclusive time, and active-CPU-per-second (the spike shape / duration).
• Map hot minified frames to real source: rg -n "function <symbol>|const <symbol>" <pkg>/src, then read the source to confirm the mechanism.
• Route heavy reads to a subagent; keep summaries in the main thread.

Metric by symptom

Symptom	Measure	Goal
Freeze / unresponsive	longest task, total blocking time (task-time over 50ms)	no task > ~50ms
Sustained 100% CPU, UI still responsive	total active CPU, idle %, per-function self-time	less total work
Janky animation / scroll	long tasks during the interaction	fewer/shorter tasks

Do not optimize a count (timers, renders) unless the profile shows it is the cost.

Phase 4 — Diagnose the root cause

Trace the symptom to a mechanism. Common shapes:

• Accidental O(N²): each of N items touches the whole N-collection (e.g. per-item rebuild of a structure containing all items). Hides until N is large; multiplied by an event storm it dominates.
• Event/notification storm: fan-out + one-timer-per-event produces duplicate work for the same target. Look for a hot id notified many times.
• Expensive reuse guard: a cache check that deep-compares more than the rebuild costs, then rebuilds anyway.
• Per-item recompute that should be shared or scoped.

Phase 5 — Fix with measurement discipline

• Smallest behavior-preserving change first. Prefer:
  • Dedupe over coalesce-into-one-task. Collapsing a burst into a single synchronous task freezes the thread — the per-event yield points were keeping tasks small. Dedupe by key; keep one unit of work per unique key.
  • Reference/version checks over deep compares for immutably-updated state (a new reference already proves the change).
  • A guard must be cheaper than the work it guards.
• After each change: re-capture, compare active CPU / longest task against baseline, run the unit tests. Keep only what measurably helps; revert the rest.
• Verify in the browser: correct render (DOM/values), and both interaction directions (e.g. A→B and B→A), not just one.
• Note dev vs prod: React StrictMode double-invokes effects and dev builds log warnings — dev numbers overstate prod. Compare like-for-like.

Decision lessons (the diverge-to-correct moments)

These are real wrong-turns from triage. Expect to make some; revert fast.

Tried	Why it failed	Correct move
Coalesce all notifications into one flush	Concentrated the burst into one multi-second synchronous task → hard freeze	Dedupe by id; keep one timer per unique id (work stays spread)
Share one cache across all consumers	Consumers had a per-instance dependency; sharing didn't apply and the gate check was itself O(N)	Verify the shared computation is truly instance-independent before sharing; a fast path that is O(N) is not fast
Memoize by object reference	The reference churned every event in the hot path, so the cache always missed	Confirm the key is stable in the hot path before relying on reference memoization
Optimize "timer/notification count"	Irrelevant to a freeze (which is about task length)	Match the metric to the symptom first

Tooling

• scripts/capture-cpuprofile.js — CDP capture to .cpuprofile, drives the interaction itself.
• scripts/parse-cpuprofile.js — offline analysis (idle %, active CPU, self/inclusive time, spike shape).

Both are generic (parameterized by URL, click targets, duration, port). Commit a copy next to the investigation when the work outlives the session.