Pack Profilage et Optimisation de Performance

What's in this pack

This is the rig for the engineer who just got pinged: "the /search endpoint is taking 8 seconds, can you look?" — or "the dashboard freezes for 2 seconds when I open it." Ten picks, each with a clear role in a five-step loop: baseline → profile → diagnose → fix → regression-test.

Every tool here is open-source or has a free tier that covers the loop. No "contact sales," no SaaS-only telemetry. The AI agents (Performance Profiler, GraphQL Performance Optimizer, Postgres MCP Pro) read the actual profile output — they don't pattern-match on your code and hallucinate "add an index here."

Install in this order

1. Claude Code Agent: Performance Profiler — the orchestrator. Install first because it's the agent you'll point at flamegraphs and traces. It knows the difference between a CPU profile, an off-CPU profile, and a wall-clock profile, and won't suggest "add caching" when the bottleneck is GC pauses.
2. Lighthouse — frontend baseline. Run lighthouse https://your.url --output html before touching anything. Save the report. Every later change gets a re-run for diff. This is your frontend before-picture.
3. Size Limit — JS bundle perf budget. Wire it into CI on day one. Once you set size-limit: [{ path: 'dist/*.js', limit: '200 KB' }], every PR that bloats the bundle gets blocked before merge. Cheapest performance win in the stack.
4. FlameGraph — Brendan Gregg's perl/SVG flamegraph generator. The actual file format the rest of the ecosystem speaks. Install once, every other profiler in this pack can pipe into it: perf script | stackcollapse-perf.pl | flamegraph.pl > out.svg.
5. async-profiler — low-overhead JVM sampling profiler. For Java/Kotlin/Scala services. ~1% overhead in production, emits collapsed-stack format that pipes straight into FlameGraph. Captures CPU, allocation, lock contention, and wall-clock in one tool.
6. BCC (BPF Compiler Collection) — eBPF tracing for Linux. Reach for this when the bottleneck is below your runtime — syscalls, disk I/O, network, page faults. biolatency, tcpretrans, funccount are the three commands you'll use first.
7. Grafana Pyroscope — continuous profiling backend. Once you've fixed one slow endpoint, install Pyroscope so the next regression shows up as a flamegraph diff in a dashboard, not a Slack message at 11pm. Pairs with FlameGraph format natively.
8. Postgres MCP Pro — index tuning + safe SQL MCP. For "the query is slow" — point this MCP at your Postgres, ask the agent to explain a query plan, and it returns a real EXPLAIN ANALYZE plus index suggestions the agent itself validated by running EXPLAIN again. Not a hallucination.
9. Claude Code Agent: GraphQL Performance Optimizer — for the N+1 query problem that every GraphQL gateway eventually hits. Reads your resolvers, finds the unbatched DB calls, suggests DataLoader patterns specific to your schema.
10. k6 — JavaScript-scripted load testing. The regression net. After every fix, run the same k6 script against staging and compare p50/p95/p99. If you can't reproduce the slowdown with a k6 script, you can't prove the fix.

How they fit together

┌─ BASELINE ─────────────────────────┐
│ Lighthouse (frontend)              │
│ k6 (backend p50/p95/p99)           │
│ Size Limit (bundle budget in CI)   │
└─────────────┬──────────────────────┘
              │ "it's slow — but where?"
              ▼
┌─ PROFILE ──────────────────────────┐
│ async-profiler (JVM)               │
│ BCC / eBPF (syscalls, I/O)         │
│ Pyroscope (continuous, in prod)    │
│ → all emit FlameGraph format       │
└─────────────┬──────────────────────┘
              │ flamegraph.svg
              ▼
┌─ DIAGNOSE (agent reads profile) ───┐
│ Performance Profiler agent         │
│ Postgres MCP Pro (query plans)     │
│ GraphQL Performance Optimizer      │
└─────────────┬──────────────────────┘
              │ "hot path is X, fix is Y"
              ▼
        FIX ONE HOT PATH
              │
              ▼
┌─ REGRESSION TEST ──────────────────┐
│ k6 (rerun same script, diff p95)   │
│ Lighthouse (rerun, diff scores)    │
│ Pyroscope (flamegraph diff)        │
└────────────────────────────────────┘

The loop is non-negotiable. Skipping baseline means you can't prove the fix. Skipping the flamegraph means you're guessing — and the LLM is guessing harder. Skipping regression means the next deploy un-fixes it silently.

Tradeoffs you'll hit

• Pyroscope vs ad-hoc async-profiler runs — Pyroscope is continuous (always-on, low overhead, costs storage). async-profiler is on-demand (run it for 60 seconds when you suspect something, zero idle cost). Start with async-profiler; install Pyroscope only after you've fixed two regressions and want the third to be obvious from a dashboard.
• BCC vs perf — BCC is higher-level and writes scripts in Python (readable). perf is the kernel's own profiler, lower level, slightly more universal. BCC is the friendlier on-ramp; reach for raw perf when you need a specific event source BCC doesn't expose.
• Lighthouse local vs LH-CI — local Lighthouse is one-shot. Lighthouse-CI runs it on every PR and stores the trend. If you're past the first fix, install LH-CI; otherwise local is fine.
• Size Limit vs Bundlephobia/Webpack Bundle Analyzer — Size Limit blocks CI on regression (proactive). Analyzers just show you the bundle (reactive). Both are useful; Size Limit is the one that prevents the next 50 KB of accidental bloat.
• k6 vs Artillery vs Locust — k6 wins on script ergonomics (real JavaScript, not YAML), built-in p95/p99 reporting, and Grafana integration. Pick Artillery if your team is YAML-first; pick Locust if your team is Python-first.

Common pitfalls

• Profiling in dev, fixing for prod — your laptop's CPU is faster, the dataset is smaller, and the JVM is in interpreter mode. Always profile in an environment that mirrors prod load. Pyroscope-in-prod beats async-profiler-on-laptop every time.
• Reading a flamegraph as a call tree — flamegraphs are sampled stacks. Width = CPU time, not call count. A wide block doesn't mean "called a lot," it means "spent a lot of CPU there."
• Asking an LLM to optimize without showing it the profile — every "optimize this code" prompt without the actual measurement returns generic advice ("add memoization," "use a Set"). Show the agent the flamegraph or the EXPLAIN ANALYZE. That's why the Performance Profiler agent and Postgres MCP Pro exist.
• Fixing the cold path — 80% of "optimizations" target code that runs 0.1% of the time. Always confirm the function you're rewriting is actually in the top 5 of the flamegraph.
• No regression test after the fix — if you can't replay the slow path with a k6 script (or a SQL repro), you'll re-introduce the regression on the next refactor and not notice for two weeks.