Performance Profiling

---
name: performance-profiling
description: Find and fix performance bottlenecks with measurement. Use when the user reports slowness, high latency, memory growth, or asks to optimize.
---

# Performance Profiling

Measure first. Optimizing without a profile is guessing, and the guess is usually wrong.

## Establish the baseline

1. Define the metric that matters: p95 latency, time-to-interactive, memory ceiling, query time.
2. Measure it before touching anything:
   - HTTP: `curl -o /dev/null -s -w 'total: %{time_total}s\n' <url>`
   - Script: `time <command>`
   - Node: `node --cpu-prof app.js` or `node --inspect` + Chrome DevTools
   - Frontend: Lighthouse / performance panel trace
3. Record the number. Every later claim is relative to it.

## Find the bottleneck

- **Backend:** which layer — DB, network calls, CPU, serialization? Add timing around each; check slow query logs; look for N+1 (a query inside a loop).
- **Frontend:** long tasks, re-render storms (React DevTools profiler), bundle size (`npx vite-bundle-visualizer` or webpack analyzer), unmemoized expensive computation.
- **Memory:** growth over time = leak. Heap snapshots before/after the suspected action.

## Optimize

1. Fix the single largest contributor first. A 50% win on the top item beats 5% on ten items.
2. Prefer algorithmic fixes (caching, indexing, batching, pagination) over micro-tweaks.
3. State the tradeoff of each change: memory vs latency, freshness vs cache hits, complexity vs speed.

## Verify

- Re-run the exact baseline measurement. Report before → after with the same method and load.
- Confirm correctness: run the test suite — fast and wrong is worse than slow.
- If you cannot measure an improvement, revert the change.