pprof Deep Dive — Specification¶

Focus: Precise reference for the pprof tool itself — how to invoke it, every profile type it consumes, every interactive command it offers, every flag that changes its output, and the on-disk format it reads.

Sources: - runtime/pprof package: https://pkg.go.dev/runtime/pprof - net/http/pprof package: https://pkg.go.dev/net/http/pprof - pprof upstream: https://github.com/google/pprof - Profile format: https://github.com/google/pprof/blob/main/proto/profile.proto - Go diagnostics guide: https://go.dev/doc/diagnostics

1. Invocation forms¶

go tool pprof accepts a profile source as the last argument. Everything before it is flags.

The HTTP form requires the target to have the net/http/pprof handlers registered, typically by side-effect import:

import _ "net/http/pprof"
go http.ListenAndServe("127.0.0.1:6060", nil)

2. Profile types¶

The net/http/pprof endpoint exposes the following named profiles. All accept ?debug=N (text format when N>0) and ?seconds=N where applicable.

The heap and allocs endpoints serve the same underlying profile; what differs is the default sample_index (in-use vs. allocated).

3. Sample indices¶

A profile may carry multiple value columns per sample. -sample_index selects which column drives all commands.

go tool pprof -sample_index=alloc_objects heap.pb.gz

Inside the shell you can switch with sample_index=alloc_space at any time.

4. Interactive commands¶

After loading a profile, pprof drops into a REPL. The core verbs:

Regexes are RE2; they match against the fully qualified function name as package.Func or (*Type).Method.

5. Web UI (-http)¶

-http=addr starts an embedded HTTP server with four built-in views, each a one-click switch:

The "View" menu also exposes "Refine" filters (focus, ignore, hide, show, tagfocus) as URL parameters, so a flame graph URL is shareable.

Useful flags around -http:

• -no_browser — do not auto-open a browser, just print the URL.
• -nodecount=N — initial graph node cap.
• -edgefraction=F — initial edge threshold.

6. Programmatic capture (runtime/pprof)¶

The same profiles are accessible from inside the program without an HTTP server:

import "runtime/pprof"

f, _ := os.Create("cpu.pb.gz")
pprof.StartCPUProfile(f)
defer pprof.StopCPUProfile()
// ... workload ...

g, _ := os.Create("heap.pb.gz")
pprof.Lookup("heap").WriteTo(g, 0)

7. Custom profiles¶

var openFiles = pprof.NewProfile("openfiles")

func open(p string) *os.File {
    f, _ := os.Open(p)
    openFiles.Add(f, 2)   // record stack at this point, key = f
    return f
}

func closeOne(f *os.File) {
    openFiles.Remove(f)
    f.Close()
}

Add(key, skip) records the current stack and increments the count for that stack; Remove(key) decrements. WriteTo produces a standard .pb.gz profile that go tool pprof reads with no special flags. Used by the standard library for goroutine, threadcreate, block, mutex, heap.

8. Profile labels¶

Labels are key→value strings attached to CPU samples. They let you slice a profile by tenant, request path, route, or any other dimension you choose.

ctx := pprof.WithLabels(r.Context(), pprof.Labels(
    "route", routeName,
    "tenant", tenantID,
))
pprof.Do(ctx, pprof.Labels(), func(ctx context.Context) {
    handle(ctx, r)
})

In the shell:

tagfocus=route=/api/v1/orders
tagignore=tenant=internal

Labels also propagate to descendant goroutines spawned with pprof.Do. They do not propagate via go fn() unless you explicitly call pprof.SetGoroutineLabels(ctx) inside the new goroutine.

Only CPU, block, and mutex profiles carry labels; the heap profile does not.

9. Profile format¶

pprof profiles are gzipped protobuf messages defined by profile.proto. Top-level fields:

The format is the same for cpu, heap, block, mutex, goroutine, and custom profiles — only sample_type differs. That's why one tool drives all of them.

To dump a profile without rendering:

go tool pprof -raw cpu.pb.gz | less
go tool pprof -proto cpu.pb.gz > cpu.proto  # textual proto

10. Combining and diffing¶

# straight merge: union of samples with values added
go tool pprof prof1.pb.gz prof2.pb.gz prof3.pb.gz

# diff: show what changed
go tool pprof -base=before.pb.gz after.pb.gz
go tool pprof -diff_base=before.pb.gz after.pb.gz

-base subtracts and reports the positive delta; -diff_base subtracts and reports both positive and negative (red = new cost, green = saved cost in the web UI).

The two profiles must have the same sample_type (you cannot diff a cpu against an inuse_space).

11. Symbolization and source¶

pprof resolves addresses to function names using the mapping records inside the profile. For a Go binary built without -ldflags="-s -w", symbols are embedded. If you stripped symbols, supply the original binary explicitly:

go tool pprof /path/to/binary http://host:6060/debug/pprof/heap

For list to show source code, the source paths inside the profile (function.filename) must exist on the local filesystem with the same absolute path. Use -trim_path=PATH to remove leading directories, or -source_path=PATH to add search roots.

12. Flags reference¶

13. Defaults that bite¶

14. Non-goals / limitations¶

• pprof cannot show scheduling latency, syscall blocking sequences, or goroutine wake-up causality — that's what go tool trace is for.
• A CPU profile only sees on-CPU time. Goroutines waiting on I/O or channels are absent (use goroutine and block profiles).
• Heap profiles are sampled; do not use them for exact accounting (see Bug 12 in find-bug.md).
• Profile labels do not attach to heap or goroutine profiles, only CPU/block/mutex.
• Diffing requires identical sample_type columns.

15. Related references¶

• pprof README: https://github.com/google/pprof/blob/main/doc/README.md
• runtime/pprof API: https://pkg.go.dev/runtime/pprof
• net/http/pprof handler set: https://pkg.go.dev/net/http/pprof
• Profile proto: https://github.com/google/pprof/blob/main/proto/profile.proto
• Continuous profiling tools: Pyroscope (https://pyroscope.io), Parca (https://www.parca.dev), GCP Cloud Profiler (https://cloud.google.com/profiler)