performance-profiling

name	performance-profiling
description	Profile and optimize application performance. Use when asked to improve speed, reduce latency, fix memory leaks, find bottlenecks, or optimize a slow function or endpoint.
license	MIT
compatibility	Requires python 3.10+ or node 18+

Overview

You do not optimize what you have not measured. Every performance investigation starts with a profiler, not a hypothesis.

Process

1. Establish a baseline. Before changing anything, measure the current performance:

   • For a function: time it with actual production-representative data
   • For an endpoint: measure p50, p95, p99 latency under realistic load
   • For memory: record heap size at start, peak, and end of operation

   import cProfile, pstats, io
   
   pr = cProfile.Profile()
   pr.enable()
   result = slow_function(data)
   pr.disable()
   
   s = io.StringIO()
   ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
   ps.print_stats(20)  # Top 20 by cumulative time
   print(s.getvalue())
   

2. Read the profiler output. Identify the top 3 functions by cumulative time. Do not optimize anything that is NOT in the top 3 — this is Amdahl's Law in practice.

3. Form ONE hypothesis for why the top bottleneck is slow. Common causes, in order of frequency:

   • N+1 query (calling the database once per item in a loop)
   • Missing index on a frequently queried column
   • Serialization of large objects in a hot path
   • Synchronous I/O blocking an async event loop
   • Unnecessary repeated computation (missing cache)

4. Apply ONE change. The smallest possible change that addresses the hypothesis. Do not refactor the entire module.

5. Measure again. Compare against the baseline. Report the improvement as a percentage.

6. Repeat. If there is still a performance gap, return to step 2 with the updated profile.

Common Patterns

N+1 query fix:

# Before: queries once per user
for user in users:
    user.orders = db.query(f"SELECT * FROM orders WHERE user_id={user.id}")

# After: one query for all users
user_ids = [u.id for u in users]
orders = db.query("SELECT * FROM orders WHERE user_id = ANY(%s)", [user_ids])
orders_by_user = defaultdict(list)
for o in orders: orders_by_user[o.user_id].append(o)
for user in users: user.orders = orders_by_user[user.id]

Caching a pure function:

from functools import lru_cache

@lru_cache(maxsize=512)
def expensive_computation(input_id: int) -> dict:
    ...

Rationalizations

Excuse	Rebuttal
"I know what the bottleneck is without profiling"	You don't. Everyone thinks they know. Profile first, always.
"Let me optimize the whole module while I'm here"	Scope creep disguised as diligence. Fix the top bottleneck, measure, then decide if more work is needed.
"It's fast enough on my machine"	Production data is 100x larger. Profile with production-scale data.

Verification

• Baseline performance was measured before any change
• Profiler output was read (not guessed)
• Only the top bottleneck was targeted
• Performance was measured after the change and improvement percentage was reported