perf-profiling

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Performance Profiling

Rule 0: Don't optimize what you haven't measured. Almost all "obvious" optimizations are wrong.

---

The Protocol

Step 1 — Define "fast enough"

Performance is relative. Before optimizing:

• Current metric (p50, p95, p99 latency / MB memory / % CPU)
• Target metric (what's the SLO/SLA/user expectation?)
• Gap — what needs to close

If no target → ask the user. Don't optimize without a goal — you'll polish forever.

Step 2 — Measure baseline

Use the appropriate profiler:

Language	Profiler
Node.js	node --prof, clinic.js, 0x
Browser JS	Chrome DevTools Performance tab
Python	cProfile, py-spy, memory_profiler
Go	pprof (built-in)
Rust	cargo flamegraph, perf
CLI	hyperfine
HTTP	wrk, k6, vegeta

Run the profiler under realistic load, not trivial input. Capture for 30–60s minimum — short captures miss long-tail events.

Step 3 — Analyze (flamegraph / top consumers)

Identify the top 3 functions by:

• Self time (function's own CPU, excluding descendants)
• Total time (self + descendants)
• Call count (high-frequency cold functions add up)

Pareto check: Is there a clear 80/20?

• Top function takes 50%+ of time → that's your target
• Time spread evenly across 100 functions → hard to optimize; likely needs architectural change

Step 4 — Form optimization hypothesis

For the bottleneck:

• What's it doing? (read the code)
• Why is it slow? (algorithm, I/O, allocations, lock contention, cache miss)
• What's a realistic improvement target?

Common bottleneck classes + fixes:

Bottleneck	Fix
O(n²) on large n	Change to O(n log n) or O(n)
Sync I/O in hot path	Async, batch, or remove the I/O
Allocations in loop	Pre-allocate, object pool, reuse
Redundant computation	Memoize, cache result
Lock contention	Lock-free structure, sharding, immutable data
Large object serialization	Streaming, lazy fields, columnar format
Database N+1	Join, prefetch, dataloader pattern
Cold cache / page fault	Warm up, prefetch, locality