Benchmarking and Profiling
What you will learn
By the end of this lesson, you will be able to:
- write a benchmark that measures the intended operation;
- report allocations and compare distributions rather than one run;
- choose CPU, heap, block, mutex, or execution-trace evidence;
- use
pprofto move from a symptom to relevant code; - decide whether profile-guided optimisation is worth evaluating.
Begin with a user-visible problem
“This function allocates” is not automatically a problem. A useful performance investigation starts with an outcome:
- requests exceed a latency objective;
- throughput is insufficient under expected concurrency;
- memory growth approaches a resource limit;
- CPU cost makes the service too expensive;
- lock or queue contention causes unstable tail latency.
Record a baseline before changing code.
Write a focused benchmark
func BenchmarkParseLessonID(b *testing.B) {
input := "lesson-123456"
b.ReportAllocs()
for b.Loop() {
result, err := ParseLessonID(input)
if err != nil {
b.Fatal(err)
}
runtime.KeepAlive(result)
}
}
The benchmark setup occurs outside the measured loop. b.Loop controls repeated execution in current Go toolchains. For code targeting older toolchains, use the documented for i := 0; i < b.N; i++ pattern.
ReportAllocs reports allocation statistics. KeepAlive can make the intended lifetime explicit; design benchmarks so the compiler cannot remove the work as unused.
Include realistic cases
Use sub-benchmarks for meaningful dimensions:
func BenchmarkDecodeLesson(b *testing.B) {
cases := map[string][]byte{
"small": []byte(`{"title":"Slices"}`),
"large": makeLargeLessonJSON(),
}
for name, input := range cases {
b.Run(name, func(b *testing.B) {
b.SetBytes(int64(len(input)))
for b.Loop() {
var lesson Lesson
if err := json.Unmarshal(input, &lesson); err != nil {
b.Fatal(err)
}
}
})
}
}
Microbenchmarks isolate code but can miss cache, network, database, scheduler, and end-to-end effects. Use load tests and production-like profiles for system decisions.
Compare statistically
Run several samples:
go test -run='^$' -bench=BenchmarkParseLessonID -benchmem -count=10 ./internal/lesson > before.txt
Repeat after the change into after.txt and compare with a suitable statistical tool such as benchstat from the Go performance tools. Keep machine load, toolchain, power settings, and inputs as consistent as practical.
Tiny differences can be noise. Look for a meaningful effect tied to the actual objective.
Choose the right profile
| Evidence | Question |
|---|---|
| CPU profile | Where is sampled CPU time spent? |
Heap inuse_space | What currently retains heap memory? |
Heap alloc_space | Where have allocations accumulated over time? |
| Block profile | Where do goroutines wait on synchronization? |
| Mutex profile | Where is lock contention observed? |
| Goroutine profile | What stacks and wait states exist now? |
| Execution trace | How do goroutines, scheduling, GC, and blocking interact over time? |
Profiles are sampled evidence. Interpret them in the context of the workload and collection window.
Profile a test or benchmark
go test -run='^$' -bench=BenchmarkWork -cpuprofile=cpu.out -memprofile=mem.out ./internal/work
go tool pprof cpu.out
Useful interactive commands include top, top -cum, list FunctionName, and web when graph dependencies are available.
For a service, net/http/pprof can expose runtime profiles on an HTTP server. Protect that listener and avoid exposing it publicly.
Read flat and cumulative cost
- Flat cost is attributed directly to a function.
- Cumulative cost includes work performed by functions it calls.
A coordinator may have low flat cost but high cumulative cost. A low-level operation may have high flat cost across many callers.
Follow the call path and inspect source lines before deciding what to change.
Execution traces
Use a trace when the problem involves latency, scheduling, goroutine states, network blocking, or garbage collection interaction:
go test -run TestScenario -trace=trace.out ./internal/work
go tool trace trace.out
Traces can be large and add overhead. Capture the shortest representative window that contains the problem.
Profile-guided optimisation
Go supports using representative CPU profiles to guide compiler optimisation. PGO can improve some workloads without source changes, but gains vary.
Use a representative, recent profile; verify correctness; compare performance and binary behaviour; and keep a reproducible process for refreshing or removing the profile. Treat PGO as the final part of an evidence loop, not a substitute for fixing inefficient algorithms.
Common mistakes
- Benchmarking setup inside the loop: parsing or allocation unrelated to the target dominates the result.
- Comparing one run: scheduler and machine noise look like an improvement.
- Using unrealistic tiny input: algorithmic behaviour at real sizes remains invisible.
- Optimising the hottest function without understanding why it is called: the better fix may remove calls higher in the stack.
- Reading
allocs/opwithout retention evidence: allocation rate and live memory are different questions. - Shipping a stale or unrepresentative PGO profile: compiler choices target the wrong workload.
Practice
Create two implementations that build a comma-separated string: repeated + concatenation and strings.Builder. Benchmark small and large inputs, report allocations, collect a CPU profile for the larger case, and write a conclusion limited to the measured conditions.
func concatenate(values []string) string {
var result string
for index, value := range values {
if index > 0 {
result += ","
}
result += value
}
return result
}
func build(values []string) string {
var builder strings.Builder
for index, value := range values {
if index > 0 {
builder.WriteByte(',')
}
builder.WriteString(value)
}
return builder.String()
}
func benchmarkJoin(b *testing.B, size int, function func([]string) string) {
values := make([]string, size)
for index := range values {
values[index] = "lesson"
}
b.ReportAllocs()
for b.Loop() {
result := function(values)
runtime.KeepAlive(result)
}
}
Create named benchmarks for both functions at several sizes. Do not publish a universal conclusion from expected intuition; report toolchain, hardware, inputs, sample count, and observed distribution.
Summary
- Start performance work with a user-visible objective and baseline.
- Benchmark representative operations and compare repeated samples.
- Select profiles based on the question: CPU, retention, allocation, blocking, contention, or scheduling.
- Inspect call paths and source before modifying code.
- Re-measure after every optimisation and remove complexity that does not help.
Official references: Diagnostics and Profile-guided optimization.
Ready to wrap up?
Mark this complete when you can explain the main idea and finish the practice task.