Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add float histograms and gauge histograms to proto spec #58

Merged
merged 2 commits into from Jun 29, 2022

Commits on Jun 14, 2022

  1. Add float histograms and gauge histograms to proto spec

    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 <beorn@grafana.com>
    beorn7 committed Jun 14, 2022
    Copy the full SHA
    8171e83 View commit details
    Browse the repository at this point in the history

Commits on Jun 19, 2022

  1. Explain Span layout better

    Signed-off-by: beorn7 <beorn@grafana.com>
    beorn7 committed Jun 19, 2022
    Copy the full SHA
    0da3265 View commit details
    Browse the repository at this point in the history