From 3e50eddd64a70c22d6c5c50fc6062b5ad5192280 Mon Sep 17 00:00:00 2001
From: beorn7 <beorn@soundcloud.com>
Date: Thu, 19 Feb 2015 12:40:29 +0100
Subject: [PATCH] Do not count the +Inf bucket for bucket creation.

Add explanation for DefBuckets.
---
 prometheus/examples_test.go  |  2 +-
 prometheus/histogram.go      | 34 ++++++++++++++++++----------------
 prometheus/histogram_test.go |  4 ++--
 3 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/prometheus/examples_test.go b/prometheus/examples_test.go
index 64139a8..a82d32c 100644
--- a/prometheus/examples_test.go
+++ b/prometheus/examples_test.go
@@ -457,7 +457,7 @@ func ExampleHistogram() {
 	temps := prometheus.NewHistogram(prometheus.HistogramOpts{
 		Name:    "pond_temperature_celsius",
 		Help:    "The temperature of the frog pond.", // Sorry, we can't measure how badly it smells.
-		Buckets: prometheus.LinearBuckets(20, 5, 6),  // 6 buckets, each 5 centigrade wide.
+		Buckets: prometheus.LinearBuckets(20, 5, 5),  // 5 buckets, each 5 centigrade wide.
 	})
 
 	// Simulate some observations.
diff --git a/prometheus/histogram.go b/prometheus/histogram.go
index 1d3cfb1..a02fd53 100644
--- a/prometheus/histogram.go
+++ b/prometheus/histogram.go
@@ -47,23 +47,25 @@ type Histogram interface {
 	Observe(float64)
 }
 
-// DefBuckets are the default Histogram buckets. Most likely, you want to define
-// buckets customized to your use case.
+// DefBuckets are the default Histogram buckets. The default buckets are
+// tailored to broadly measure response time in seconds for a typical online
+// serving system. Most likely, however, you will be required to define buckets
+// customized to your use case.
 var (
 	DefBuckets = []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10}
 )
 
 // LinearBuckets creates 'count' buckets, each 'width' wide, where the lowest
-// bucket has an upper bound of 'start'. The final +Inf bucket is counted
-// towards the total 'count', but not included in the returned slice. The
-// returned slice is meant to be used for the Buckets field of HistogramOpts.
+// bucket has an upper bound of 'start'. The final +Inf bucket is not counted
+// and not included in the returned slice. The returned slice is meant to be
+// used for the Buckets field of HistogramOpts.
 //
-// The function panics if 'count' is less than 2.
+// The function panics if 'count' is zero or negative.
 func LinearBuckets(start, width float64, count int) []float64 {
-	if count < 2 {
-		panic("LinearBuckets needs a count > 1")
+	if count < 1 {
+		panic("LinearBuckets needs a positive count")
 	}
-	buckets := make([]float64, count-1)
+	buckets := make([]float64, count)
 	for i := range buckets {
 		buckets[i] = start
 		start += width
@@ -73,15 +75,15 @@ func LinearBuckets(start, width float64, count int) []float64 {
 
 // ExponentialBuckets creates 'count' buckets, where the lowest bucket has an
 // upper bound of 'start' and each following bucket's upper bound is 'factor'
-// times the previous bucket's upper bound. The final +Inf bucket is counted
-// towards the total 'count', but not included in the returned slice. The
-// returned slice is meant to be used for the Buckets field of HistogramOpts.
+// times the previous bucket's upper bound. The final +Inf bucket is not counted
+// and not included in the returned slice. The returned slice is meant to be
+// used for the Buckets field of HistogramOpts.
 //
-// The function panics if 'count' is less than 2, if 'start' is 0 or negative,
+// The function panics if 'count' is 0 or negative, if 'start' is 0 or negative,
 // or if 'factor' is less than or equal 1.
 func ExponentialBuckets(start, factor float64, count int) []float64 {
-	if count < 2 {
-		panic("ExponentialBuckets needs a count > 1")
+	if count < 1 {
+		panic("ExponentialBuckets needs a positive count")
 	}
 	if start <= 0 {
 		panic("ExponentialBuckets needs a positive start value")
@@ -89,7 +91,7 @@ func ExponentialBuckets(start, factor float64, count int) []float64 {
 	if factor <= 1 {
 		panic("ExponentialBuckets needs a factor greater than 1")
 	}
-	buckets := make([]float64, count-1)
+	buckets := make([]float64, count)
 	for i := range buckets {
 		buckets[i] = start
 		start *= factor
diff --git a/prometheus/histogram_test.go b/prometheus/histogram_test.go
index e4ed07d..855af46 100644
--- a/prometheus/histogram_test.go
+++ b/prometheus/histogram_test.go
@@ -304,13 +304,13 @@ func getCumulativeCounts(vars []float64) []uint64 {
 }
 
 func TestBuckets(t *testing.T) {
-	got := LinearBuckets(-15, 5, 7)
+	got := LinearBuckets(-15, 5, 6)
 	want := []float64{-15, -10, -5, 0, 5, 10}
 	if !reflect.DeepEqual(got, want) {
 		t.Errorf("linear buckets: got %v, want %v", got, want)
 	}
 
-	got = ExponentialBuckets(100, 1.2, 4)
+	got = ExponentialBuckets(100, 1.2, 3)
 	want = []float64{100, 120, 144}
 	if !reflect.DeepEqual(got, want) {
 		t.Errorf("linear buckets: got %v, want %v", got, want)