runtime/metrics: clarify memory and GC metrics documentation

Change-Id: I8940990a591a808ddd4b8613531f52453f85bde1
Reviewed-on: https://go-review.googlesource.com/c/go/+/271557
Run-TryBot: Michael Knyszek <mknyszek@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Michael Knyszek <mknyszek@google.com>
Reviewed-by: Michael Pratt <mpratt@google.com>

diff --git a/src/runtime/metrics/description.go b/src/runtime/metrics/description.go
index bc2e0882db6535032e2a63c076b54bf8c4c929a0..9d3611b64c140756298647f074abdac21750513c 100644 (file)
--- a/src/runtime/metrics/description.go
+++ b/src/runtime/metrics/description.go
@@ -58,7 +58,7 @@ var allDesc = []Description{
        },
        {
                Name:        "/gc/cycles/forced:gc-cycles",
-               Description: "Count of completed forced GC cycles.",
+               Description: "Count of completed GC cycles forced by the application.",
                Kind:        KindUint64,
                Cumulative:  true,
        },
@@ -94,28 +94,33 @@ var allDesc = []Description{
                Kind:        KindFloat64Histogram,
        },
        {
-               Name:        "/memory/classes/heap/free:bytes",
-               Description: "Memory that is available for allocation, and may be returned to the underlying system.",
-               Kind:        KindUint64,
+               Name: "/memory/classes/heap/free:bytes",
+               Description: "Memory that is completely free and eligible to be returned to the underlying system, " +
+                       "but has not been. This metric is the runtime's estimate of free address space that is backed by " +
+                       "physical memory.",
+               Kind: KindUint64,
        },
        {
                Name:        "/memory/classes/heap/objects:bytes",
-               Description: "Memory occupied by live objects and dead objects that have not yet been collected.",
+               Description: "Memory occupied by live objects and dead objects that have not yet been marked free by the garbage collector.",
                Kind:        KindUint64,
        },
        {
-               Name:        "/memory/classes/heap/released:bytes",
-               Description: "Memory that has been returned to the underlying system.",
-               Kind:        KindUint64,
+               Name: "/memory/classes/heap/released:bytes",
+               Description: "Memory that is completely free and has been returned to the underlying system. This " +
+                       "metric is the runtime's estimate of free address space that is still mapped into the process, " +
+                       "but is not backed by physical memory.",
+               Kind: KindUint64,
        },
        {
-               Name:        "/memory/classes/heap/stacks:bytes",
-               Description: "Memory allocated from the heap that is occupied by stacks.",
-               Kind:        KindUint64,
+               Name: "/memory/classes/heap/stacks:bytes",
+               Description: "Memory allocated from the heap that is reserved for stack space. Not all of it is necessarily " +
+                       "simultaneously in use, but it may not be used for any other purpose.",
+               Kind: KindUint64,
        },
        {
                Name:        "/memory/classes/heap/unused:bytes",
-               Description: "Memory that is unavailable for allocation, but cannot be returned to the underlying system.",
+               Description: "Memory that is reserved for heap objects but is otherwise not currently used to hold heap objects.",
                Kind:        KindUint64,
        },
        {

diff --git a/src/runtime/metrics/doc.go b/src/runtime/metrics/doc.go
index e340f3d0dd6f6f4d76ea56e0b811a30d9076d0d6..f58cdcdd0335cf3649d43eea318b49b6671611a4 100644 (file)
--- a/src/runtime/metrics/doc.go
+++ b/src/runtime/metrics/doc.go
@@ -48,7 +48,7 @@ Supported metrics
                Count of completed GC cycles generated by the Go runtime.
 
        /gc/cycles/forced:gc-cycles
-               Count of completed forced GC cycles.
+               Count of completed GC cycles forced by the application.
 
        /gc/cycles/total:gc-cycles
                Count of all completed GC cycles.
@@ -69,22 +69,29 @@ Supported metrics
                Distribution individual GC-related stop-the-world pause latencies.
 
        /memory/classes/heap/free:bytes
-               Memory that is available for allocation, and may be returned
-               to the underlying system.
+               Memory that is completely free and eligible to be returned to
+               the underlying system, but has not been. This metric is the
+               runtime's estimate of free address space that is backed by
+               physical memory.
 
        /memory/classes/heap/objects:bytes
                Memory occupied by live objects and dead objects that have
-               not yet been collected.
+               not yet been marked free by the garbage collector.
 
        /memory/classes/heap/released:bytes
-               Memory that has been returned to the underlying system.
+               Memory that is completely free and has been returned to
+               the underlying system. This metric is the runtime's estimate of
+               free address space that is still mapped into the process, but
+               is not backed by physical memory.
 
        /memory/classes/heap/stacks:bytes
-               Memory allocated from the heap that is occupied by stacks.
+               Memory allocated from the heap that is reserved for stack
+               space. Not all of it is necessarily simultaneously in use, but
+               it may not be used for any other purpose.
 
        /memory/classes/heap/unused:bytes
-               Memory that is unavailable for allocation, but cannot be
-               returned to the underlying system.
+               Memory that is reserved for heap objects but is otherwise not
+               currently used to hold heap objects.
 
        /memory/classes/metadata/mcache/free:bytes
                Memory that is reserved for runtime mcache structures, but