What does runtime.NumGoroutine() count, and what does it deliberately leave out?

## What is being counted Every goroutine is a runtime object — a G record holding its stack, its status and its bookkeeping. `runtime.NumGoroutine()` reads the runtime's counters for those records and returns how many currently belong to live user goroutines. The definition is narrower than "everything the runtime is doing", in two ways worth stating precisely. **Finished goroutines are not counted.** When a goroutine's function returns, its G is taken out of the live population and pushed onto a free list so a later `go` statement can reuse it without allocating. The record still exists — reuse is the point — but the count drops at once. You do not have to wait for a garbage collection to see a goroutine go away. **The runtime's own goroutines are not counted.** The collector's background mark workers, the sweeper, the scavenger, the finalizer runner and friends are flagged as system goroutines and subtracted out. This is why the classic demonstration works: a program that has started nothing of its own prints `1` — the goroutine running `main`. ## What it is blind to The number says nothing about state. Included in the same total are goroutines that are: - running on a P right now, - runnable and queued waiting for one, - blocked on a channel send or receive, a mutex, or a `select`, - sleeping in `time.Sleep`, - parked in the network poller waiting for a socket, - blocked in a system call. That is the property that trips people up. A gateway holding 50,000 idle client connections legitimately holds 50,000 goroutines, nearly all parked in the poller, using no CPU. A batch job with 12 goroutines can be pinning every core. The count is a *population*, not a *load*. The companion mistake is reading it as a thread count. Goroutines are multiplexed onto a much smaller set of OS threads; the thread number is separate and generally close to `GOMAXPROCS` plus a handful, and it is what `threads=` reports in `GODEBUG=schedtrace` output. Goroutines climbing while threads stay flat is ordinary. Threads climbing is a different investigation altogether. ## Snapshot semantics The function reads counters that other goroutines are mutating while it runs. It returns a value that was true at some instant inside the call, and by the time you print it the program may have created or retired thousands. There is no locking that makes it authoritative and none is wanted — it is meant to be cheap. Practically, that means: treat it as a sample; never assert exact equality on it while other goroutines are in flight; and when you compare two readings, compare them across a long enough gap that ordinary churn is small relative to the difference you care about. ## What it is good for Because it is cheap and needs no build flags or endpoints, `NumGoroutine` is the natural way to expose "how many goroutines does this process have" from inside the program — a gauge, a log line at shutdown, a number printed next to a health response. What it cannot do is tell you *which* goroutines or *why*. Once the number says something is wrong, you need a different instrument for the next question: `GODEBUG=schedtrace` to learn whether the population is runnable or parked, `scheddetail=1` to get a line per goroutine with its wait reason, or a full stack dump to see exactly where each one is stopped. `NumGoroutine` is the smoke alarm, not the investigation. ## A small trap in interpretation Because the count includes goroutines blocked in system calls and in the poller, a number that looks alarming can be entirely healthy for the workload — and a modest number can hide a leak if the process also creates and finishes thousands per second, so that a slowly-accumulating population is masked by churn. The number is evidence, not a verdict; it becomes conclusive only when read against what the program is supposed to have in flight.