diff options
| author | Michael Anthony Knyszek <mknyszek@google.com> | 2023-06-09 19:14:55 +0000 |
|---|---|---|
| committer | Gopher Robot <gobot@golang.org> | 2023-07-05 15:21:49 +0000 |
| commit | b2215e49c79ef5078f3c1b46adc0bef6109af388 (patch) | |
| tree | 9bd3fd75efe6bfbf86f1ac0b2502356875d2b49e | |
| parent | e126572f8a91d42b86242012012d0cad4507dca8 (diff) | |
| download | go-b2215e49c79ef5078f3c1b46adc0bef6109af388.tar.gz go-b2215e49c79ef5078f3c1b46adc0bef6109af388.zip | |
runtime,runtime/metrics: clarify OS stack metrics
There are some subtle details here about measuring OS stacks in cgo
programs. There's also an expectation about magnitude in the MemStats
docs that isn't in the runtime/metrics docs. Fix both.
Fixes #54396.
Change-Id: I6b60a62a4a304e6688e7ab4d511d66193fc25321
Reviewed-on: https://go-review.googlesource.com/c/go/+/502156
Run-TryBot: Michael Knyszek <mknyszek@google.com>
Auto-Submit: Michael Knyszek <mknyszek@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Michael Pratt <mpratt@google.com>
| -rw-r--r-- | src/runtime/metrics/description.go | 18 | ||||
| -rw-r--r-- | src/runtime/metrics/doc.go | 11 | ||||
| -rw-r--r-- | src/runtime/mstats.go | 12 |
3 files changed, 33 insertions, 8 deletions
diff --git a/src/runtime/metrics/description.go b/src/runtime/metrics/description.go index aea51c7f75..745691b24f 100644 --- a/src/runtime/metrics/description.go +++ b/src/runtime/metrics/description.go @@ -339,9 +339,11 @@ var allDesc = []Description{ Kind: KindUint64, }, { - Name: "/memory/classes/heap/stacks:bytes", - Description: "Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.", - Kind: KindUint64, + Name: "/memory/classes/heap/stacks:bytes", + Description: "Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. " + + "Currently, this represents all stack memory for goroutines. It also includes all OS thread stacks in non-cgo programs. " + + "Note that stacks may be allocated differently in the future, and this may change.", + Kind: KindUint64, }, { Name: "/memory/classes/heap/unused:bytes", @@ -374,9 +376,13 @@ var allDesc = []Description{ Kind: KindUint64, }, { - Name: "/memory/classes/os-stacks:bytes", - Description: "Stack memory allocated by the underlying operating system.", - Kind: KindUint64, + Name: "/memory/classes/os-stacks:bytes", + Description: "Stack memory allocated by the underlying operating system. " + + "In non-cgo programs this metric is currently zero. This may change in the future." + + "In cgo programs this metric includes OS thread stacks allocated directly from the OS. " + + "Currently, this only accounts for one stack in c-shared and c-archive build modes, " + + "and other sources of stacks from the OS are not measured. This too may change in the future.", + Kind: KindUint64, }, { Name: "/memory/classes/other:bytes", diff --git a/src/runtime/metrics/doc.go b/src/runtime/metrics/doc.go index 5238bcea8e..5c52f78477 100644 --- a/src/runtime/metrics/doc.go +++ b/src/runtime/metrics/doc.go @@ -318,7 +318,10 @@ Below is the full list of supported metrics, ordered lexicographically. /memory/classes/heap/stacks:bytes Memory allocated from the heap that is reserved for stack space, - whether or not it is currently in-use. + whether or not it is currently in-use. Currently, this + represents all stack memory for goroutines. It also includes all + OS thread stacks in non-cgo programs. Note that stacks may be + allocated differently in the future, and this may change. /memory/classes/heap/unused:bytes Memory that is reserved for heap objects but is not currently @@ -345,6 +348,12 @@ Below is the full list of supported metrics, ordered lexicographically. /memory/classes/os-stacks:bytes Stack memory allocated by the underlying operating system. + In non-cgo programs this metric is currently zero. This may + change in the future.In cgo programs this metric includes + OS thread stacks allocated directly from the OS. Currently, + this only accounts for one stack in c-shared and c-archive build + modes, and other sources of stacks from the OS are not measured. + This too may change in the future. /memory/classes/other:bytes Memory used by execution trace buffers, structures for debugging diff --git a/src/runtime/mstats.go b/src/runtime/mstats.go index 9a247b87b5..9cdc565137 100644 --- a/src/runtime/mstats.go +++ b/src/runtime/mstats.go @@ -199,7 +199,17 @@ type MemStats struct { // StackSys is bytes of stack memory obtained from the OS. // // StackSys is StackInuse, plus any memory obtained directly - // from the OS for OS thread stacks (which should be minimal). + // from the OS for OS thread stacks. + // + // In non-cgo programs this metric is currently equal to StackInuse + // (but this should not be relied upon, and the value may change in + // the future). + // + // In cgo programs this metric includes OS thread stacks allocated + // directly from the OS. Currently, this only accounts for one stack in + // c-shared and c-archive build modes and other sources of stacks from + // the OS (notably, any allocated by C code) are not currently measured. + // Note this too may change in the future. StackSys uint64 // Off-heap memory statistics. |