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

@@ -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() {

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
 	}

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()

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.")
 }
 

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
 }