performance

Performance Optimization

Performance work follows one rule above all others: measure before you change anything. Intuition about bottlenecks is wrong more often than it is right. Every optimization should start with profiling, produce a hypothesis, apply a targeted fix, and verify with another measurement.

Core Principles

Principle	Meaning
Measure first	Never optimize without profiling data -- gut feelings about bottlenecks are unreliable
Optimize the critical path	Focus on the code that runs most frequently or blocks user-visible latency
Set budgets	Define acceptable latency, throughput, and resource usage before you start
Avoid premature optimization	Readable, correct code first -- optimize only when measurements show a real problem
Know your tradeoffs	Every optimization trades something (memory for speed, complexity for throughput, freshness for latency)

---

Profiling and Benchmarking

Profiling identifies where time and resources are spent. Without it, you are guessing.

Types of Profiling

Type	What It Reveals	When to Use
CPU profiling	Hot functions, call frequency, execution time distribution	Slow request handling, high CPU usage
Memory profiling	Allocation rates, heap size, object retention, leaks	Growing memory usage, OOM errors, GC pressure
I/O profiling	Disk reads/writes, network calls, blocking waits	Slow file operations, external service latency
Database profiling	Query execution time, query count per request, slow queries	High DB load, N+1 patterns, missing indexes

The Profiling Workflow

1. Baseline -- Capture metrics under normal conditions before any changes
2. Identify -- Find the hotspot consuming the most time or resources
3. Hypothesize -- Form a specific theory about why it is slow
4. Fix -- Apply a single, targeted change
5. Verify -- Measure again to confirm improvement and check for regressions

Performance Budgets

Define limits that trigger action when exceeded:

• Response time: P50, P95, P99 latency targets per endpoint
• Throughput: Minimum requests per second under expected load
• Resource usage: CPU, memory, and connection limits per service
• Page weight: Maximum transfer size for frontend assets

See Profiling Patterns Reference for detailed profiling workflows, bottleneck signatures, and load testing strategies.

---

Caching Strategies

Caching eliminates redundant computation and data fetching by storing results closer to where they are needed.

Cache Layers

Layer	Location	Latency	Use Case
L1 -- In-process	Application memory (object cache, memoization)	Nanoseconds	Hot data accessed many times per request
L2 -- Distributed	Redis, Memcached, shared cache	Sub-millisecond to low milliseconds	Data shared across application instances
HTTP cache	Browser, reverse proxy (Varnish, Nginx)	Zero network round-trip for client cache	Static assets, cacheable API responses
CDN	Edge servers worldwide	Low latency from geographic proximity	Static files, pre-rendered pages, media
Database cache	Query result cache, buffer pool	Varies	Repeated identical queries

Invalidation Approaches

Strategy	How It Works	Best For
TTL-based	Cache entries expire after a fixed duration	Data that tolerates bounded staleness
Event-based	Cache is cleared when the source data changes	Data that must stay fresh after writes
Write-through	Writes update both the cache and the backing store simultaneously	Read-heavy workloads needing strong consistency
Write-behind	Writes update the cache immediately; backing store is updated asynchronously	High write throughput where eventual consistency is acceptable

Cache Stampede Prevention

When a popular cache key expires, many concurrent requests may all try to regenerate it at once, overwhelming the backend. Three approaches prevent this:

• Locking -- Only one request regenerates; others wait or serve stale data
• Probabilistic early recomputation -- Requests randomly refresh the cache before expiration, spreading regeneration over time
• Request coalescing -- Duplicate in-flight requests are collapsed into a single backend call

See Caching Strategies Reference for implementation patterns with multi-language examples.

---

Database Optimization

Database queries are the most common performance bottleneck in web applications.

Index Strategy

• Create indexes on columns used in WHERE, JOIN, and ORDER BY clauses
• Use composite indexes that match your most frequent query patterns (leftmost prefix rule)
• Covering indexes include all columns a query needs, avoiding table lookups entirely
• Monitor unused indexes -- they slow down writes without helping reads

N+1 Query Prevention

The N+1 problem occurs when code fetches a list of N records, then issues one additional query per record to load related data. Instead of 1 query, you execute N+1.

Detection signals:

• Query count scales linearly with result set size
• Many nearly identical queries differing only in a single parameter
• Profiler shows dozens or hundreds of queries for a single page load

Prevention strategies:

• Eager loading (JOIN or separate batch query upfront)
• Batch loading (collect IDs, fetch all related records in one query)
• DataLoader pattern (automatic batching and deduplication within a request)

Connection Pooling

Opening a database connection is expensive (TCP handshake, authentication, TLS negotiation). Connection pools maintain a set of reusable connections:

• Size the pool based on expected concurrency -- too small causes queueing, too large overwhelms the database
• Always return connections to the pool promptly -- leaked connections exhaust the pool
• Set idle timeouts to reclaim unused connections
• Use external poolers (like PgBouncer for PostgreSQL) when application-level pooling is insufficient

See Database Optimization Reference for query patterns, explain plan analysis, and multi-language examples.

---

Memory and Resource Management

Memory Optimization Patterns

Pattern	Description
Object pooling	Reuse expensive objects instead of allocating and discarding them
Streaming	Process large datasets as streams instead of loading everything into memory
Lazy initialization	Defer creation of expensive objects until they are actually needed
Weak references	Hold references that do not prevent garbage collection
Buffer reuse	Allocate buffers once and reuse them across operations

Lazy Loading

Lazy loading defers work until the result is actually needed. It reduces startup time and memory usage but adds complexity and can cause unexpected latency later.

Where lazy loading helps:

• Loading related database records only when accessed
• Initializing expensive service connections on first use
• Loading UI components or assets only when they become visible

Where lazy loading hurts:

• When the deferred work always happens anyway (just adds overhead)
• When it moves latency from a predictable startup phase to unpredictable user interactions
• When it creates N+1 query patterns (see Database Optimization above)

Batch Operations

Replace individual operations with batch alternatives wherever possible:

• Batch inserts instead of inserting one row at a time
• Batch API calls instead of calling an external service N times
• Bulk file operations instead of processing files individually

---

Quick Reference: Common Bottleneck Patterns

Symptom	Likely Cause	First Investigation Step
Slow response times, low CPU	I/O waits (database, network, disk)	Profile I/O and check query logs
High CPU, normal response times	Inefficient algorithms or excessive computation	CPU profile to find hot functions
Growing memory over time	Memory leak (unreleased references, unbounded caches)	Heap dump comparison over time
Intermittent slowness under load	Resource contention (locks, connection pool exhaustion)	Check pool sizes and lock wait times
Fast locally, slow in production	Network latency, missing caches, different data volumes	Compare profiling data between environments

---

Reference Files

Reference	Contents
Caching Strategies	Cache layers, invalidation patterns, stampede prevention with multi-language examples
Database Optimization	Query optimization, N+1 prevention, connection pooling, batch operations with multi-language examples
Profiling Patterns	Profiling workflows, bottleneck signatures, performance budgets, load testing strategies

---

Integration with Other Skills

Situation	Recommended Skill
Performance issues caused by poor architecture	Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for clean architecture guidance
Need to refactor slow code paths	Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for refactoring techniques
API response time optimization	Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for API design principles
Database schema and query design	Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for testing strategies to verify optimizations