go tool pprof: Analyze Go CPU and Heap Profiles
go tool pprof opens a Go profile and lets you inspect hotspots interactively, including a browser UI with -http.
Go bakes profiling into the toolchain. go tool pprof reads the profiles that go test -cpuprofile or net/http/pprof produce and renders top functions, source annotations, and flame graphs.
What it does
go tool pprof loads a profile (CPU, heap, mutex, block) and offers commands like top (hottest functions), list (annotated source), and web (a call graph). With -http it starts a local server with an interactive flame graph and graph views.
Common usage
go test -cpuprofile cpu.out -bench .
go tool pprof cpu.out # interactive prompt: top, list, web
# browser UI with flame graph
go tool pprof -http=:8080 cpu.out
# pull a live profile from a running server
go tool pprof -http=:8080 http://localhost:6060/debug/pprof/heapOptions
| Flag / Command | What it does |
|---|---|
| -http=<addr> | Serve the interactive web UI at addr |
| top | List the functions consuming the most resource |
| list <func> | Show annotated source for a function |
| web | Open a call-graph SVG (needs graphviz) |
| -nodecount=N | Limit the number of nodes shown |
In CI
CI generates profiles with go test -cpuprofile / -memprofile and archives them; developers open them locally with -http. To compare two profiles for a regression, use go tool pprof -base old.out new.out to see the delta.
Common errors in CI
"Failed to execute dot. Is Graphviz installed?" on the web command or the graph view means graphviz is missing; install it (apt-get install graphviz). "profile is empty" or "parsing profile: unrecognized profile format" means the file was not written by the Go runtime, or the test exited before the profile flushed. When pulling from /debug/pprof, "connection refused" means the pprof HTTP handler was not registered or the port is wrong.