What does running a Go binary with GODEBUG=gctrace=1 print, and where does that output go?

## What `GODEBUG` is `GODEBUG` is an ordinary environment variable that the Go runtime reads once, at process start-up, before your `main` runs. Its value is a comma-separated list of `name=value` settings that switch on runtime instrumentation or change runtime behaviour. `gctrace=1` is one of those settings. Because it is read from the environment, it applies to any Go binary that is already built — you do not recompile, you do not import anything, and you do not add a line of code. That property is the whole reason this is the first diagnostic reached for in production: you can set it on a container, restart the process, and see collector behaviour within seconds. ## What it emits With `gctrace=1` set, the runtime writes exactly one line to **standard error** each time a garbage-collection cycle completes. Nothing is written per allocation, per second, or per object — the unit is the completed cycle. A short program that collects rarely produces a handful of lines; a program allocating hard can produce hundreds per second, which is worth knowing before you turn it on in a hot service. A line looks roughly like this: ``` gc 47 @12.043s 3%: 0.11+5.8+0.09 ms clock, 0.9+1.4/4.2/0+0.7 ms cpu, 42->44->21 MB, 43 MB goal, 1 MB stacks, 0 MB globals, 8 P ``` Reading left to right: `gc 47` is the cycle number, counting from the start of the process. `@12.043s` is how long the program had been running when the cycle finished. `3%` is the share of the program's total CPU time spent in garbage collection since start-up. The `ms clock` group is the wall-clock time of the cycle's phases, and the `ms cpu` group is the CPU time of the same work summed across processors. The `42->44->21 MB` triple is the heap size when the cycle started, the heap size when it ended, and the live heap that survived marking. `43 MB goal` is the heap size the collector was aiming to finish under. The `stacks` and `globals` figures report how much scannable goroutine-stack and global-variable memory there was. `8 P` is the number of logical processors the runtime was using. If a cycle was triggered by an explicit `runtime.GC()` call rather than by allocation, the line ends with `(forced)`. That single word is often the answer to "why is this service collecting so often" — some library or start-up path is forcing collections. ## Standard error, not standard output The runtime writes these lines directly to file descriptor 2. It does not go through the `log` package, your logger, or any writer you configured, so redirecting your program's own logging does not capture or suppress it. Standard error is the right channel: your program's real output on standard output — JSON, CSV, a rendered report, data piped into another tool — stays uncorrupted, while log collectors that capture both streams still pick the trace up. In practice you run something like `GODEBUG=gctrace=1 ./collector 2>gc.log` and analyse `gc.log` separately. ## What it costs, and what it is not The collector does the same work either way; the only added cost is formatting and writing a short line per cycle. On a service that collects a few times a second that is negligible. On one that collects hundreds of times a second the log volume itself becomes the problem, so it is normal to enable it for a bounded window rather than permanently. It is important to be clear about what a gctrace line is *not*. It is a summary of collector activity, not a profile: it tells you how much memory survived a cycle, but never *which* code allocated it or *which* objects are being retained. Finding allocation sites is a separate exercise with separate tools. gctrace answers questions of shape and trend — is the live heap growing, are cycles getting more frequent, is collection eating a rising share of CPU — and it answers them without changing the program. ## How it is typically used The useful reading is almost never a single line. You capture a stretch of lines and look at how the numbers move: a live heap that climbs cycle after cycle, a cumulative CPU percentage that keeps rising, cycles crowding closer together in the `@…s` timestamps. One line on its own tells you the state of one moment; the series tells you the story.