Performance Profiling & Optimization

# Performance Profiling & Optimization


Systematically find performance bottlenecks and fix them. Never guess — measure first, optimize second, measure again.


## Table of Contents

- [When to Use](#when-to-use)
- [Triggers](#triggers)
- [Methodology](#methodology)
- [Dos](#dos)
- [Don'ts](#don'ts)
- [Pitfalls](#pitfalls)
- [Cross-Skill Hints](#cross-skill-hints)

## When to Use

Use when code is slow, uses too much memory, has high latency, or needs to handle more load. NOT for premature optimization ("this might be slow so let's optimize it") — always profile first.

## Triggers

"slow", "performance", "optimize", "latency", "bottleneck", "too slow", "timeout", "memory usage", "high CPU", "response time", "scalability", "slow query", "profiling", "benchmark", "N+1", "production collapse", "only works on small data"

## Methodology

### Phase 1: Measure Before You Optimize

Never optimize based on intuition. Intuition is wrong 80% of the time. JetBrains research (2026) showed that AI agents with no profiler access score 1–2/10 on bottleneck-finding tasks; with profiling they score 9–10/10.

1. **Identify the right metric**: response time? CPU usage? Memory? IO? Throughput? Pick one primary metric to improve.
2. **Establish baseline**: measure current performance before any changes. Run 3+ times, report median, and record the environment/conditions.
3. **Find the bottleneck**: profile to find where time/memory is actually spent. Do not guess.

**Profiling tools by language:**
- Python: `cProfile` / `py-spy` (CPU), `memory_profiler` / `tracemalloc` (memory), `time.perf_counter()` (timing specific blocks), `scalene` (line-by-line CPU+GPU+memory)
- Node.js: built-in `--prof` flag, Chrome DevTools inspector, `clinic` (bubbleprof, flame, doctor), `0x` (flamegraphs)
- Go: `pprof` built-in (CPU, heap, goroutine, mutex), `benchmark` package
- Rust: `perf`, `flamegraph-rs`, `criterion` (benchmarking), `pprof-rs`
- Java: JVisualVM, JMC (Java Mission Control), Async Profiler, JMH (microbenchmarking)
- Database: `EXPLAIN ANALYZE`, slow query logs, `pg_stat_statements`, `pgBadger`, `pt-query-digest` (MySQL)
- General/Continuous Profiling: Pyroscope / Grafana Phlare (always-on production profiling), `perf` (Linux), `DTrace` (BSD/macOS)

### Phase 2: Understand Latency Scales (What to Actually Care About)

Before profiling, internalize the orders of magnitude. Optimizing a function that runs in 1ms when the real bottleneck is a 200ms database query is wasted effort.

| Cost | Operation | What It Means |
|---|---|---|
| ~0.5 ns | L1 cache hit | Fastest thing a CPU does |