Stage 3 · Build

Performance, Memory & Debugging

pprof & runtime/trace

CPU, heap, mutex, block profiles, execution traces, and flame graph workflows.

8 min readGo for SREBuild

pprof Overview

pprof collects profiles — snapshots of program behavior. CPU profiles show where time is spent. Heap profiles show memory allocation. Mutex profiles show lock contention. Together they give a complete picture of performance.

Goenable-pprof.go

28 linesLn 1, Col 1Go

The blank import registers pprof handlers on the default mux. Collect profiles programmatically for automated profiling. Always stop the CPU profile in a deferred function.

Profile Types

Profile	What It Shows	When to Use
cpu	Where CPU time is spent	Slow functions, hot paths
heap	Memory allocation	Memory leaks, allocation hotspots
mutex	Mutex contention	Lock bottlenecks
block	Blocking operations	Channel deadlocks, sync issues
goroutine	Goroutine stack traces	Leaked goroutines, deadlocks
allocs	Allocation hotspots	Reducing GC pressure

Collecting different profiles


# CPU profile (30 seconds)
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Heap profile
go tool pprof http://localhost:6060/debug/pprof/heap

# Heap after GC
go tool pprof http://localhost:6060/debug/pprof/heap?gc=1

# Mutex contention
go tool pprof http://localhost:6060/debug/pprof/mutex

# Block profile
go tool pprof http://localhost:6060/debug/pprof/block

# Goroutine dump
go tool pprof http://localhost:6060/debug/pprof/goroutine

# Allocation profile
go tool pprof http://localhost:6060/debug/pprof/allocs

# 5-second CPU profile saved to file
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile?seconds=5

Each profile type reveals different performance characteristics. CPU profiles find hot functions. Heap profiles find memory leaks. Mutex profiles find lock contention. Block profiles find blocking operations.

Flame Graphs

Flame graphs visualize where time is spent. The x-axis is stack depth. The y-axis is sample count. Wide functions are hot functions.

Flame graph workflows


# Interactive pprof
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Common commands
(pprof) top 20          # Top functions by CPU time
(pprof) top -cum        # Top by cumulative time
(pprof) list process    # Source code view
(pprof) web             # Call graph (requires graphviz)
(pprof) flame           # Flame graph

# Save profile and analyze later
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
(pprof) save cpu.prof

# Use pprof web UI
go tool pprof -http=:8080 cpu.prof

# Compare profiles
go tool pprof -base old.prof new.prof

top shows the hottest functions. list shows source-level detail. web shows the call graph. flame generates a flame graph. The web UI provides an interactive interface for exploring profiles. Compare profiles before and after optimization.

runtime/trace

runtime/trace captures a detailed execution trace — goroutine scheduling, system calls, GC events, and network I/O. It is the most powerful tool for understanding concurrency behavior.

Gotrace-collection.go

47 linesLn 1, Col 1Go

trace.Start begins recording events. trace.Stop ends recording. go tool trace opens an interactive viewer. The viewer shows a timeline of goroutines, GC pauses, and system calls. It is invaluable for diagnosing latency spikes.

Mutex and Block Profiles

Goenabling-contention-profiles.go

25 linesLn 1, Col 1Go

SetMutexProfileFraction samples mutex events. SetBlockProfileRate controls block profiling granularity. Rate 1 records all events — use in development. Rate 1000 records 1 in 1000 — use in production.

Profiling Workflow

Complete profiling workflow


# 1. Establish baseline
go test -bench=. -benchmem -count=5 > old.txt

# 2. Profile the benchmark
go test -bench=. -cpuprofile=cpu.prof -memprofile=mem.prof

# 3. Analyze CPU profile
go tool pprof cpu.prof
(pprof) top 20
(pprof) list hotFunction

# 4. Analyze heap profile
go tool pprof mem.prof
(pprof) top 20 -alloc_space
(pprof) list allocateMemory

# 5. Make targeted changes

# 6. Re-run benchmarks
go test -bench=. -benchmem -count=5 > new.txt

# 7. Compare with benchstat
go install golang.org/x/perf/cmd/benchstat@latest
benchstat old.txt new.txt

# 8. Verify in production
# Enable pprof in production
# Collect profiles during normal operation
# Analyze with go tool pprof

Profile before optimizing. Establish a baseline. Identify the bottleneck. Make a targeted change. Measure the improvement. Repeat. Never optimize without measurement.

Profile in production

pprof adds minimal overhead — a few percent CPU for profiling. Enable it in production with localhost-only binding. Use port-forward to access profiles securely. Production profiles show real-world performance, not synthetic benchmarks.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.