Performance & Optimization

┌─────────────────────────────────────────────────────────┐
│                    Client                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │              Browser Cache                      │   │
│  │         (Static assets, API responses)          │   │
│  └─────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────┼────────────────────────────────┐
│                        ▼                                │
│  ┌─────────────────────────────────────────────────┐   │
│  │                   CDN                           │   │
│  │      (Edge caching, global distribution)        │   │
│  └─────────────────────────────────────────────────┘   │
│                        │                                │
│                        ▼                                │
│  ┌─────────────────────────────────────────────────┐   │
│  │            Application Cache                    │   │
│  │         (Redis, Memcached - in-memory)          │   │
│  └─────────────────────────────────────────────────┘   │
│                        │                                │
│                        ▼                                │
│  ┌─────────────────────────────────────────────────┐   │
│  │               Database                          │   │
│  │      (Query cache, buffer pool)                 │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

# Cache-Aside (Lazy Loading) -- the most common pattern.
# Application manages the cache explicitly. Simple but the application
# bears full responsibility for cache consistency.
def get_user(user_id):
    # 1. Check cache first -- fast path, ~1ms
    cached = redis.get(f"user:{user_id}")
    if cached:
        return json.loads(cached)  # Cache hit -- serve from memory
    
    # 2. Cache miss -- fetch from DB (~10-100ms)
    user = db.query("SELECT * FROM users WHERE id = ?", user_id)
    
    # 3. Store in cache with TTL for next time.
    # TTL is your safety net: even if invalidation fails, stale data
    # expires automatically. Choose TTL based on acceptable staleness.
    redis.setex(f"user:{user_id}", 3600, json.dumps(user))  # 1 hour TTL
    
    return user

# Write-Through -- update DB and cache atomically.
# Guarantees cache is always fresh for reads, but adds latency to writes
# (must wait for both DB and cache writes before returning).
def update_user(user_id, data):
    # 1. Update database (source of truth)
    db.update("UPDATE users SET ... WHERE id = ?", data, user_id)
    
    # 2. Update cache immediately -- no stale reads after this point
    redis.setex(f"user:{user_id}", 3600, json.dumps(data))

# Cache Invalidation -- delete from cache, let next read repopulate.
# Simpler than write-through; avoids caching data that may never be read again.
def delete_user(user_id):
    db.delete("DELETE FROM users WHERE id = ?", user_id)
    redis.delete(f"user:{user_id}")  # Next read triggers fresh cache-aside load

-- ❌ Slow: Full table scan -- YEAR() wraps the column in a function,
-- preventing the database from using an index on created_at.
-- The DB must read EVERY row and compute YEAR() on each one.
SELECT * FROM orders WHERE YEAR(created_at) = 2024;

-- ✅ Fast: Use index-friendly range query -- the database can use a
-- B-tree index on created_at to jump directly to the right range.
-- This can be 1000x faster on large tables.
SELECT * FROM orders 
WHERE created_at >= '2024-01-01' 
  AND created_at < '2025-01-01';

-- ❌ Slow: SELECT * fetches all columns, including that 5MB BLOB
-- column you forgot was there. Wastes network bandwidth and memory.
SELECT * FROM users WHERE id = 1;

-- ✅ Fast: Select only the columns you actually use in your code.
-- Bonus: a covering index can serve this entirely from the index
-- without touching the table at all.
SELECT id, name, email FROM users WHERE id = 1;

-- EXPLAIN ANALYZE is your best friend for query optimization.
-- It shows the actual execution plan AND timing for each step.
-- Look for: Seq Scan (missing index), high row estimates, Sort on disk.
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 123;

-- Single column index
CREATE INDEX idx_users_email ON users(email);

-- Composite index (order matters!)
CREATE INDEX idx_orders_user_status ON orders(user_id, status);
-- This index helps: WHERE user_id = 1 AND status = 'pending'
-- Also helps: WHERE user_id = 1
-- Does NOT help: WHERE status = 'pending'

-- Covering index (includes all needed columns)
CREATE INDEX idx_users_covering ON users(email) INCLUDE (name, created_at);

# ❌ Bad: New connection per request -- 20-50ms overhead EVERY time.
# At 1,000 RPS, you are spending 20-50 seconds/second just on handshakes.
# Also risks exhausting the database's max_connections limit.
def get_user(user_id):
    conn = psycopg2.connect(...)  # TCP + TLS + auth = ~30ms wasted
    result = conn.execute(query)
    conn.close()                  # Connection discarded, next request starts from scratch
    return result

# ✅ Good: Connection pool -- connections are created once, reused thousands of times.
# Borrowing a connection from the pool takes ~0.1ms instead of ~30ms.
from sqlalchemy import create_engine

engine = create_engine(
    DATABASE_URL,
    pool_size=20,        # Keep 20 connections warm and ready
    max_overflow=10,     # Allow up to 30 total under burst load
    pool_timeout=30      # Wait up to 30s for a connection before raising an error
)

Vertical Scaling (Scale Up)     Horizontal Scaling (Scale Out)
┌─────────────────────┐         ┌──────┐ ┌──────┐ ┌──────┐
│                     │         │Server│ │Server│ │Server│
│    Bigger Server    │         │  1   │ │  2   │ │  3   │
│                     │         └──────┘ └──────┘ └──────┘
│  More CPU, RAM      │              │       │       │
│                     │              └───────┼───────┘
└─────────────────────┘                      │
                                    ┌────────┴────────┐
                                    │  Load Balancer  │
                                    └─────────────────┘

                     Read Replicas
                          │
    ┌─────────────────────┼─────────────────────┐
    │                     │                     │
    ▼                     ▼                     ▼
┌────────┐          ┌────────┐           ┌────────┐
│Replica │          │Replica │           │Replica │
│   1    │          │   2    │           │   3    │
└────────┘          └────────┘           └────────┘
    ▲                     ▲                     ▲
    │                     │                     │
    └─────────────────────┴─────────────────────┘
                          │
                    Replication
                          │
                    ┌─────────┐
                    │ Primary │ ◄── All writes
                    │   DB    │
                    └─────────┘

# CPU Profiling -- identifies which functions consume the most CPU time.
# cProfile is a deterministic profiler built into Python's standard library.
# Overhead is ~10-20%, so it is usable even in staging environments.
import cProfile
import pstats

def profile_function(func):
    """Wrap any function to see where time is actually spent.
    The output shows: total calls, time per call, cumulative time.
    Sort by 'cumulative' to find the function that is the real bottleneck
    (not the one called most often, but the one where time accumulates)."""
    profiler = cProfile.Profile()
    profiler.enable()
    
    result = func()
    
    profiler.disable()
    stats = pstats.Stats(profiler)
    stats.sort_stats('cumulative')  # Sort by total time spent (including sub-calls)
    stats.print_stats(10)           # Show top 10 slowest -- start here
    
    return result

# Memory Profiling -- essential for long-running services (APIs, workers).
# A function that leaks 1KB per call does not matter if called once,
# but at 1,000 RPS that is 1MB/second -- the service crashes in hours.
from memory_profiler import profile

@profile  # Decorating a function shows line-by-line memory usage
def memory_intensive_function():
    # This shows: Line 1 allocates 38MB, Line 2 allocates 0MB (sum is lazy).
    # Without profiling, you might blame sum() -- the profiler proves otherwise.
    large_list = [i for i in range(1000000)]  # ~38MB for 1M Python ints
    return sum(large_list)

# Production-friendly alternative: py-spy (sampling profiler, near-zero overhead).
# Attach to a running process without restarting it -- invaluable for debugging
# production performance issues in real time.
# Usage: py-spy top --pid 12345          (live top-like view)
# Usage: py-spy record -o profile.svg --pid 12345  (flame graph output)

# Using locust for load testing
from locust import HttpUser, task, between

class WebsiteUser(HttpUser):
    wait_time = between(1, 5)
    
    @task(3)
    def view_homepage(self):
        self.client.get("/")
    
    @task(1)
    def view_product(self):
        self.client.get("/products/1")
    
    @task(1)
    def create_order(self):
        self.client.post("/orders", json={
            "product_id": 1,
            "quantity": 2
        })

# ❌ N+1 Problem: 1 query for orders + N queries for users.
# With 1,000 orders, this fires 1,001 database queries!
# Each query is ~5ms, so total = 5 seconds. Unacceptable.
orders = Order.objects.all()  # Query 1: SELECT * FROM orders
for order in orders:
    print(order.user.name)    # Query 2...1001: SELECT * FROM users WHERE id = ?
                              # ORM lazily loads each user on first access

# ✅ Eager Loading: exactly 2 queries total, regardless of N.
# Query 1: SELECT * FROM orders
# Query 2: SELECT * FROM users WHERE id IN (1, 2, 3, ... 1000)
# Total: ~10ms instead of 5 seconds. 500x improvement.
orders = Order.objects.select_related('user').all()
for order in orders:
    print(order.user.name)    # Already loaded -- no additional query

# For many-to-many relationships, use prefetch_related (separate query, joined in Python)
orders = Order.objects.prefetch_related('items').all()

from celery import Celery

app = Celery('tasks', broker='redis://localhost:6379')

@app.task
def send_email(user_id, template):
    """Runs in a separate worker process, not in the web request lifecycle.
    If the email service is slow or down, it retries without blocking users."""
    user = get_user(user_id)
    email_service.send(user.email, template)

@app.task
def generate_report(report_id):
    """Reports can take minutes to generate. Running this synchronously
    would tie up a web worker and likely trigger a request timeout."""
    data = fetch_large_dataset()
    report = process_data(data)
    save_report(report_id, report)

# Usage -- the API endpoint responds in ~50ms instead of ~2500ms
# because it offloads slow work to background workers.
@api.post("/orders")
def create_order(order_data):
    order = save_order(order_data)             # ~50ms -- the only synchronous work
    
    # Queue async tasks -- these are added to Redis in ~1ms each
    send_email.delay(order.user_id, "order_confirmation")  # Runs later in background
    generate_report.delay(order.id)                         # Runs later in background
    
    return {"order_id": order.id}  # Return to user immediately

import aio_pika
import asyncio

async def publish_event(event_type: str, data: dict):
    connection = await aio_pika.connect_robust("amqp://localhost/")
    async with connection:
        channel = await connection.channel()
        await channel.default_exchange.publish(
            aio_pika.Message(body=json.dumps(data).encode()),
            routing_key=event_type,
        )

async def consume_events(queue_name: str, handler):
    connection = await aio_pika.connect_robust("amqp://localhost/")
    async with connection:
        channel = await connection.channel()
        queue = await channel.declare_queue(queue_name)
        async for message in queue:
            async with message.process():
                await handler(json.loads(message.body))

HTML ──► DOM ──┐
              ├──► Render Tree ──► Layout ──► Paint
CSS ──► CSSOM ─┘

<!-- Defer non-critical JavaScript -->
<script src="analytics.js" defer></script>

<!-- Preload critical resources -->
<link rel="preload" href="critical.css" as="style">
<link rel="preload" href="hero-image.webp" as="image">

<!-- Lazy load images -->
<img src="placeholder.jpg" data-src="actual-image.jpg" loading="lazy">

<!-- Use modern image formats -->
<picture>
  <source srcset="image.avif" type="image/avif">
  <source srcset="image.webp" type="image/webp">
  <img src="image.jpg" alt="Description">
</picture>

// Code splitting -- load heavy components only when the user navigates to them.
// The initial page load ships a smaller bundle, and HeavyComponent is
// fetched on-demand as a separate network request.
const HeavyComponent = lazy(() => import('./HeavyComponent'));

// Tree shaking -- bundlers (webpack, esbuild, Rollup) eliminate unused code,
// but only from ES module imports (import/export), not CommonJS (require).
import { debounce } from 'lodash-es';  // ✅ Tree-shakeable: only debounce ships (~300B)
import _ from 'lodash';                 // ❌ Entire library ships (~72KB gzipped!)

-- PostgreSQL: Enable slow query log -- every query over 1 second gets logged
-- with its execution plan, helping you find the worst offenders.
ALTER SYSTEM SET log_min_duration_statement = 1000;  -- Log queries > 1s

-- EXPLAIN ANALYZE actually executes the query and shows real timing data.
-- BUFFERS shows how much data was read from cache vs disk.
-- This is your X-ray machine for query performance.
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM orders 
WHERE user_id = 123 
ORDER BY created_at DESC 
LIMIT 10;

-- What to look for in the output:
-- - Seq Scan: full table scan -- almost always means a missing index
-- - High "actual time": the wall-clock time for that operation
-- - "Rows Removed by Filter": large number = index is not selective enough
-- - "Sort Method: external merge Disk": data too large for memory sort
-- - "Buffers: shared read": data was NOT in PostgreSQL's cache (cold query)

# Formula from PostgreSQL wiki (originally from Brian Kress at Oracle):
# connections = (core_count * 2) + effective_spindle_count
# For SSD: connections approximately equals (cores * 2) + 1
# A 4-core server with SSD needs roughly 9 connections -- not 100!

from sqlalchemy import create_engine

engine = create_engine(
    DATABASE_URL,
    pool_size=20,           # Warm connections maintained in the pool
    max_overflow=10,        # Burst capacity: up to 30 total under spike load
    pool_timeout=30,        # How long to wait for a connection before error (seconds)
    pool_recycle=1800,      # Close and recreate connections after 30 min (prevents stale)
    pool_pre_ping=True,     # Health-check each connection before use (catches dropped connections)
)

import asyncio
import aiohttp

# ❌ Sequential -- each request waits for the previous one to finish.
# 10 URLs at 200ms each = 2 seconds total. The thread just sits idle
# waiting for each response.
def fetch_all_sequential(urls):
    results = []
    for url in urls:
        response = requests.get(url)    # Block for 200ms
        results.append(response.json())
    return results  # Takes N * avg_response_time = 2 seconds

# ✅ Concurrent -- all requests fire simultaneously, we collect results.
# 10 URLs at 200ms each = ~200ms total (limited by the slowest response).
# 10x speedup with zero additional hardware.
async def fetch_all_concurrent(urls):
    async with aiohttp.ClientSession() as session:
        tasks = [fetch(session, url) for url in urls]
        return await asyncio.gather(*tasks)  # Takes max(response_times) = 200ms

async def fetch(session, url):
    async with session.get(url) as response:
        return await response.json()

# Use appropriate data structures for the access pattern
from collections import deque, defaultdict
from functools import lru_cache

# deque: O(1) append/pop from BOTH ends (list.pop(0) is O(n)!)
# Use for: queues, sliding windows, recent-N buffers
queue = deque(maxlen=1000)  # Bounded -- automatically evicts oldest when full

# defaultdict: eliminates the "check if key exists, then update" pattern.
# Cleaner code AND slightly faster due to fewer dictionary lookups.
counts = defaultdict(int)
for item in items:
    counts[item] += 1  # Auto-initializes missing keys to 0

# lru_cache: automatic memoization -- caches function results by arguments.
# Turns repeated expensive calls into O(1) dictionary lookups.
# Use for: recursive algorithms, expensive API/DB calls with stable inputs.
@lru_cache(maxsize=1000)  # Stores last 1000 unique results, evicts least-recently-used
def expensive_calculation(n):
    return fibonacci(n)   # Only computed once per unique n, then served from cache

# Response time percentiles
p50 = 100ms   # Median - most users
p95 = 500ms   # 95% of requests faster than this
p99 = 1000ms  # Tail latency - worst 1%

# Throughput
rps = 10000   # Requests per second

# Error rate
error_rate = errors / total_requests  # Should be < 1%

# Saturation
cpu_usage = 70%      # Alert at 80%
memory_usage = 60%   # Alert at 75%

Required Capacity = (Peak RPS × Avg Response Time) / Utilization Target

Example:
- Peak: 10,000 RPS
- Avg response: 100ms
- Target utilization: 70%

Capacity = (10000 × 0.1) / 0.7 = 1,429 concurrent connections needed