How do you capture a Go heap profile with runtime/pprof, and why call runtime.GC() first?

## What a Go heap profile is A Go heap profile is a table of **allocation sites**: for each call stack that allocated memory, the runtime keeps four numbers — how many objects that stack has allocated since the process started, how many bytes, how many of those objects are still live, and how many of those bytes are still live. It is produced by the Go runtime itself (no agent, no external tool), it is sampled rather than exhaustive, and it is written in the protobuf `pprof` format that `go tool pprof` reads. It is not a CPU profile. A CPU profile answers "where is time going"; a heap profile answers "where is memory coming from, and what is still holding it". ## Route 1: from code, with runtime/pprof The canonical snippet is four lines: ```go f, err := os.Create("heap.out") if err != nil { log.Fatal(err) } defer f.Close() runtime.GC() if err := pprof.WriteHeapProfile(f); err != nil { log.Fatal(err) } ``` `pprof.WriteHeapProfile(w)` is a convenience wrapper for `pprof.Lookup("heap").WriteTo(w, 0)`. The `0` is the debug level: `0` writes the binary protobuf format that tooling expects; `1` writes a legacy human-readable text form with a `runtime.MemStats` dump appended, which is occasionally handy when you cannot get the file off the machine but can read a log. `pprof.Lookup` also knows the name `"allocs"`. That is the *same* underlying data; the two names differ only in which view `go tool pprof` opens by default. ## Route 2: from tests and benchmarks `go test -memprofile mem.out ./...` writes a memory profile for the package under test, and `go test -bench=. -benchmem -memprofile mem.out` does it for a benchmark while also printing bytes-per-operation and allocations-per-operation in the benchmark output. `testing.B.ReportAllocs()` forces those per-op columns on for one benchmark without the flag. For benchmarks this is usually the fastest loop: change code, re-run, compare allocs/op, and open the profile when the number moves the wrong way. `go test` also accepts `-memprofilerate` to change the sampling rate for that run. ## Route 3: from a running service Production services normally export the profile over an HTTP endpoint so you can pull it without restarting anything. The mechanics of that endpoint are a separate subject; what matters here is that the artefact is identical — the same sampled table, read with the same tool. ## Why runtime.GC() before writing The *live* columns of a heap profile (in-use objects and in-use bytes) are computed from the most recently finished garbage-collection cycle. If your program has been allocating heavily since that cycle ended, the profile understates what is live, and objects that have already become garbage but have not been collected yet still count as live. Calling `runtime.GC()` immediately before writing forces a collection so the snapshot reflects the state right now. The cumulative columns (everything ever allocated) do not need this, but a forced GC does not hurt them. The cost is a full collection, which is a real stop-the-world-adjacent pause on a busy service, so it is a deliberate choice rather than something you sprinkle everywhere. ## Reading it `go tool pprof ./binary heap.out` opens an interactive session; the binary is passed so the tool can symbolise addresses. Everything you then do — top, listing a function, opening a flame graph in a browser — works on the four columns above. ## Things people get wrong * Assuming it records every allocation. It records a statistical sample; the numbers are scaled estimates. * Writing the profile without closing or flushing the file, then wondering why the tool reports a truncated profile. * Reaching for a heap profile to explain high CPU, or a CPU profile to explain memory growth. * Taking the profile at process exit and being surprised that almost nothing is live — by then most work is done and much has been collected.