Skip to content

Commit

Permalink
Add float histograms and gauge histograms to proto spec
Browse files Browse the repository at this point in the history
Note that this is only an extension of the proto spec. Both generators
and consumers of the protobuf still need changes to make use of these
changes.

Gauge histograms measure current distributions. For one, they are
inspired by the GaugeHistogram type introducted by OpenMetrics, see
https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#gaugehistogram

They are also handled in the same way as OpenMetrics does it, by
using a new MetricType enum field GAUGE_HISTOGRAM, but not changing
anything else, i.e. for both regular and gauge histograms, the same
Histogram message type is used.

The other reason why we need gauge histograms comes from PromQL: If
you `rate` a histogram (which is possible with the new sparse
histograms as 1st class data type), the result is a gauge histogram. A
rate'd histogram can be created by a recording rule and then stored in
the TSDB. From there, it can be exposed by federation, so we need to
be able to represent it in the exposition format.

Float histograms are histograms where all counts (count of
observations, counts in each bucket, zero bucket count) are floating
point numbers rather than integer numbers. They are rarely needed for
direct instrumentation. Use cases are weighted histograms or timing
histograms, see kubernetes/kubernetes#109277
for a real-world example.

However, float histograms happen all the time as results of PromQL
expressions. Following the same line of argument as above, those float
histograms can end up in the TSDB via recording rules, which means
they can be exposed via federation.

Note that float histograms are implicitly supported by the original
Prometheus text format, as this format simply uses floating point
numbers for all sample values. OpenMetrics has avoided this ambiguity
and has specified integers for bucket counts and the count of
observations in a histogram, which means it needs to be extended to
support float histograms, similar to how this commit extends the
original Prometheus protobuf format.

Signed-off-by: beorn7 <[email protected]>
  • Loading branch information
beorn7 committed Jun 14, 2022
1 parent 408689d commit 8171e83
Show file tree
Hide file tree
Showing 2 changed files with 149 additions and 88 deletions.
190 changes: 119 additions & 71 deletions go/metrics.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 8171e83

Please sign in to comment.