In runtime.MemStats, how do HeapAlloc, HeapInuse, HeapIdle and HeapReleased differ?

## Getting the numbers `runtime.ReadMemStats(&m)` fills a `runtime.MemStats` struct with the allocator's current accounting. It takes a pointer to a struct you own rather than returning one, and it briefly stops the world so the snapshot is internally consistent — which is why it belongs on a periodic path, not in a hot loop or on every request. The struct has dozens of fields. Four of them describe the heap, and confusing them is the root of most "is this a leak" arguments. ## Two different levels of accounting The key to keeping them straight is that Go's allocator works at two levels. **Objects** are what your code allocates. **Spans** are runs of pages the runtime carves objects out of. `HeapAlloc` counts objects; `HeapInuse`, `HeapIdle` and `HeapReleased` count span memory. **`HeapAlloc`** is bytes of allocated heap objects. Two things about it surprise people. First, it rises as you allocate and falls only when the sweeper actually frees an object — so it includes objects that are already unreachable but not yet swept. Reading it at an arbitrary instant therefore overstates the live heap, sometimes considerably, and reading it right after a cycle understates the peak. Second, it is object bytes only: no goroutine stacks, no runtime metadata. `MemStats.Alloc` holds the same value. **`HeapInuse`** is bytes in spans that hold at least one object. Because a span is claimed whole for one size class, a span holding a single small object counts entirely as in-use. `HeapInuse - HeapAlloc` is therefore the free slots inside in-use spans: internal fragmentation. Ordinary programs have some; a program that allocated a huge number of objects of one size and then freed nearly all of them can have a lot. **`HeapIdle`** is bytes in spans that hold no objects at all. This memory is free from your program's point of view and available for the runtime to reuse, but the runtime still owns it. It is the field people forget, and forgetting it is how a healthy process gets mislabelled as leaking. **`HeapReleased`** is the part of that idle memory whose physical pages have actually been given back to the operating system. So `HeapIdle - HeapReleased` is the memory the runtime is holding, unused, on purpose: keeping it means the next growth spurt needs no syscall and no new mapping. ## How they fit together `HeapInuse + HeapIdle` accounts for the heap span memory the runtime holds. Above the heap, `HeapSys` is the heap memory obtained from the operating system — reserved address space, so it behaves like a high-water mark. Above that, `Sys` is the total obtained from the operating system across everything: heap, goroutine stacks (`StackSys`), collector metadata (`GCSys`), and the rest. `Sys` is the field to compare against the process's resident set size, and resident memory normally sits at or below it. The ordering that follows is worth memorising: `HeapAlloc <= HeapInuse <= HeapInuse + HeapIdle <= HeapSys <= Sys`. If someone quotes `HeapAlloc` and the RSS in the same breath and calls the difference a leak, that chain is the answer. ## Which field answers which question - *How much memory do my objects occupy right now?* — `HeapAlloc`, with the caveat that unswept garbage is included. - *Am I fragmenting?* — `HeapInuse - HeapAlloc`. - *Is the runtime sitting on memory it is not using?* — `HeapIdle - HeapReleased`. - *How much has this process taken from the kernel in total?* — `Sys`. - *How many objects, not bytes, am I holding?* — `HeapObjects`, useful when the suspicion is many small objects rather than a few large ones. ## Other fields worth knowing exist `TotalAlloc` is cumulative bytes ever allocated for heap objects; it never decreases, so its slope is an allocation-rate measure rather than a memory measure. `NumGC` counts completed cycles. `GCCPUFraction` is the same cumulative collector CPU share that appears as the percentage in a gctrace line. `NextGC` is the heap target for the coming cycle. `StackInuse` is goroutine-stack memory in use, which is where a goroutine leak shows up rather than in any heap field. ## The practical failure mode The reason to hold these four apart is that a single one of them, read alone, supports the wrong conclusion in both directions. A big `HeapAlloc` right before a cycle is not a leak. A small `HeapAlloc` next to a large resident set is not proof that everything is fine either — you have to look at `HeapIdle`, `HeapReleased` and `Sys` to know whether the memory is genuinely free inside the runtime or genuinely gone.