go tool pprof: Profile Binaries in CI
go tool pprof reads a profile (CPU, heap, block) and reports where time or allocations go, via text tables, source listings, or an interactive web UI.
Profiles come from go test -cpuprofile or a service's /debug/pprof endpoint. pprof turns the raw data into the hot functions, which is how you confirm a CI perf regression.
What it does
go tool pprof loads a profile file together with the binary that produced it (for symbols) and analyzes it. -top lists the heaviest functions, -list <func> shows annotated source, and -http serves an interactive flame graph and call graph in a browser.
Common usage
go test -cpuprofile=cpu.out -bench=. ./pkg/codec
go tool pprof -top cpu.out
go tool pprof -list=Encode ./codec.test cpu.out
go tool pprof -http=:8080 cpu.out # local UI onlyFlags
| Flag | What it does |
|---|---|
| -top | Print the functions consuming the most resource |
| -list <regex> | Show source annotated with profile data |
| -http <addr> | Serve the interactive web UI (flame/graph) |
| -cum | Sort by cumulative cost |
| -nodecount <n> | Limit the number of nodes shown |
| go test -cpuprofile / -memprofile | Produce the profile to analyze |
In CI
Generate profiles during a benchmark step and upload them as artifacts; run go tool pprof -top non-interactively to print a summary into the log. The -http UI needs a browser, so reserve it for local analysis. Graph output via -svg/-png needs Graphviz installed on the runner.
Common errors in CI
"profile is empty" means the workload was too short to collect samples; raise -benchtime or run longer. "could not symbolize ..." or "Local symbolization failed" means you did not pass the matching binary alongside the profile. "graphviz: executable file not found in $PATH" when generating images means Graphviz is missing; apt-get install graphviz on the runner.