Execution Traces
Purpose and Scope
Execution traces are the Go toolchain’s timeline-oriented view into a running program. Where a CPU or heap profile summarizes where time or memory went, a trace keeps event ordering visible so a developer can inspect goroutine scheduling, blocking, syscalls, network waits, and related runtime activity over time. This page explains the repository-backed entry point for working with those traces through the bundled command, the supported command-line modes, and the browser viewer assets that make the interactive view possible. It is intended for readers who already know how to run Go tests and want to move from a trace file to actionable diagnostic output.
Sources: src/cmd/trace/main.go
The command documented here is the tool invoked as go tool trace. Its own usage text starts from a trace file produced by go test with the trace flag, then offers two primary ways to consume that file: open an HTTP-served browser UI, or generate a profile-like report from the trace. The same executable also has debug modes for inspecting raw or processed trace data, which are useful when diagnosing trace format or tool behavior rather than application performance. Older trace files are handled with an optional binary argument for compatibility with Go 1.5 and Go 1.6-era traces.
Sources: src/cmd/trace/main.go
Relevant Source Files
- src/cmd/trace/main.go — Implements the go tool trace command entry point, usage text, flags, argument handling, trace-file opening, profile generation mode, and debug-mode dispatch.
- src/internal/trace/traceviewer/static/README.md — Documents the embedded Chrome Catapult trace viewer resources, how those resources were generated or copied, and the licenses for the bundled viewer and Web Components helper.
Command Workflow
A typical trace workflow begins outside this command by producing a trace file during a test run. The usage string shows the canonical capture command as go test with a trace output file and a package argument. Once that file exists, the developer runs go tool trace with the trace file, and the command parses flags before choosing a viewing, profiling, or debug path. This keeps capture and analysis separate: the test command records runtime events, while the trace tool decides whether to serve an interactive UI or transform the same events into another diagnostic representation.
Sources: src/cmd/trace/main.go
The argument rules are intentionally narrow. With one positional argument, the command treats it as the trace file. With two positional arguments, it treats the first as a program binary and the second as the trace file. The source comments explain why: Go 1.7 traces embed symbol information and do not require the binary, but the command still optionally accepts a binary for older Go 1.5 traces. Any other argument count prints the usage text and exits. This design lets modern users follow the short command while preserving a migration path for historical trace artifacts.
Sources: src/cmd/trace/main.go
After parsing the command line, the command opens the named trace file, defers closing it, and stats it to learn its size. That size is then passed into parsing for profile-generation mode. Errors at these early stages are fatal because the rest of the tool depends on the trace stream being readable and correctly identified. This is a useful operational detail: if go tool trace fails before opening a browser, first confirm that the path names the trace file produced by the test run and that the user running the tool can read it.
Sources: src/cmd/trace/main.go
API Components and Flags
The public interface of this page is command-line oriented rather than package oriented. The usage text exposes three main flags. The http flag selects the HTTP server listen address, with a default of localhost on an automatically selected port. The pprof flag switches from the interactive viewer to profile emission. The debug flag prints diagnostic information and exits. The command also records telemetry counters for invocations and flag use, but that is an implementation signal rather than something callers configure through the trace file itself.
Sources: src/cmd/trace/main.go
| Component | Public spelling | Behavior |
|---|---|---|
| Trace capture example | go test -trace=trace.out pkg | Produces a trace file to pass to the trace tool. |
| Interactive view | go tool trace [flags] [pkg.test] trace.out | Serves a browser-based trace UI. |
| Profile mode | -pprof=TYPE | Emits a pprof-like profile instead of opening the viewer. |
| HTTP address | -http=addr | Chooses the HTTP server listen address, for example a local port. |
| Debug mode | -d=mode | Prints debug information for wire, parsed, or footprint modes. |
Profile mode supports four named profile types. Network blocking, synchronization blocking, syscall blocking, and scheduler latency are selected with the values net, sync, syscall, and sched. In this mode the command parses the trace, chooses the matching profile computation, builds a profile through the trace viewer support package, and writes the result to standard output. An unknown profile type is treated as an error. This makes profile mode well suited for scripts or command pipelines where opening a browser is not appropriate but a profile-like artifact is still useful.
Sources: src/cmd/trace/main.go
Interactive Viewer and Static Assets
When the tool is used in its browser-oriented mode, the trace UI is backed by embedded static resources derived from Chrome’s Catapult trace viewer. The static asset README identifies the Go execution trace UI as embedding Chrome’s trace viewer for go tool trace, and it records the specific Catapult revision used for the current resources. That documentation matters because the UI is not a small handwritten page local to this command; it is a bundled copy of a larger viewer ecosystem adapted for Go’s trace format and served by the toolchain.
Sources: src/internal/trace/traceviewer/static/README.md
The command usage text sets an expectation about browser support. The profile pages available when launching the tool work on every browser, but the trace viewer page itself comes from the Chrome or Chromium project and is only actively tested there. Developers should interpret UI problems accordingly. If profile output works but the visual trace page behaves strangely in another browser, retrying in Chrome or Chromium is the first practical step before assuming the trace file is corrupt or the Go command has failed.
Sources: src/cmd/trace/main.go, src/internal/trace/traceviewer/static/README.md
The static asset README also documents maintenance tasks for the embedded viewer. It describes generating trace_viewer_full.html with Catapult’s vulcanize_trace_viewer command using a full configuration, notes that the lean configuration would be smaller but was broken at the time of the note, and explains that webcomponents.min.js is copied from Catapult’s Polymer Web Components dependency. These instructions are contributor-facing, but they help users understand why the repository contains large prebuilt browser assets and why updating the viewer is a deliberate process rather than an incidental file edit.
Sources: src/internal/trace/traceviewer/static/README.md
Networking, Security, and Operational Notes
The listen-address behavior is worth reading carefully when using go tool trace on shared machines. The usage text says that when only a port is supplied to the http flag, such as a colon followed by a port number, the tool listens only on localhost. To listen on all addresses, the user must explicitly supply an unspecified address such as the all-interfaces IPv4 address with that port. This default favors local inspection and reduces accidental exposure of trace data, while still allowing deliberate remote access in controlled environments.
Sources: src/cmd/trace/main.go
Trace files can reveal detailed timing, goroutine names, stack information, and application behavior. The command source does not frame this as an access-control system; it is a local diagnostic tool that starts an HTTP server for convenience. Treat the trace file and the served viewer as sensitive diagnostic material, especially when traces are collected from production-like workloads. Prefer the default local binding during routine investigation, and choose an all-address listen value only when you have an explicit reason and a network boundary that matches your organization’s debugging practices.
Sources: src/cmd/trace/main.go
Next Steps
Start with a small, reproducible workload and collect a trace through go test before moving to larger programs. Open the resulting file with the browser viewer when you need timeline context, and use the pprof-like modes when you want a compact blocking or latency profile suitable for comparison or automation. If you are contributing to the trace viewer itself, read the static asset README before updating embedded HTML or JavaScript resources, because those files are tied to Catapult generation steps and external licenses. For adjacent diagnostics, continue with pages on pprof, diagnostics, testing, and runtime performance tooling.