Hermes Wiki
Developer/Languages/Go/PerformanceOptimization/Fundamentals/profiling-escape-analysis-and-allocation-conscious-go

Profiling, Escape Analysis, and Allocation-Conscious Go

Concept

The Go compiler decides at compile time whether each value is allocated on the stack or the heap — this is escape analysis. A value that never outlives the function that created it (no pointer to it survives the return, it isn't captured by a closure or goroutine that outlives the call, it isn't stored into an interface in a way the compiler can't prove is safe) stays on the stack: allocation is just a stack-pointer bump, and it's freed automatically when the function returns, with zero garbage-collector involvement. A value that does escape gets heap-allocated instead, which costs more (an actual allocation, GC tracking, eventual collection). go build -gcflags="-m" prints the compiler's escape decisions line by line, which turns "why is this slow" into "which specific value is escaping and why."

pprof is the runtime-side complement: it doesn't predict allocation behavior, it measures actual behavior under real load. A CPU profile samples the call stack at a fixed interval to show where wall-clock time is actually spent; a heap profile records alloc_space/alloc_objects (cumulative, since the process started) and inuse_space/inuse_objects (currently live) so you can see both "what allocates the most over time" and "what's actually sitting in memory right now." Profiles come from a running server via the net/http/pprof package's endpoints, or from tests via go test -bench=. -benchmem, which reports allocations-per-operation and bytes-per-operation for each benchmark. go tool pprof then gives an interactive view (top for the hottest functions, list for line-by-line annotation, a call graph via web) over any of these profiles. benchstat compares two sets of benchmark runs statistically, which matters because a single before/after run is noisy enough to make an actual regression look like an improvement or vice versa — it reports whether a measured difference is likely real or within the run's own variance.

Tradeoffs

Technique Benefit Cost
-gcflags="-m" (escape analysis output) Instant, no running program needed; explains exactly why a specific value escapes Doesn't tell you whether that escape matters — a function that escapes once per request is irrelevant next to one called in a hot inner loop
CPU/heap profiling (pprof) Measures real, prioritized impact under representative load — tells you what's actually worth fixing Requires a running workload resembling production; profiling an unrepresentative micro-case can point at the wrong function entirely
interface{}/any parameters Maximum flexibility — one function accepts any type Boxes the value into the interface, which usually forces a heap allocation even for a value that would otherwise stay on the stack — invisible in the source, only visible via -gcflags="-m" or a heap profile
Concrete typed parameters / generics No boxing, no heap escape from the parameter itself Less flexible than interface{}; requires either a concrete type per call site or Go 1.18+ type parameters
Pre-sized slices/maps (make([]T, 0, n)) One allocation instead of several as the collection grows and gets copied Requires knowing (or estimating) the final size up front, which isn't always available

When to use / when not to

  • Profile (CPU and heap) before changing anything performance-motivated — optimizing a function that isn't actually hot, based on intuition alone, is wasted engineering effort and sometimes makes the code worse for no measured gain.
  • Use -gcflags="-m" as a follow-up once pprof has already named a specific hot function, to understand why a value in it escapes, not as the starting point for a performance investigation.
  • Reach for -benchmem and benchstat whenever a change is allocation-motivated — "fewer allocations" without a benchmark number is an assumption, not a result, and a single run either direction isn't enough to separate signal from noise.
  • Don't chase every heap allocation the profiler shows — most allocations in a typical service are fine; the ones worth acting on are the ones that are a meaningful fraction of alloc_objects/alloc_space in a path that's actually hot.

Common pitfall

Passing a value through an interface{}/any parameter — a generic logging call, a container, a variadic helper — forces it onto the heap ("boxing") even when the same value passed concretely would have stayed on the stack, and nothing in the call site's source code signals this. A tight loop that calls something like a fmt.Sprintf-style variadic function per iteration allocates once per argument per iteration purely from the interface conversions, independent of whatever the function itself does. This is invisible without either -gcflags="-m" on the specific call or a heap profile showing the allocation site — it doesn't show up as an obviously expensive line the way a nested loop or a network call would.

Engineering Lens

Escape analysis and pprof answer different questions and the review test is whether an optimization is backed by the right one: "-gcflags=-m says this escapes" explains a mechanism but not whether it's worth fixing, while a profile showing a function as a real share of CPU or heap time establishes that it matters before anyone spends effort on it. The strong version of a performance PR names the specific profile that motivated the change and the benchstat-confirmed before/after numbers, not "interface{} boxes so I made it concrete" as a rule applied uniformly regardless of whether that code path is ever actually hot.

Sources

Hermes Wiki