From add45938b53114656980ecc47021b4463d9f2507 Mon Sep 17 00:00:00 2001 From: Michael Anthony Knyszek Date: Thu, 19 Nov 2020 15:01:34 +0000 Subject: [PATCH] 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 TryBot-Result: Go Bot Trust: Michael Knyszek Reviewed-by: Michael Pratt --- src/runtime/metrics/description.go | 29 +++++++++++++++++------------ src/runtime/metrics/doc.go | 23 +++++++++++++++-------- 2 files changed, 32 insertions(+), 20 deletions(-) diff --git a/src/runtime/metrics/description.go b/src/runtime/metrics/description.go index bc2e0882db..9d3611b64c 100644 --- 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 e340f3d0dd..f58cdcdd03 100644 --- 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 -- 2.48.1