Advanced Go

Benchmarking and Profiling

Measure representative performance, locate bottlenecks, compare changes, and avoid misleading microbenchmarks.

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 pprof to 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

EvidenceQuestion
CPU profileWhere is sampled CPU time spent?
Heap inuse_spaceWhat currently retains heap memory?
Heap alloc_spaceWhere have allocations accumulated over time?
Block profileWhere do goroutines wait on synchronization?
Mutex profileWhere is lock contention observed?
Goroutine profileWhat stacks and wait states exist now?
Execution traceHow 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/op without 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.

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.

Copyright © 2026