pprof and Profiling Tools — Specification¶

Table of Contents¶

1. Scope
2. HTTP Endpoints
3. Profile Types
4. Goroutine Debug Levels
5. runtime/pprof API Surface
6. net/http/pprof API Surface
7. runtime/trace API Surface
8. go tool pprof CLI
9. Runtime Knobs
10. Reference Tables

Scope¶

This file is the reference. It enumerates every endpoint, every profile type, every runtime knob, and every CLI flag relevant to goroutine analysis with pprof. It does not teach concepts — see junior.md through professional.md for that. Use it as a lookup.

Versions covered: Go 1.21 through 1.25.

HTTP Endpoints¶

All endpoints under /debug/pprof/. Registered automatically by import _ "net/http/pprof" on http.DefaultServeMux. Must be registered manually on custom muxes.

All debug parameters default to 0 when called by go tool pprof (which sets Accept: application/octet-stream).

Profile Types¶

Custom profiles created with pprof.NewProfile(name) are added to the registry and exposed at /debug/pprof/<name>.

Goroutine Debug Levels¶

debug=1 output structure¶

goroutine profile: total <N>
<count> @ <pc1> <pc2> ...
#       <pc>     <function>+<offset>    <file>:<line>
#       ...

<count> @ ...

debug=2 output structure¶

goroutine <id> [<state>, <duration>]:
<function>(<args>)
        <file>:<line> +<offset>
<caller>(<args>)
        ...
created by <function> in goroutine <id>
        <file>:<line> +<offset>

goroutine <id> [<state>]:
...

Goroutine states reported in debug=2¶

A duration in brackets ([chan receive, 12 minutes]) appears when the goroutine has been in that state for longer than a runtime threshold (about 1 minute). It is the single strongest leak signal.

runtime/pprof API Surface¶

package pprof

func StartCPUProfile(w io.Writer) error
func StopCPUProfile()

type Profile struct{}
func NewProfile(name string) *Profile
func Lookup(name string) *Profile
func Profiles() []*Profile

func (*Profile) Name() string
func (*Profile) Count() int
func (*Profile) Add(value any, skip int)
func (*Profile) Remove(value any)
func (*Profile) WriteTo(w io.Writer, debug int) error

func WriteHeapProfile(w io.Writer) error

type LabelSet struct{}
func Labels(args ...string) LabelSet
func WithLabels(ctx context.Context, labels LabelSet) context.Context
func Label(ctx context.Context, key string) (string, bool)
func ForLabels(ctx context.Context, f func(key, value string) bool)
func SetGoroutineLabels(ctx context.Context)
func Do(ctx context.Context, labels LabelSet, f func(context.Context))

Key facts:

• Labels(args...) takes an even number of strings (key, value, key, value, ...).
• SetGoroutineLabels overwrites all labels on the current goroutine.
• Do is the safe pattern: scoped lifetime, automatic restore.
• Labels are not propagated to spawned goroutines automatically.

net/http/pprof API Surface¶

package pprof

func Index(w http.ResponseWriter, r *http.Request)
func Cmdline(w http.ResponseWriter, r *http.Request)
func Profile(w http.ResponseWriter, r *http.Request)
func Symbol(w http.ResponseWriter, r *http.Request)
func Trace(w http.ResponseWriter, r *http.Request)
func Handler(name string) http.Handler

Handler(name) returns the handler for a named profile (goroutine, heap, etc.). Use it to register on a custom mux.

mux.Handle("/debug/pprof/goroutine", pprof.Handler("goroutine"))
mux.Handle("/debug/pprof/heap", pprof.Handler("heap"))
// etc.

The package's init() registers all routes on http.DefaultServeMux. There is no programmatic way to undo this; once imported, the routes are present.

runtime/trace API Surface¶

package trace

func Start(w io.Writer) error
func Stop()
func IsEnabled() bool

type Task struct{}
func NewTask(pctx context.Context, taskType string) (context.Context, *Task)
func (*Task) End()

type Region struct{}
func StartRegion(ctx context.Context, regionType string) *Region
func (*Region) End()
func WithRegion(ctx context.Context, regionType string, f func())

func Log(ctx context.Context, category, message string)
func Logf(ctx context.Context, category, format string, args ...any)

Behaviour notes:

• Only one trace at a time. Calling Start while a trace is running returns an error.
• Trace events are attributed to the current goroutine.
• Task and Region survive go f() only if the new goroutine continues to use the parent context.

go tool pprof CLI¶

go tool pprof [options] [binary] <profile-source>

profile-source is a file path, an HTTP URL, or http://host:port/debug/pprof/<name>.

Selected options¶

Interactive REPL commands¶

Runtime Knobs¶

Environment variables affecting profiling:

Reference Tables¶

Profile size estimates (typical)¶

CLI quick reference¶

# fetch and analyse
go tool pprof http://host:6060/debug/pprof/goroutine

# fetch, save, analyse
curl -o g.prof http://host:6060/debug/pprof/goroutine
go tool pprof g.prof

# web UI
go tool pprof -http=:9090 g.prof

# diff
go tool pprof -base before.prof after.prof

# tag filter
go tool pprof -tagfocus=tenant=acme g.prof

# CPU profile, 30 seconds
go tool pprof http://host:6060/debug/pprof/profile?seconds=30

# trace
curl -o trace.out http://host:6060/debug/pprof/trace?seconds=5
go tool trace trace.out

Label propagation matrix¶

Endpoint security checklist¶