How do you capture a CPU profile from a running Go program with runtime/pprof?

## What a CPU profile is A Go CPU profile is a statistical record of where the program's threads were executing while the profiler was on. Roughly 100 times a second, per thread that is burning CPU, the runtime interrupts execution, walks the stack of the goroutine running on that thread, and records it. At the end you have a set of stacks with counts; multiplied by the sample period each count becomes an amount of CPU time. It is a sample, not a log: nothing counts calls, and nothing is instrumented into your functions. ## The two calls The whole API for an in-process capture is two functions in `runtime/pprof`: - `func StartCPUProfile(w io.Writer) error` — turns sampling on and streams the encoded profile to `w`. It returns a non-nil error if a CPU profile is already in progress; a process can only have one at a time. - `func StopCPUProfile()` — turns sampling off. It takes nothing and returns nothing, but it does not return until all pending writes to `w` have completed. That second point is the one juniors trip over. Samples are buffered and drained by a background goroutine; the file on disk is not a valid profile until `StopCPUProfile` has run. If the program exits without it — `os.Exit`, `log.Fatal`, a panic that is not recovered, a `kill -9` — you are left with a truncated file that `go tool pprof` refuses or reads as almost empty. ## The idiomatic shape ```go f, err := os.Create("cpu.out") if err != nil { log.Fatal(err) } defer f.Close() if err := pprof.StartCPUProfile(f); err != nil { log.Fatal(err) } defer pprof.StopCPUProfile() ``` Note the defer order. Deferred calls run last-in-first-out, so `StopCPUProfile` runs before `f.Close()` — which is what you want, because Stop still needs to write into the file. Reversing the two lines gives you writes to a closed file. ## Scoping the window The profile covers exactly the interval between the two calls, and it covers the whole process — every goroutine on every thread, not just the one that called Start. If your goal is to cut the cost of a search-ranking scorer that runs once per query inside a larger service, wrapping `main` gives you a profile dominated by configuration loading, index warm-up and connection setup. Start the profile immediately before the scoring loop instead, or drive the scorer from a benchmark and use `go test -cpuprofile`, which brackets the run for you. A second consequence of the interval being wall-clock: you need enough of it. At roughly 100 samples per second per busy core, a two-second profile of a mostly idle process yields a handful of samples and tells you nothing. Ten to thirty seconds of genuinely busy work — or a benchmark run with a longer `-benchtime` — is the normal target. ## Cost and safety Sampling is cheap and bounded: it is a fixed number of stack walks per second, independent of how many function calls the program makes. That is why the overhead stays in the low single-digit percent and does not scale with call volume, and why taking a CPU profile of a live service is a routine operation rather than an emergency measure. Long-running services usually expose the capture through an HTTP endpoint rather than calling Start and Stop by hand, but the underlying mechanism is exactly these two functions. ## Common mistakes - Calling Start and never calling Stop, then wondering why the file is empty. - Calling `os.Exit` inside the profiled region, which skips every deferred call. - Calling Start twice — the second call errors and, if you ignore the error, you believe you are profiling when you are not. - Profiling for two seconds and treating a function with three samples as a hotspot. - Expecting the profile to explain latency. It records CPU time. A goroutine parked on a channel, a lock or a network read burns no CPU and therefore leaves no samples. ## Where the data goes The output is a gzipped protocol-buffer profile. You do not read it by hand; you feed the file to `go tool pprof` together with the binary that produced it so symbols resolve. Keeping the binary that produced the profile matters — a profile from one build inspected against a different build produces nonsense addresses.