Heap Analysis and Escape Optimization

A profiling session shows the garbage collector consuming 20% of CPU in a service that allocates almost nothing on the request path — according to the code, which declares a handful of locals per request. The mental model most programmers bring from C is that a local variable lives on the stack for the life of its function. Go's compiler does not promise that. When it decides a value must outlive the frame that declared it, it moves the variable to the heap at compile time, and every such move is a future allocation for the collector to reclaim.

The compiler will tell you exactly what it decided:

go build -gcflags="-m" ./...

./report.go:14:12: can inline buildReport
./report.go:18:9: moved to heap: summary
./report.go:21:20: composite literal escapes to heap
./report.go:25:13: &totals escapes to heap
./report.go:30:7: leaking param: rows

Three messages matter most. moved to heap: x — the local could not stay in its stack frame, so the compiler allocates it on the heap and the variable becomes pointer-to-heap access on every read. escapes to heap — a value (often a composite literal) is being stored somewhere the stack cannot reach: a global, a heap struct, a channel, or a grown slice. leaking param: p — a function parameter's reference escapes into something longer-lived than the call, so the caller's value may also need heap storage; this diagnostic is contagious and explains why one escaping value inflates allocations across a call chain.

A concrete case that shows several at once:

func buildReport(rows []Row) *Report {
	var summary string       // moved to heap: returned through r below
	var totals Totals        // composite literal escapes with the report

	for _, r := range rows {
		totals.Add(r)
	}
	summary = totals.String()

	r := &Report{Summary: summary, Totals: totals} // escapes: result outlives the frame
	return r
}

The escape is not a mistake here — the function returns *Report, and the caller now owns data that must survive buildReport's frame. Stack allocation is impossible by definition. The useful reading of -m is therefore not "how many warnings" but "which escapes were avoidable": values that escape because they must are free of blame; values that escape because of how the code was written — a loop that appends without capacity, a string concatenated ten times, a local boxed into an interface for fmt.Println — are candidates.

Two measurement tools complete the picture. go test -bench=. -benchmem reports B/op and allocs/op for a benchmark, telling you how many heap allocations a code path performs per operation — the number the collector actually cares about. And a heap profile from CPU and Runtime Profiling with pprof tells you which functions produce the volume in production. Compiler output says what escaped; benchmarks and profiles say whether it matters.

Escape analysis output looks chaotic until you group it by cause. Six patterns account for nearly every avoidable heap allocation in ordinary service code.

Returning a local pointer — necessary, not a bug.

func newUser(id int64) *User { return &User{ID: id} } // escapes: result outlives frame

Stack allocation cannot satisfy a caller-owned reference. The compiler already inlines small constructors when it can; leave these alone.

Appending in a loop without capacity — trivially avoidable.

var out []string
for _, s := range rows { // each append may grow: allocate, copy, discard
	out = append(out, normalize(s))
}

When the length is knowable, out := make([]string, 0, len(rows)) collapses several allocations into one. The diagnostics say append(...) and slice growth escape; the benchmark (allocs/op) proves the fix.

String concatenation in a loop — the classic.

var s string
for _, p := range parts {
	s += p // allocates a new string every iteration
}

strings.Builder allocates amortized once: it grows a byte buffer and materializes the string once at String(). Ten parts become one allocation instead of ten.

Passing a pointer where a value would do — the semantic question.

func total(t Totals) Totals { return t }  // value: copies, no escape pressure
func total(t *Totals) Totals { return *t } // pointer: caller's Totals may escape via leaking param

Small structs passed as values cost a copy (cheap for a few words) and give the compiler stack-allocation freedom. This connects directly to Value Semantics versus Pointers: choose the pointer when you need shared mutation or the struct is large, not by reflex.

Boxing into an interface — invisible in source, visible in -m.

fmt.Println(id) // id escapes to heap: converted to interface

Formatting converts the concrete value into an any, which requires a heap-allocated interface box on hot paths. This is why production code formats in logging statements that the level filter removes before the call, not in unconditional Sprintf per iteration.

Closure capture that outlives the call — deliberate by nature. A function returned from a factory captures its variables and forces them to the heap, which is exactly what makes closures work (Closures and Anonymous Functions). It appears in every -m run and belongs there.

The classifier to apply to every diagnostic: does the value need to outlive the frame because of what the program means, or only because of how the line was written? The first group is semantics. The second group is where optimization lives.

Escape analysis is a hypothesis generator; a benchmark is the experiment. The workflow that keeps optimization honest is: find a path with real allocation volume (heap profile or -benchmem), form a hypothesis about one cause, change exactly one thing, and re-run the same benchmark.

func BenchmarkFormat(b *testing.B) {
	parts := []string{"user=42", "op=checkout", "status=ok", "latency=12ms"}
	b.ReportAllocs()
	for i := 0; i < b.N; i++ {
		var s string
		for _, p := range parts {
			s += " " + p
		}
		_ = s
	}
}

BenchmarkFormat-8   8500000   142 ns/op   192 B/op   5 allocs/op

Five allocations per call, four of them from concatenating five pieces. One change — strings.Builder with Grow — and the same benchmark:

BenchmarkFormat-8   41000000   28.6 ns/op   64 B/op   1 allocs/op

From 192 bytes and 5 allocations to 64 bytes and 1, at roughly five times the speed. The compiler diagnostics explained why (each += allocates a new string); the benchmark proved the change mattered; and the allocation count — not the nanoseconds — is the number to watch, because the collector's work scales with allocation volume.

That last point sets the limits of this whole discipline. Allocations matter only through garbage collection pressure: at a modest rate the collector is invisible, at extreme rates it shows up as CPU and pause cost in the heap profile. Optimizing a function that runs twice a day saves nothing; optimizing the function in the request hot path at 10k rps saves real CPU. Three rules keep escape optimization from becoming cargo cult:

1. Never trade correctness for a diagnostic. sync.Pool to avoid allocations, object pooling that leaks references and inflates the heap, hand-rolled buffer reuse that creates aliasing bugs — each converts a measurable cost into an invisible one. Pool only objects that are large and proven hot.
2. Re-measure under production shape. Microbenchmarks that operate on four strings say nothing about a path whose input is a 10 KB payload; take the heap profile after the change (see CPU and Runtime Profiling with pprof) and confirm the volume moved.
3. Keep the readability ledger honest. strings.Builder and make([]T, 0, n) are pure wins — clearer intent and fewer allocations. A rewrite that obscures the code to remove two allocations on a cold path is a net loss, and the review comment should say so.

The end state is not an -m run with no warnings — that output is unachievable for any program that returns data. The end state is knowing, for the code paths that matter, which values must escape, what each one costs per operation, and that the number was worth paying for.