performance-optimization

Use a sampling profiler like py-spy for production processes with 1-5% overhead, or cProfile locally for exact call counts. Read the resulting flame graph by width, not depth: the widest plateau is your optimization target.

Sampling profilers like py-spy periodically snapshot the stack with minimal overhead, suiting production use. Deterministic profilers like cProfile record every call exactly but slow execution 2-10x, making them better for local analysis of known hot functions.

Averages hide tail behavior: a 60 ms mean is consistent with 1% of requests taking 2.5 seconds. In fan-out systems making 100 backend calls, a p99 event becomes a 63% page-level event, so users experience the tail, not the mean.

Cache only after profiling confirms the hot path, when reads greatly outnumber writes, computation is expensive, and staleness is tolerable. Always measure the hit rate; a 40% hit rate can be worse than no cache once latency and invalidation bugs are counted.

Amdahl's Law bounds total speedup by the optimized component's share of runtime: a 10x faster component that uses 5% of total time yields only 1.05x overall. Re-profile after each fix, since the ranking of contributors changes once the top one is removed.