Performance and Diagnostics

Open a file, call runtime/pprof.StartCPUProfile(f), run the workload, then call StopCPUProfile before exiting. Stop flushes the buffered samples; without it the file is unusable. Inside tests, go test -cpuprofile does the same thing.

A blank import of net/http/pprof runs the package's init, which registers /debug/pprof handlers on http.DefaultServeMux. It starts no listener of its own, so the routes are reachable only if some server actually serves that mux.

top ranks functions by their share of a profile's samples. flat counts samples taken inside that function's own code; cum counts those plus everything it called. A wrapper has a tiny flat and a huge cum.

Go's block profile records the waiting goroutine's stack for any synchronisation wait — channels, select, mutex acquisition, WaitGroup. The mutex profile records contention on sync.Mutex and sync.RWMutex from the holder's side, attributing the waiters' delay to the unlock that released the lock.

inuse_space is memory still live at the moment of the snapshot; alloc_space is every byte allocated since the process started, freed or not. One profile file carries both, and go tool pprof -sample_index chooses which you look at.

Scheduler wait is time the goroutine was runnable but not running: it had work to do and sat queued, waiting for one of the GOMAXPROCS logical processors to pick it up. It is queueing delay, not blocking.

Mark assist is garbage-collection marking work done by an application goroutine itself, charged in proportion to how much it allocated during a collection cycle. Allocation-heavy goroutines pay it, and it lands directly in their latency.

The timeline in go tool trace plots wall-clock time horizontally, one row per P (Go's scheduler slot), showing which goroutine ran where, plus GC and heap rows. The same page serves goroutine analysis, blocking profiles, scheduler latency, and minimum mutator utilization.

Go's execution tracer records every traced runtime event with a timestamp — goroutine lifecycle, block reasons, syscalls, scheduler and GC phases — rather than sampling. That exhaustiveness makes files grow with activity, so captures stay short.

A runtime/trace task is a logical operation that may span goroutines: NewTask returns a context carrying it, and Task.End closes it. A region is one interval inside a single goroutine, ended by the goroutine that started it.

Every user goroutine is parked waiting on another goroutine, with nothing runnable, no armed timer and no thread in a system call. Progress is provably impossible, so the runtime dumps every goroutine stack and exits.

The process has hit its RLIMIT_NOFILE ceiling on open file descriptors. Every socket, file and open HTTP response body costs one, so the cause is almost always a resource opened on some code path and never closed.

Import net/http/pprof for its side effect and serve HTTP on a debug port, then fetch /debug/pprof/goroutine?debug=2. That prints the full current stack of every goroutine in the process, one block each.

An inuse_space heap profile counts only live Go heap objects, sampled as of the last completed garbage collection. RSS counts every physical page the kernel has given the whole process, including freed-but-retained heap spans, goroutine stacks and runtime structures.

runtime.NumGoroutine counts goroutines only, never OS threads. For the thread count read the /sched/threads:threads gauge from runtime/metrics, run the process with GODEBUG=schedtrace=1000, or ask the operating system, for example /proc/<pid>/status on Linux.

By default a Go crash prints a stack for the goroutine that panicked. GOTRACEBACK=all makes the runtime print a stack for every user-created goroutine instead. It is an environment variable, so it costs a restart, not a rebuild.

Go's compiler keeps locals in registers and inlines small calls, so the variable and the stack frame a debugger looks for do not exist at runtime. Rebuild with go build -gcflags="all=-N -l" to disable optimisation and inlining before stepping.

Call runtime/debug.Stack() inside the deferred function. It returns the calling goroutine's formatted stack trace as a byte slice, still containing the frames that panicked. debug.PrintStack() does the same but writes straight to standard error.

GODEBUG is an environment variable the Go runtime reads when the process starts, so you set it in whatever launches the binary: GODEBUG=gctrace=1 ./job. It holds a comma-separated list of name=value settings and needs no code change.

An untrapped SIGQUIT is fatal to a Go process: the runtime prints a header naming the signal, then a stack trace for every goroutine, and the process then dies. It is a one-shot snapshot, not something the process survives.

GOGC sets how much the heap may grow between garbage collections, as a percentage of the live data kept after the last one. The default, 100, lets the heap roughly double before the next collection starts.

GOMAXPROCS caps how many goroutines run Go code simultaneously. Since Go 1.25 on Linux its default is the lower of the machine's usable logical CPUs and the container's cgroup CPU limit; older releases looked only at the CPU count.

GOMEMLIMIT sets a target ceiling on the total memory the Go runtime manages, so the garbage collector runs more often as usage approaches it. It is soft: the runtime never refuses an allocation, so a program can still exceed it.

A collection cycle's cost tracks live data, not garbage, so quadrupling the growth allowance runs about a quarter as many cycles for the same allocation rate. The price is the heap the process holds between cycles, which grows roughly fourfold.

GOMEMLIMIT governs only memory the Go runtime manages, and it is a target rather than a cap. The binary, cgo allocations and mapped files sit outside it, so an equal setting leaves no headroom.

Run go test -bench with -count several times on each revision, saving the output to old.txt and new.txt, then run benchstat old.txt new.txt. benchstat pairs benchmarks by name and prints the percent change with a p-value.

Two things: it inlines hot callees it would otherwise judge too expensive, and it devirtualizes hot indirect calls by emitting a direct call to the dominant concrete type behind a type check, with the original indirect call as the fallback. Cold code is left alone.

Run go build -gcflags=-m ./... or go test -gcflags=-m. The compiler prints its inlining and escape decisions to stderr: can inline, inlining call to, cannot inline, moved to heap. Use -m=2 for more detail.

Save a pprof CPU profile as a file named default.pgo in the main package's directory. The go command defaults to -pgo=auto, so build, run, install and test pick that file up with no flag. Use -pgo=off to opt out.

The p-value is the chance of seeing a difference this large if both revisions performed the same, and n is the samples per side. A ~ means the difference was not significant at 95% confidence, not that the two are equal.