runtime,runtime/metrics: use explicit histogram boundaries

This change modifies the semantics of
runtime/metrics.Float64Histogram.Buckets to remove implicit buckets to
that extend to positive and negative infinity and instead defines all
bucket boundaries as explicitly listed.

Bucket boundaries remain the same as before except
/gc/heap/allocs-by-size:objects and /gc/heap/frees-by-size:objects no
longer have a bucket that extends to negative infinity.

This change simplifies the Float64Histogram API, making it both easier
to understand and easier to use.

Also, add a test for allocs-by-size and frees-by-size that checks them
against MemStats.

Fixes #43443.

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

1 files changed, 16 insertions, 13 deletions

diff --git a/src/runtime/metrics/histogram.go b/src/runtime/metrics/histogram.go
index e1364e1e26..956422bf84 100644
--- a/src/runtime/metrics/histogram.go
+++ b/src/runtime/metrics/histogram.go
@@ -6,25 +6,28 @@ package metrics
 
 // Float64Histogram represents a distribution of float64 values.
 type Float64Histogram struct {
-	// Counts contains the weights for each histogram bucket. The length of
-	// Counts is equal to the length of Buckets (in the metric description)
-	// plus one to account for the implicit minimum bucket.
+	// Counts contains the weights for each histogram bucket.
 	//
-	// Given N buckets, the following is the mathematical relationship between
-	// Counts and Buckets.
-	// count[0] is the weight of the range (-inf, bucket[0])
-	// count[n] is the weight of the range [bucket[n], bucket[n+1]), for 0 < n < N-1
-	// count[N-1] is the weight of the range [bucket[N-1], inf)
+	// Given N buckets, Count[n] is the weight of the range
+	// [bucket[n], bucket[n+1]), for 0 <= n < N.
 	Counts []uint64
 
-	// Buckets contains the boundaries between histogram buckets, in increasing order.
+	// Buckets contains the boundaries of the histogram buckets, in increasing order.
 	//
-	// Because this slice contains boundaries, there are len(Buckets)+1 counts:
-	// a count for all values less than the first boundary, a count covering each
-	// [slice[i], slice[i+1]) interval, and a count for all values greater than or
-	// equal to the last boundary.
+	// Buckets[0] is the inclusive lower bound of the minimum bucket while
+	// Buckets[len(Buckets)-1] is the exclusive upper bound of the maximum bucket.
+	// Hence, there are len(Buckets)-1 counts. Furthermore, len(Buckets) != 1, always,
+	// since at least two boundaries are required to describe one bucket (and 0
+	// boundaries are used to describe 0 buckets).
+	//
+	// Buckets[0] is permitted to have value -Inf and Buckets[len(Buckets)-1] is
+	// permitted to have value Inf.
 	//
 	// For a given metric name, the value of Buckets is guaranteed not to change
 	// between calls until program exit.
+	//
+	// This slice value is permitted to alias with other Float64Histograms' Buckets
+	// fields, so the values within should only ever be read. If they need to be
+	// modified, the user must make a copy.
 	Buckets []float64
 }