From 0c27e036bc45153db882dda1784ccdbef7bd0e55 Mon Sep 17 00:00:00 2001
From: Akshay Shah <shah@uber.com>
Date: Mon, 11 Dec 2017 15:24:43 -0800
Subject: [PATCH] Rename ObserveInt to IncBucket

Rename histograms' `ObserveInt` method to clarify that this is a
low-level API that bypasses the typical duration-centered `Observe` API.
Adjust docs to clarify the relationship between units, buckets,
`Observe`, and `IncBucket`.
---
 example_test.go   |  3 ++-
 histogram.go      | 11 ++++++-----
 histogram_test.go |  4 ++--
 nop_test.go       |  2 +-
 spec.go           |  5 +++--
 5 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/example_test.go b/example_test.go
index 5f69638..919e5e3 100644
--- a/example_test.go
+++ b/example_test.go
@@ -138,7 +138,8 @@ func ExampleHistogram() {
 	if err != nil {
 		panic(err)
 	}
-	h.Observe(37 * time.Millisecond)
+	h.Observe(37 * time.Millisecond) // increments bucket with upper bound 50
+	h.IncBucket(37)                  // also increments bucket with upper bound 50
 }
 
 func ExampleHistogramVector() {
diff --git a/histogram.go b/histogram.go
index 7032dff..ae4f900 100644
--- a/histogram.go
+++ b/histogram.go
@@ -95,17 +95,18 @@ func newHistogram(m metadata, unit time.Duration, uppers []int64) *Histogram {
 
 // Observe finds the correct bucket for the supplied duration and increments
 // its counter. This is purely a convenience - it's equivalent to dividing the
-// duration by the histogram's unit and calling ObserveInt directly.
+// duration by the histogram's unit and calling IncBucket directly.
 func (h *Histogram) Observe(d time.Duration) {
 	if h == nil {
 		return
 	}
-	h.ObserveInt(int64(d / h.unit))
+	h.IncBucket(int64(d / h.unit))
 }
 
-// ObserveInt finds the correct bucket for the supplied integer and increments
-// its counter.
-func (h *Histogram) ObserveInt(n int64) {
+// IncBucket bypasses the time-based Observe API and increments a histogram
+// bucket directly. It finds the correct bucket for the supplied value and
+// adds one to its counter.
+func (h *Histogram) IncBucket(n int64) {
 	if h == nil {
 		return
 	}
diff --git a/histogram_test.go b/histogram_test.go
index cac456b..c79e774 100644
--- a/histogram_test.go
+++ b/histogram_test.go
@@ -59,9 +59,9 @@ func TestHistogram(t *testing.T) {
 		require.NoError(t, err, "Unexpected construction error.")
 
 		h.Observe(-1)
-		h.ObserveInt(0)
+		h.IncBucket(0)
 		h.Observe(10)
-		h.ObserveInt(75)
+		h.IncBucket(75)
 		h.Observe(150)
 
 		snap := root.Snapshot()
diff --git a/nop_test.go b/nop_test.go
index 66a8ded..22328e1 100644
--- a/nop_test.go
+++ b/nop_test.go
@@ -117,7 +117,7 @@ func assertNopGaugeVector(t testing.TB, vec *GaugeVector) {
 func assertNopHistogram(t testing.TB, h *Histogram) {
 	assert.NotPanics(t, func() {
 		h.Observe(time.Second)
-		h.ObserveInt(42)
+		h.IncBucket(42)
 	}, "Unexpected panic using no-op histgram.")
 }
 
diff --git a/spec.go b/spec.go
index 30cc777..974a6eb 100644
--- a/spec.go
+++ b/spec.go
@@ -76,8 +76,9 @@ type HistogramSpec struct {
 	// exposed as 1000. Typically, the unit should also be part of the metric
 	// name.
 	Unit time.Duration
-	// Upper bounds (inclusive) for the histogram buckets. A catch-all bucket
-	// for large observations is automatically created, if necessary.
+	// Upper bounds (inclusive) for the histogram buckets in terms of the unit.
+	// A catch-all bucket for large observations is automatically created, if
+	// necessary.
 	Buckets []int64
 }