From eab0e32ed47552cc9827b0ca23988d89f6edddc4 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Sat, 23 Nov 2019 13:04:24 +0200 Subject: [PATCH] Added docs about Histogram --- README.md | 15 +++++++++++++++ histogram.go | 12 +++++++----- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0dcb2df..6cb2305 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ * Easy to use. See the [API docs](http://godoc.org/github.com/VictoriaMetrics/metrics). * Fast. * Allows exporting distinct metric sets via distinct endpoints. See [Set](http://godoc.org/github.com/VictoriaMetrics/metrics#Set). +* Supports [easy-to-use histograms](http://godoc.org/github.com/VictoriaMetrics/metrics#Histogram), which just work without any tuning. ### Limitations @@ -39,6 +40,9 @@ var ( queueSize = metrics.NewGauge(`queue_size{queue="foobar",topic="baz"}`, func() float64 { return float64(foobarQueue.Len()) }) + + // Register histogram with a single label. + responseSize = metrics.NewHistogram(`response_size{path="/foo/bar"}`) ) // ... @@ -50,6 +54,9 @@ func requestHandler() { processRequest() // Update requestDuration summary. requestDuration.UpdateDuration(startTime) + + // Update responseSize histogram. + responseSize.Update(responseSize) } // Expose the registered metrics at `/metrics` path. @@ -86,3 +93,11 @@ exposed from your application. Just use [GetOrCreateCounter](http://godoc.org/github.com/VictoriaMetrics/metrics#GetOrCreateCounter) instead of `CounterVec.With`. See [this example](https://godoc.org/github.com/VictoriaMetrics/metrics#example-Counter--Vec) for details. + + +#### Why [Histogram](http://godoc.org/github.com/VictoriaMetrics/metrics#Histogram) buckets contain `vmrange` labels instead of `le` labels like in Prometheus histograms? + +Buckets with `vmrange` labels occupy less disk space comparing to Promethes-style buckets with `le` labels, +because `vmrange` buckets don't include counters for the previous ranges. [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) provides `prometheus_buckets` +function, which converts `vmrange` buckets to Prometheus-style buckets with `le` labels. This is useful for building heatmaps in Grafana. +Additionally, its' `histogram_quantile` function transparently handles histogram buckets with `vmrange` labels. diff --git a/histogram.go b/histogram.go index 423abde..a72e6d6 100644 --- a/histogram.go +++ b/histogram.go @@ -37,14 +37,16 @@ import ( // - and - start and end values for the given bucket // - - the number of hits to the given bucket during Update* calls. // -// Only non-zero buckets are exposed. +// Histogram buckets can be converted to Prometheus-like buckets with `le` labels +// with `prometheus_buckets(_bucket)` function in VictoriaMetrics: // -// Histogram buckets can be converted to Prometheus-like buckets in VictoriaMetrics -// with `prometheus_buckets(_bucket)`: -// -// prometheus_buckets(rate(request_duration_bucket[5m])) +// prometheus_buckets(request_duration_bucket) // // Histogram cannot be used for negative values. +// +// Time series produced by the Histogram have better compression ratio comparing to +// Prometheus histogram buckets with `le` labels, since they don't include counters +// for all the previous buckets. type Histogram struct { buckets [bucketsCount]uint64