Performance Fundamentals¶

// Kernel threads: Java thread-per-request pattern
// 10,000 concurrent users = 10,000 threads = 10-20 GB ram, thrashing scheduler

// User-space: Go goroutine-per-request pattern  
// 10,000 concurrent users = 10,000 goroutines ≈ 40-80 MB ram, 4-8 kernel threads

// Same application, 100-200× more efficient memory use

// BAD: Goroutine leak
func subscribe(eventChan chan Event) {
    for event := range eventChan {
        go func() {
            // Process event
        }()
    }
}

// Unbounded spawn is not the same as a leak.
// If each goroutine *returns*, you have a load/memory spike, then they go away.
// A leak is a goroutine that *never returns* (blocked on a chan/mutex/context).
// This example is unbounded spawn; it becomes a leak only if process() never exits.

// GOOD: Reuse goroutines with worker pool
func subscribe(eventChan chan Event) {
    for i := 0; i < 100; i++ {
        go func() {
            for event := range eventChan {
                // Process event
            }
        }()
    }
}
// Always 100 goroutines regardless of request rate

import "runtime"

func diagnosticGoroutineCount() {
    for {
        count := runtime.NumGoroutine()
        log.Printf("Active goroutines: %d", count)
        time.Sleep(10 * time.Second)
    }
}

// If this number constantly increases, you have a leak

// BAD: Unbounded buffer
eventQueue := make(chan Event, 1000000)  // Crash if more than 1M events queue

// Every send waits for receive; if receiver is slow:
// - Queue fills up
// - Sender blocks
// - Upstream backs up
// - Cascading failure

// GOOD: Bounded with backpressure
eventQueue := make(chan Event, 1000)  // Only buffer 1000

// If sender is faster than receiver:
// - Sender blocks on send
// - Upstream gets backpressure signal
// - Upstream can shed load (drop requests, fail fast)

// BAD: Unbounded allocation
func cacheUserPrefs(userID int, prefs map[string]interface{}) {
    globalCache := make(map[int]map[string]interface{})
    globalCache[userID] = prefs  // No eviction policy
}

// After 1 million users:
// - globalCache has 1M entries
// - Each entry has nested map (at least 200 bytes)
// - Total: 200 MB minimum, plus GC pressure

// GOOD: Bounded cache
type BoundedCache struct {
    max int
    mu sync.Mutex
    cache map[int]map[string]interface{}
    lru *lru.Cache  // Evict least-used when full
}

func (c *BoundedCache) Set(userID int, prefs map[string]interface{}) {
    c.mu.Lock()
    defer c.mu.Unlock()
    if c.cache.Len() > c.max {
        c.cache.RemoveOldest()
    }
    c.cache[userID] = prefs
}

// BAD: O(n²) memory allocations
var result string
for i := 0; i < 10000; i++ {
    result += fmt.Sprintf("item %d,", i)  // New string each time
}
// Creates 10,000 intermediate strings, ~5MB garbage

// GOOD: StringBuilder (or strings.Builder in Go)
var buf strings.Builder
for i := 0; i < 10000; i++ {
    fmt.Fprintf(&buf, "item %d,", i)
}
result := buf.String()  // One allocation

// BAD: Map grows without bound
seenIDs := make(map[int]bool)
for event := range eventStream {
    seenIDs[event.ID] = true  // Never pruned
    // After 1M events: 8MB (int64 key + bool value + bucket overhead)
}

// GOOD: Use TTL or bounded LRU
cache := lru.New(100000)  // Only keep 100k most recent
for event := range eventStream {
    cache.Add(event.ID, true)
}

// BAD: Cardinality explosion
log.Printf("Request from user_id=%d, path=%s", userID, path)
// 1 million unique userIDs = 1 million log patterns
// Logging system allocates string + buffer for each unique pattern

// GOOD: Use structured logging, filter cardinality
log.WithFields(log.Fields{"path": path}).Info("request")  // Cardinality = 100s of paths
// Log user_id separately if needed, with sampling

// A single GC pause can spike latency

Request timeline:
  t=0ms: Request arrives
  t=1ms: Allocate 100MB for processing
  t=2ms: Processing halfway done
  t=2.5ms: STOP-THE-WORLD GC pause starts (all goroutines stop)
  t=50ms: GC pause ends (48ms latency spike!)
  t=52ms: Processing resumes
  t=55ms: Response sent

  User sees: p99 latency = 55ms (was 5ms before)

// Default GOGC=100: Trigger GC when heap doubles
// Lower GOGC = more frequent GC, shorter pauses, higher CPU
// Higher GOGC = fewer pauses, longer pauses when they happen, less CPU

import _ "net/http/pprof"
// Profile with pprof to see GC frequency

// Option 1: Reduce allocation rate (best fix)
// Option 2: Tune GOGC *before* start, or call debug.SetGCPercent at runtime.
// os.Setenv("GOGC", "50") after the process has started does NOT retune GC.
debug.SetGCPercent(50)  // this is what actually changes the running process

// Option 3: GOMEMLIMIT (Go 1.19+) as a soft heap cap, with SetMemoryLimit

// BAD: Shared mutex on hot path
type Counter struct {
    mu sync.Mutex
    val int64
}

func (c *Counter) Increment() {
    c.mu.Lock()
    c.val++
    c.mu.Unlock()  // 100,000 RPS = 100k locks/sec
}
// At scale, context switch cost of locking dominates

// GOOD: Atomic or sharded
type Counter struct {
    val atomic.Int64
}
func (c *Counter) Increment() {
    c.val.Add(1)  // No lock, no context switch, CPU cache-friendly
}

// OR: Shard across cores
type ShardedCounter struct {
    shards [runtime.NumCPU()]atomic.Int64
}
func (c *ShardedCounter) Increment() {
    cpu := getcpu()  // or use hash of thread-local ID
    c.shards[cpu].Add(1)
}

// BAD: JSON marshaling per request
type Response struct {
    UserID int
    Name string
}

func handleRequest(w http.ResponseWriter, r *http.Request) {
    resp := Response{UserID: 123, Name: "Alice"}
    json.NewEncoder(w).Encode(resp)  // Reflection + allocation per request
}
// 10,000 RPS = 10k reflection operations/sec

// GOOD: Pre-marshal or use code generation
var cachedResponse []byte = []byte(`{"UserID":123,"Name":"Alice"}`)
func handleRequest(w http.ResponseWriter, r *http.Request) {
    w.Write(cachedResponse)  // No allocation
}

// OR: Use code-gen (easiest)
// easyjson, protobuf, or sqlc generate marshaling code at compile time

// BAD: Unbounded goroutine creation (this is a load bound, not a leak
// unless the goroutine never returns)
func handleRequest(w http.ResponseWriter, r *http.Request) {
    go func() {  // New goroutine for each request!
        // Process
    }()
}
// 1 million concurrent requests = 1 million goroutines = 2-4 GB memory
// Context switching thrashing if > cores × 4
// Leak = those goroutines *never exit*. Spawn-per-request that finishes is "too many", not "leaked".

// GOOD: HTTP server already pools goroutines internally
// Go's net/http reuses goroutines (connection pooling)
// Additional goroutines only if you need background work

func handleRequest(w http.ResponseWriter, r *http.Request) {
    // This runs in a goroutine already managed by HTTP server
    // Only create new goroutine if you need async work after response
}

// If you DO need background work:
func handleRequest(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(200)
    w.Write([]byte("OK"))

    go asyncTask()  // Fire-and-forget, but bounded!
}
// But: you need a worker pool to bound goroutines
type BackgroundTasks struct {
    queue chan Task
}
func NewBackgroundTasks(workers int) *BackgroundTasks {
    q := make(chan Task, 1000)  // Bounded queue
    for i := 0; i < workers; i++ {
        go func() {
            for task := range q {
                task.Execute()
            }
        }()
    }
    return &BackgroundTasks{queue: q}
}

// BAD: Synchronous logging (every log waits for disk)
log.Info("Processing request")  // Waits for disk write (~5ms)
process()
log.Info("Done")                 // Waits for disk write (~5ms)
// Total: 10ms added to request latency just for logging!

// GOOD: Asynchronous logging (buffer in memory, flush batch)
asyncLog.Info("Processing request")  // Enqueues, returns immediately
process()
asyncLog.Info("Done")                 // Enqueues, returns immediately
// Background goroutine batches and writes every 10ms
// Added latency: <1ms

type AsyncLogger struct {
    queue chan LogEntry
}

func NewAsyncLogger(bufferSize int) *AsyncLogger {
    l := &AsyncLogger{queue: make(chan LogEntry, bufferSize)}
    go l.flushLoop()  // Background goroutine
    return l
}

func (l *AsyncLogger) flushLoop() {
    batch := []LogEntry{}
    ticker := time.NewTicker(100 * time.Millisecond)
    for {
        select {
        case entry := <-l.queue:
            batch = append(batch, entry)
            if len(batch) > 1000 {  // Flush when full
                l.flush(batch)
                batch = []LogEntry{}
            }
        case <-ticker.C:
            if len(batch) > 0 {
                l.flush(batch)
                batch = []LogEntry{}
            }
        }
    }
}

// GOOD: Structured logging with sampling
import "go.uber.org/zap"

logger, _ := zap.NewProduction()
if rand.Intn(100) == 0 {  // Sample 1-in-100
    logger.Info("request",
        zap.String("path", r.URL.Path),        // Low cardinality
        zap.Int("status", 200),                 // Low cardinality
        zap.Duration("latency", duration),      // OK: will be bucketed
    )
}

// Problem: Goroutine migrates between cores, flushing CPU cache
// Solution: Pin goroutine to a core

import (
    "runtime"
    "golang.org/x/sys/unix"
)

func pinToCPU(cpuID int) {
    runtime.LockOSThread()  // required: affinity is per OS thread, not per goroutine
    var cpuSet unix.CPUSet
    cpuSet.Set(cpuID)
    unix.SchedSetaffinity(0, &cpuSet)  // bind the locked OS thread
}

func main() {
    // Each worker goroutine handles a shard — must stay on that OS thread
    for i := 0; i < runtime.NumCPU(); i++ {
        go func(cpu int) {
            pinToCPU(cpu)
            worker()  // never unlock the OS thread if you want the pin to stick
        }(i)
    }
}

// BAD: Read entire file into memory
data, _ := ioutil.ReadFile("bigfile.bin")  // 10GB file = 10GB allocation + copy
process(data)

// GOOD: Memory-map the file
f, _ := os.Open("bigfile.bin")
m, _ := unix.Mmap(int(f.Fd()), 0, 10<<30, unix.PROT_READ, unix.MAP_SHARED)
// Linux manages paging; only accessed pages are in RAM
// Kernel evicts pages when memory is needed
process(m)
unix.Munmap(m)

import _ "net/http/pprof"

// Start server with pprof: go run main.go
// In another terminal:
// go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

// This creates a profile showing CPU time spent in each function
// Sort by cumulative time to find real bottlenecks

// Output:
// (pprof) top
// Showing nodes accounting for 2500ms, 98.5% of 2540ms total
//       flat  flat%   sum%        cum   cum%
//      800ms 31.5% 31.5%      1500ms 59.1%  encoding/json.Marshal
//      600ms 23.6% 55.1%       600ms 23.6%  runtime.memclr
//      400ms 15.7% 70.8%       900ms 35.4%  sync.(*Mutex).Lock

// go tool pprof http://localhost:6060/debug/pprof/heap

// (pprof) top -cum
// Shows most-allocated functions

// (pprof) alloc_space  (total allocated, not just live)
// vs live_space (currently held in memory)

// Typical output shows allocation hotspots:
// 1. JSON marshaling
// 2. String concatenation
// 3. Map growth

import "runtime"
import "runtime/pprof"

func diagnostics() {
    f, _ := os.Create("goroutine.prof")
    pprof.Lookup("goroutine").WriteTo(f, 1)

    // or: go tool pprof http://localhost:6060/debug/pprof/goroutine
}

// This shows all goroutine stack traces
// Look for goroutines stuck on:
//   - channel receive (channel never closed)
//   - mutex (holding lock too long)
//   - network (socket read timeout missing)

import "testing"

func BenchmarkJSONMarshal(b *testing.B) {
    data := Response{UserID: 123, Name: "Alice"}
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        json.Marshal(data)
    }
}

// Run: go test -bench=. -benchmem
// Output:
// BenchmarkJSONMarshal-8   1000000   1234 ns/op   128 B/op   2 allocs/op
//                          ^^^^^^^^  ^^^^         ^^^         ^
//                          iterations per-op ns   allocs/op   # of allocs