Profiling with pprof
A profile is a statistical sample of where a program spends its time or memory. Go writes the format and reads it: runtime/pprof records from a program, net/http/pprof serves a live one, and go tool pprof answers questions about the file. A benchmark tells you that something is slow; a profile tells you which function is. The previous lesson looked for bugs; this one looks for cost.
A CPU profile
The sampler interrupts the program about a hundred times a second and records the stack, so a short run needs many iterations to produce enough samples. A benchmark is the convenient place to record one: -cpuprofile=cpu.out writes the file while the benchmarks run, and the profile belongs to that run and that machine.
package hot
import "testing"
func BenchmarkSlowBuild(b *testing.B) {
for i := 0; i < b.N; i++ {
SlowBuild(2000)
}
}
func BenchmarkFastBuild(b *testing.B) {
for i := 0; i < b.N; i++ {
FastBuild(2000)
}
}
func BenchmarkHash(b *testing.B) {
s := FastBuild(2000)
b.ResetTimer()
for i := 0; i < b.N; i++ {
Hash(s)
}
}
go test -bench=. -benchtime=300ms -cpuprofile=cpu.out -run=^$ .
goos: linux
goarch: amd64
pkg: example.com/hot
cpu: Intel(R) Core(TM) i3-6006U CPU @ 2.00GHz
BenchmarkSlowBuild-4 192 1781111 ns/op
BenchmarkFastBuild-4 45289 7559 ns/op
BenchmarkHash-4 272757 1508 ns/op
PASS
ok example.com/hot 1.397s
The test run wrote cpu.out next to the package. The numbers on the benchmark lines are one run on this machine, but the profile is the artefact: it can be read again, compared with another build, and attached to a review.
go test -bench=. -benchtime=300ms -cpuprofile=cpu.out -run=^$ . >/dev/null
go tool pprof -top -nodecount=8 cpu.out | sed -n '/flat flat%/,$p'
flat flat% sum% cum cum%
350ms 17.68% 17.68% 350ms 17.68% example.com/hot.Hash
200ms 10.10% 27.78% 440ms 22.22% example.com/hot.FastBuild
200ms 10.10% 37.88% 200ms 10.10% runtime.memmove
180ms 9.09% 46.97% 210ms 10.61% strings.(*Builder).WriteByte (inline)
90ms 4.55% 51.52% 90ms 4.55% runtime.typePointers.next
70ms 3.54% 55.05% 70ms 3.54% runtime.futex
70ms 3.54% 58.59% 170ms 8.59% runtime.scanObject
70ms 3.54% 62.12% 80ms 4.04% runtime.unlock2
flat is the time spent in the function itself and cum is the time including the functions it called; a hot leaf has a large flat value and a parent has a large cumulative one. The percentages move a little between runs, which is why a profile is read for the order of magnitude and the shape of the call tree, not for the last digit.
A memory profile
-memprofile=mem.out records allocations, and go tool pprof -alloc_space mem.out ranks them by total bytes rather than by objects that survived. The distinction matters: -inuse_space shows the heap at the end, while -alloc_space shows every allocation the program made, which is the one that finds a loop building a string by concatenation.
For a server, import net/http/pprof for its side effect and the profiles are served under /debug/pprof/ on the same port: a CPU profile with /debug/pprof/profile?seconds=30, a heap with /debug/pprof/heap. That endpoint must not be exposed to the public internet; it is a debugging door, usually on localhost or behind authentication.
Reading a profile
The command-line report is enough for most questions: -top ranks functions, -list=Func prints the source with per-line costs, and -peek shows the callers and callees of one function. The web view draws a graph, but it is the same data. Start with the top of the profile, fix the one function that dominates, and profile again: optimising a function that is not in the top ten is the common way to waste a day.
Exercises
- Record a CPU profile of the benchmark and find the function with the largest flat value. What does the source line report for it?
- Record a memory profile and compare -inuse_space with -alloc_space for the slow builder. Which one shows the cost of the loop?
- Add net/http/pprof to a small server and fetch a profile with go tool pprof http://localhost:8080/debug/pprof/heap. What does the tool print before it opens the prompt?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does a CPU profile sample?
Answer
The stack of the running program about a hundred times a second
Sampling is why a profile is statistical and needs many iterations.
-
What does -cpuprofile do on go test?
Answer
Writes a CPU profile while the tests or benchmarks run
The file is read later with go tool pprof.
-
What does the flat column mean?
Answer
Time spent in the function itself
cum includes callees; flat is the function's own cost.
-
Which pprof view ranks functions by cost?
Answer
-top
-top is the first report to read; the others drill down.
-
What does -alloc_space show?
Answer
Every allocation the program made, ranked by bytes
inuse_space is the heap at the end; alloc_space is the total churn.
-
What does net/http/pprof add to a server?
Answer
Profile endpoints under /debug/pprof/
The import is for its side effect; the handlers register themselves.
-
Why should /debug/pprof/ not be public?
Answer
It exposes internals and costs CPU while a profile runs
Profiling a public endpoint is a denial-of-service risk.
-
When is a profile more useful than a benchmark?
Answer
When you know the code is slow but not which function is
The benchmark gives the number; the profile gives the location.
-
What does -list=Func print?
Answer
The source of the function with the cost per line
It is the fastest way to see which line inside a hot function costs.
-
What happens to profile numbers between runs?
Answer
They move a little, so read the order and the shape
Statistical sampling plus machine noise means the ranking is the signal.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev