Prometheus compatible histograms

histogram_example_test.go

@@ -20,7 +20,7 @@ func ExampleHistogram() {
 func ExampleHistogram_vec() {
 	for i := 0; i < 3; i++ {
 		// Dynamically construct metric name and pass it to GetOrCreateHistogram.
-		name := fmt.Sprintf(`response_size_bytes{path=%q}`, "/foo/bar")
+		name := fmt.Sprintf(`response_size_bytes{path=%q, code=%q}`, "/foo/bar", 200+i)
 		response := processRequest()
 		metrics.GetOrCreateHistogram(name).Update(float64(len(response)))
 	}

prometheus_histogram.go

@@ -0,0 +1,244 @@
+package metrics
+
+import (
+	"fmt"
+	"io"
+	"math"
+	"sync"
+	"time"
+)
+
+// PrometheusHistogramDefaultBuckets is a list of the default bucket upper
+// bounds. Those default buckets are quite generic, and it is recommended to
+// pick custom buckets for improved accuracy.
+var PrometheusHistogramDefaultBuckets = []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10}
+
+// PrometheusHistogram is a histogram for non-negative values with pre-defined buckets
+//
+// Each bucket contains a counter for values in the given range.
+// Each bucket is exposed via the following metric:
+//
+// <metric_name>_bucket{<optional_tags>,le="upper_bound"} <counter>
+//
+// Where:
+//
+//   - <metric_name> is the metric name passed to NewHistogram
+//   - <optional_tags> is optional tags for the <metric_name>, which are passed to NewHistogram
+//   - <upper_bound> - upper bound of the current bucket. all samples <= upper_bound are in that bucket
+//   - <counter> - the number of hits to the given bucket during Update* calls
+//
+// Next to the bucket metrics, two additional metrics track the total number of
+// samples (_count) and the total sum (_sum) of all samples.
+//
+// <metric_name>_sum{<optional_tags>} <counter>
+// <metric_name>_count{<optional_tags>} <counter>
+type PrometheusHistogram struct {
+	// Mu guarantees synchronous update for all the counters and sum.
+	//
+	// Do not use sync.RWMutex, since it has zero sense from performance PoV.
+	// It only complicates the code.
+	mu sync.Mutex
+
+	// upperBounds and buckets are aligned by element position:
+	// upperBounds[i] defines the upper bound for buckets[i].
+	// buckets[i] contains the count of elements <= upperBounds[i]
+	upperBounds []float64
+	buckets     []uint64
+
+	// count is the counter for all observations on this histogram
+	count uint64
+
+	// sum is the sum of all the values put into Histogram
+	sum float64
+}
+
+// Reset resets previous observations in h.
+func (h *PrometheusHistogram) Reset() {
+	h.mu.Lock()
+	for i := range h.buckets {
+		h.buckets[i] = 0
+	}
+
+	h.sum = 0
+	h.count = 0
+	h.mu.Unlock()
+}
+
+// Update updates h with v.
+//
+// Negative values and NaNs are ignored.
+func (h *PrometheusHistogram) Update(v float64) {
+	if math.IsNaN(v) || v < 0 {
+		// Skip NaNs and negative values.
+		return
+	}
+	bucketIdx := -1
+	for i, ub := range h.upperBounds {
+		if v <= ub {
+			bucketIdx = i
+			break
+		}
+	}
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	h.sum += v
+	h.count++
+	if bucketIdx == -1 {
+		// +Inf, nothing to do, already accounted for in the total sum
+		return
+	}
+	h.buckets[bucketIdx]++
+}
+
+// UpdateDuration updates request duration based on the given startTime.
+func (h *PrometheusHistogram) UpdateDuration(startTime time.Time) {
+	d := time.Since(startTime).Seconds()
+	h.Update(d)
+}
+
+// NewPrometheusHistogram creates and returns new PrometheusHistogram with the given name.
+//
+// name must be valid Prometheus-compatible metric with possible labels.
+// For instance,
+//
+//   - foo
+//   - foo{bar="baz"}
+//   - foo{bar="baz",aaa="b"}
+//
+// The returned histogram is safe to use from concurrent goroutines.
+func NewPrometheusHistogram(name string) *PrometheusHistogram {
+	return defaultSet.NewPrometheusHistogram(name)
+}
+
+// NewPrometheusHistogramExt creates and returns new PrometheusHistogram with the given name and upperBounds.
+//
+// name must be valid Prometheus-compatible metric with possible labels.
+// For instance,
+//
+//   - foo
+//   - foo{bar="baz"}
+//   - foo{bar="baz",aaa="b"}
+//
+// The returned histogram is safe to use from concurrent goroutines.
+func NewPrometheusHistogramExt(name string, upperBounds []float64) *PrometheusHistogram {
+	return defaultSet.NewPrometheusHistogramExt(name, upperBounds)
+}
+
+// GetOrCreatePrometheusHistogram returns registered histogram with the given name
+// or creates a new histogram if the registry doesn't contain histogram with
+// the given name.
+//
+// name must be valid Prometheus-compatible metric with possible labels.
+// For instance,
+//
+//   - foo
+//   - foo{bar="baz"}
+//   - foo{bar="baz",aaa="b"}
+//
+// The returned histogram is safe to use from concurrent goroutines.
+//
+// Performance tip: prefer NewPrometheusHistogram instead of GetOrCreatePrometheusHistogram.
+func GetOrCreatePrometheusHistogram(name string) *PrometheusHistogram {
+	return defaultSet.GetOrCreatePrometheusHistogram(name)
+}
+
+// GetOrCreatePrometheusHistogramExt returns registered histogram with the given name and
+// upperBounds or creates new histogram if the registry doesn't contain histogram
+// with the given name.
+//
+// name must be valid Prometheus-compatible metric with possible labels.
+// For instance,
+//
+//   - foo
+//   - foo{bar="baz"}
+//   - foo{bar="baz",aaa="b"}
+//
+// The returned histogram is safe to use from concurrent goroutines.
+//
+// Performance tip: prefer NewPrometheusHistogramExt instead of GetOrCreatePrometheusHistogramExt.
+func GetOrCreatePrometheusHistogramExt(name string, upperBounds []float64) *PrometheusHistogram {
+	return defaultSet.GetOrCreatePrometheusHistogramExt(name, upperBounds)
+}
+
+func newPrometheusHistogram(upperBounds []float64) *PrometheusHistogram {
+	mustValidateBuckets(upperBounds)
+	last := len(upperBounds) - 1
+	if math.IsInf(upperBounds[last], +1) {
+		upperBounds = upperBounds[:last] // ignore +Inf bucket as it is covered anyways
+	}
+	h := PrometheusHistogram{
+		upperBounds: upperBounds,
+		buckets:     make([]uint64, len(upperBounds)),
+	}
+
+	return &h
+}
+
+func mustValidateBuckets(upperBounds []float64) {
+	if err := ValidateBuckets(upperBounds); err != nil {
+		panic(err)
+	}
+}
+
+func ValidateBuckets(upperBounds []float64) error {
+	if len(upperBounds) == 0 {
+		return fmt.Errorf("upperBounds can't be empty")
+	}
+	for i := 0; i < len(upperBounds)-1; i++ {
+		if upperBounds[i] >= upperBounds[i+1] {
+			return fmt.Errorf("upper bounds for the buckets must be strictly increasing")
+		}
+	}
+	return nil
+}
+
+// LinearBuckets returns a slice containing `count` upper bounds to be used
+// with a prometheus histogram, and whose distribution is as follows:
+// [start, start + width, start + 2 * width, ... start + (count-1) * width]
+func LinearBuckets(start, width float64, count int) []float64 {
+	if count < 1 {
+		panic("LinearBuckets needs a positive count")
+	}
+	upperBounds := make([]float64, count)
+	for i := range upperBounds {
+		upperBounds[i] = start
+		start += width
+	}
+	return upperBounds
+}
+
+func (h *PrometheusHistogram) marshalTo(prefix string, w io.Writer) {
+	cumulativeSum := uint64(0)
+	h.mu.Lock()
+	count := h.count
+	sum := h.sum
+	if count == 0 {
+		h.mu.Unlock()
+		return
+	}
+	for i, ub := range h.upperBounds {
+		cumulativeSum += h.buckets[i]
+		tag := fmt.Sprintf(`le="%v"`, ub)
+		metricName := addTag(prefix, tag)
+		name, labels := splitMetricName(metricName)
+		fmt.Fprintf(w, "%s_bucket%s %d\n", name, labels, cumulativeSum)
+	}
+	h.mu.Unlock()
+
+	tag := fmt.Sprintf("le=%q", "+Inf")
+	metricName := addTag(prefix, tag)
+	name, labels := splitMetricName(metricName)
+	fmt.Fprintf(w, "%s_bucket%s %d\n", name, labels, count)
+
+	name, labels = splitMetricName(prefix)
+	if float64(int64(sum)) == sum {
+		fmt.Fprintf(w, "%s_sum%s %d\n", name, labels, int64(sum))
+	} else {
+		fmt.Fprintf(w, "%s_sum%s %g\n", name, labels, sum)
+	}
+	fmt.Fprintf(w, "%s_count%s %d\n", name, labels, count)
+}
+
+func (h *PrometheusHistogram) metricType() string {
+	return "histogram"
+}

prometheus_histogram_example_test.go

@@ -0,0 +1,27 @@
+package metrics_test
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/VictoriaMetrics/metrics"
+)
+
+func ExamplePrometheusHistogram() {
+	// Define a histogram in global scope.
+	h := metrics.NewPrometheusHistogram(`request_duration_seconds{path="/foo/bar"}`)
+
+	// Update the histogram with the duration of processRequest call.
+	startTime := time.Now()
+	processRequest()
+	h.UpdateDuration(startTime)
+}
+
+func ExamplePrometheusHistogram_vec() {
+	for i := 0; i < 3; i++ {
+		// Dynamically construct metric name and pass it to GetOrCreateHistogram.
+		name := fmt.Sprintf(`response_size_bytes{path=%q, code=%q}`, "/foo/bar", 200+i)
+		response := processRequest()
+		metrics.GetOrCreateHistogram(name).Update(float64(len(response)))
+	}
+}