Switch to base-2 buckets

This seem what OTel is converging towards, see
open-telemetry/oteps#149 .

I see pros and cons with base-10 vs base-2. They are discussed in
detail in that OTel PR, and the gist of the discussion is pretty much
in line with my design doc. Since the balance is easy to tip here, I
think we should go with base-2 if OTel picks base-2. This also seems
to be in agreement with several proprietary solution (see again the
discussion on that OTel PR.)

The idea to make the number of buckets per power of 2 (or formerly 10)
a power of 2 itself was also sketched out in the design doc
already. It guarantees mergeability of different resolutions. I was
undecided between making it a recommendation or mandatory. Now I think
it should be mandatory as it has the additional benefit of playing
well with OTel's plans.

This commit also addresses a number of outstanding TODOs.

Signed-off-by: beorn7 <beorn@grafana.com>

examples/random/main.go

@@ -54,10 +54,10 @@ var (
 	// normal distribution, with 20 buckets centered on the mean, each
 	// half-sigma wide.
 	rpcDurationsHistogram = prometheus.NewHistogram(prometheus.HistogramOpts{
-		Name:                    "rpc_durations_histogram_seconds",
-		Help:                    "RPC latency distributions.",
-		Buckets:                 prometheus.LinearBuckets(*normMean-5**normDomain, .5**normDomain, 20),
-		SparseBucketsResolution: 20,
+		Name:                "rpc_durations_histogram_seconds",
+		Help:                "RPC latency distributions.",
+		Buckets:             prometheus.LinearBuckets(*normMean-5**normDomain, .5**normDomain, 20),
+		SparseBucketsFactor: 1.1,
 	})
 )
 

go.mod

@@ -5,7 +5,7 @@ require (
 	github.com/cespare/xxhash/v2 v2.1.1
 	github.com/golang/protobuf v1.4.3
 	github.com/json-iterator/go v1.1.11
-	github.com/prometheus/client_model v0.2.1-0.20210403151606-24db95a3d5d6
+	github.com/prometheus/client_model v0.2.1-0.20210611125623-bbaf1cc17b15
 	github.com/prometheus/common v0.26.0
 	github.com/prometheus/procfs v0.6.0
 	golang.org/x/sys v0.0.0-20210603081109-ebe580a85c40

go.sum

@@ -24,6 +24,7 @@ github.com/gogo/protobuf v1.1.1/go.mod h1:r8qH/GZQm5c6nD/R0oafs1akxWv10x8SbQlK7a
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.5/go.mod h1:6O5/vntMXwX2lRkT1hjjk0nAC1IDOTvTlVgjlRvqsdk=
 github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
 github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
 github.com/golang/protobuf v1.4.0-rc.2/go.mod h1:LlEzMj4AhA7rCAGe4KMBDvJI+AwstrUpVNzEA03Pprs=
@@ -79,6 +80,10 @@ github.com/prometheus/client_model v0.0.0-20190129233127-fd36f4220a90/go.mod h1:
 github.com/prometheus/client_model v0.2.0/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
 github.com/prometheus/client_model v0.2.1-0.20210403151606-24db95a3d5d6 h1:wlZYx9ITBsvMO/wVoi30A36fAdRlBC130JksGGfaYl8=
 github.com/prometheus/client_model v0.2.1-0.20210403151606-24db95a3d5d6/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/prometheus/client_model v0.2.1-0.20210610213838-8831f0df144c h1:YpsmaOx/8Vx7iXSiYIz1oJX2WKYKQF59S3wdGauCxKE=
+github.com/prometheus/client_model v0.2.1-0.20210610213838-8831f0df144c/go.mod h1:LDGWKZIo7rky3hgvBe+caln+Dr3dPggB5dvjtD7w9+w=
+github.com/prometheus/client_model v0.2.1-0.20210611125623-bbaf1cc17b15 h1:l+7cw41KLeOScRk7f9Tg//xT8LAz55Kg+Fg9i0i0Cyw=
+github.com/prometheus/client_model v0.2.1-0.20210611125623-bbaf1cc17b15/go.mod h1:LDGWKZIo7rky3hgvBe+caln+Dr3dPggB5dvjtD7w9+w=
 github.com/prometheus/common v0.4.1/go.mod h1:TNfzLD0ON7rHzMJeJkieUDPYmFC7Snx/y86RQel1bk4=
 github.com/prometheus/common v0.10.0/go.mod h1:Tlit/dnDKsSWFlCLTWaA1cyBgKHSMdTB80sz/V91rCo=
 github.com/prometheus/common v0.26.0 h1:iMAkS2TDoNWnKM+Kopnx/8tnEStIfpYA0ur0xQzzhMQ=

prometheus/examples_test.go

@@ -538,8 +538,8 @@ func ExampleHistogram() {
 	//     cumulative_count: 816
 	//     upper_bound: 40
 	//   >
-	//   sb_resolution: 0
-	//   sb_zero_threshold: 1e-128
+	//   sb_schema: 0
+	//   sb_zero_threshold: 0
 	// >
 }