What do the buf and all arguments to Go's runtime.Stack(buf, all) control?

## Signature and contract ```go func Stack(buf []byte, all bool) int ``` Three things about this contract catch people out, and all three follow from the fact that it is a runtime function designed to work even when the heap is in trouble. **It writes into your buffer.** `runtime.Stack` does not allocate a slice for you and hand it back. You supply the storage. That is deliberate: the function must be usable in situations where allocating is a bad idea, such as inside a signal-driven dump path or when you are already near a memory limit. **It returns a count, not an error.** The `int` is the number of bytes written. If the formatted trace is larger than `len(buf)`, the runtime writes what fits and stops. There is no error, no partial-write flag, and no marker in the text saying the trace was cut. A truncated trace looks exactly like a short trace, which is how people ship diagnostics that lose the frames they needed. **Detecting truncation is your job.** The convention is: if `n == len(buf)`, assume you were truncated, grow the buffer and try again. `runtime/debug.Stack` implements exactly this, and reading it is the fastest way to remember the rule: ```go func Stack() []byte { buf := make([]byte, 1024) for { n := runtime.Stack(buf, false) if n < len(buf) { return buf[:n] } buf = make([]byte, 2*len(buf)) } } ``` Note the two facts embedded there: the doubling loop, and the hardcoded `false`. `debug.Stack` is always the current goroutine only. ## What the all argument really costs With `all` false, the runtime walks one goroutine's frames — the caller's — and formats them. The goroutine is already stopped, since it is the one making the call, so nothing else in the program is disturbed. With `all` true, the output is the calling goroutine's trace followed by a trace for every other goroutine in the process. To produce a coherent snapshot the runtime has to stop the world: no goroutine may run while stacks are being walked, or the walk would read frames that are actively changing. Critically, the world stays stopped for the entire operation, formatting included, not just for a quick census. Two consequences follow directly: - **Pause time scales with goroutine count.** A program with a few dozen goroutines will not notice. A service holding tens or hundreds of thousands of goroutines can pause for a very long time on human scales, and every in-flight request pays that latency. - **Output size scales too.** Each goroutine contributes a header line and a frame list. Multiply by the goroutine count and the buffer you need is measured in megabytes, which you must either size for or accept truncation of. That combination is why `all=true` is an operator-triggered, rate-limited action rather than something a service does on a timer or on every error. ## The formatted output Each goroutine is introduced by a header naming its id and its state — running, `chan receive`, `select`, `IO wait`, `sync.Mutex.Lock`, `sleep` and so on — sometimes with how long it has been blocked. Then come frame lines in pairs: the function with its arguments as raw words, then a tab-indented file path and line number. It is the same layout the runtime prints when a program dies from an unrecovered panic, which is why it reads as familiar to anyone who has debugged Go at all. ## Choosing a buffer For the single-goroutine case, do not invent a size — call `debug.Stack()` and let the standard library's doubling loop do it. Reach for `runtime.Stack` directly only when you need `all=true`, or when you must reuse a pre-allocated buffer because you cannot afford to allocate at that moment. In the `all=true` case, size from your actual goroutine count with headroom, check `n == len(buf)`, and grow-and-retry rather than shipping a trace that quietly ends mid-goroutine. Bear in mind that each retry pays the stop-the-world cost again, so starting far too small is worse here than it is for a single goroutine.