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 bc2e088..9d3611b 100644
--- a/src/runtime/metrics/description.go
+++ b/src/runtime/metrics/description.go
@@ -58,7 +58,7 @@
},
{
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 @@
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 e340f3d..f58cdcd 100644
--- a/src/runtime/metrics/doc.go
+++ b/src/runtime/metrics/doc.go
@@ -48,7 +48,7 @@
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 @@
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
