Run go build -gcflags="-m" to enable escape analysis output, which tells you whether variables are allocated on the stack or heap. This helps you identify performance bottlenecks where stack-allocated data is unexpectedly promoted to the heap, potentially increasing garbage collection pressure.
The -m flag prints escape analysis information to stderr during compilation. You can combine it with -m=2 for more detailed output, including the specific reason for heap allocation. Note that this flag is only available during the build process, not at runtime.
Here is a practical example showing a variable that escapes to the heap:
package main
import "fmt"
func main() {
// This slice escapes to the heap because it is returned
// and must survive beyond the function call.
data := []int{1, 2, 3}
fmt.Println(data)
}
Compile and run with escape analysis enabled:
go build -gcflags="-m" main.go
You will see output like this:
./main.go:7:6: data escapes to heap
In contrast, a variable that stays on the stack looks like this:
func process() {
x := 10
// x does not escape; it stays on the stack
fmt.Println(x)
}
Running the same build command on this code produces no escape warning for x.
For more complex cases, use -m=2 to see why a variable escapes:
go build -gcflags="-m=2" main.go
This might output:
./main.go:7:6: data escapes to heap:
data is returned from function main
Common reasons for heap allocation include returning a variable from a function, storing it in a global variable, or passing it to a goroutine. To fix unnecessary escapes, avoid returning pointers to local variables, minimize the use of interfaces with local data, and ensure goroutines don't capture large local structures.
Remember that escape analysis is a compiler optimization, not a runtime tool. It only works during the build phase. Also, the analysis is conservative; sometimes the compiler promotes variables to the heap even if they could theoretically stay on the stack, to ensure safety or simplify code generation.
Use this tool when profiling shows high GC activity or when optimizing tight loops. Don't over-optimize prematurely; the Go compiler is generally good at making these decisions automatically. Focus on cases where you see clear patterns of unnecessary heap allocation that impact performance.