How do you capture a Go execution trace from a running program or a test, and how do you open it?

A Go **execution trace** is a recording of what the Go runtime did over a window of wall-clock time: when each goroutine was created, started running, blocked, was unblocked and finished; when a P (a scheduler slot for running Go code) picked work up or went idle; when goroutines entered and left syscalls; and when the garbage collector moved between its phases. It is a different artefact from a profile. A CPU profile answers "where did the time go, aggregated over the run"; an execution trace answers "what was happening at 10:42:03.418, and what was each goroutine waiting for". ## The three ways to capture one **1. From inside the program — `runtime/trace`.** `trace.Start(w io.Writer) error` turns the tracer on and streams events to `w`; `trace.Stop()` turns it off and flushes. Wrap exactly the work you want to see: ```go f, err := os.Create("gateway.trace") if err != nil { log.Fatal(err) } if err := trace.Start(f); err != nil { log.Fatal(err) } // ... run the workload ... trace.Stop() f.Close() ``` Order matters: `trace.Stop()` before `f.Close()`, because Stop is what flushes the buffered events. If you use `defer`, remember defers run LIFO, so `defer f.Close()` written first and `defer trace.Stop()` written second gives the right order. A process that exits with the tracer still running leaves a file that ends mid-stream, and `go tool trace` will usually refuse it or show only the part it could parse. **2. From a test or benchmark — `go test -trace`.** `go test -trace=t.trace ./...` records the entire test binary run. This is the cheapest way to get a trace of a reproducible workload, and it pairs naturally with `-bench`, so you can look at a benchmark's concurrency behaviour rather than only its ns/op number. **3. From a live service — the pprof HTTP endpoint.** A program that imports `net/http/pprof` exposes `/debug/pprof/trace`, which starts the tracer, waits, stops it, and returns the bytes. The `seconds` query parameter chooses the window: `curl -o stall.trace 'http://localhost:6060/debug/pprof/trace?seconds=5'`. Without it the handler defaults to a one-second trace, which is almost always too short to be interesting. Unlike `/debug/pprof/heap`, which is an instantaneous snapshot, a trace is inherently a *window*, which is why it takes a duration. Only one execution trace can be running at a time in a process; asking for a second one while the first is active returns an error rather than interleaving them. ## Opening it `go tool trace stall.trace` parses the file, converts it for the viewer, prints a `http://127.0.0.1:PORT` URL and serves an interactive UI: a timeline of the recorded window plus a set of derived views. The file itself is a compact binary format — do not expect to `less` it, and do not commit it to a repository; a few seconds from a busy process can be tens of megabytes. ## What it is not It is not a sampled profile, so it will not hand you a flame graph of hot functions. It is not free — the tracer instruments the runtime, so it costs a few percent of CPU while running and produces data fast, which is why every capture path above is scoped to a bounded window rather than left on forever. And it is per-process: a trace tells you what one Go binary did, not what a distributed request did across services. ## Practical checklist - Decide the window first. Five to ten seconds of a *representative* period beats a minute of idling. - Make sure the interesting work actually happens between Start and Stop; a trace of a program's startup tells you about initialisation, not about steady state. - Keep the endpoint off public listeners if you expose it over HTTP — anyone who can reach it can force a trace and read your program's internal timing. - Save the file with the incident time in its name. Traces are only useful when you know what window they cover.