Skip to content

feat(nh): remove experimental from native histograms #2741

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.

Sign up for GitHub

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat(nh): remove experimental from native histograms #2741

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/instrumenting/exposition_formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,14 +160,14 @@ To enable this experimental feature you must have at least version v2.26.0 and a

Earlier versions of Prometheus supported an exposition format based on [Protocol Buffers](https://developers.google.com/protocol-buffers/) (aka Protobuf) in addition to the current text-based format. With Prometheus 2.0, the Protobuf format was marked as deprecated and Prometheus stopped ingesting samples from said exposition format.

However, new experimental features were added to Prometheus where the Protobuf format was considered the most viable option. Making Prometheus accept Protocol Buffers once again.
However, new (experimental) features were added to Prometheus where the Protobuf format was considered the most viable option. Making Prometheus accept Protocol Buffers once again.

Here is a list of experimental features that, once enabled, will configure Prometheus to favor the Protobuf exposition format:
Here is a list of (experimental) features that, once enabled, will configure Prometheus to favor the Protobuf exposition format:

| feature flag | version that introduced it |
|--------------|----------------------------|
| native-histograms | 2.40.0 |
| created-timestamp-zero-ingestion | 2.50.0 |
| feature flag | Experimental | version that introduced it |
|--------------|--------------|----------------------------|
| native-histograms | no | 2.40.0 |
| created-timestamp-zero-ingestion | yes | 2.50.0 |

## Historical versions

Expand Down
28 changes: 13 additions & 15 deletions docs/specs/native_histograms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Native Histograms [EXPERIMENTAL]
title: Native Histograms
sort_rank: 1
---

Expand All @@ -8,8 +8,8 @@ They are a concept that touches almost every part of the Prometheus stack. The
first version of the Prometheus server supporting native histograms was
v2.40.0. The support had to be enabled via a feature flag
`--enable-feature=native-histograms`. (TODO: This is still the case with the
current release v2.55 and v3.00. Update this section with the stable release,
once it has happened.)
current release v2.xx and v3.xx. Update this section once native histograms are
enabled by default.)

Due to the pervasive nature of the changes related to native histograms, the
documentation of those changes and explanation of the underlying concepts are
Expand Down Expand Up @@ -319,7 +319,7 @@ If, after this optional schema conversion, the schema is still unknown to the
receiver, there are the following options:

- If a scrape (including federation) contains one or more histograms with an
unknown schema, the entiry scrape MUST fail, following the Prometheus
unknown schema, the entire scrape MUST fail, following the Prometheus
practice of avoiding incomplete scrapes.
- For any other ingestion paths (including replaying the WAL/WBL), the receiver
MAY ignore histograms with unknown schemas and SHOULD notify the user about
Expand Down Expand Up @@ -640,7 +640,6 @@ message Histogram {
google.protobuf.Timestamp created_timestamp = 15;

// Everything below here is for native histograms (also known as sparse histograms).
// Native histograms are an experimental feature without stability guarantees.

// schema defines the bucket schema. Currently, valid numbers are -4 <= n <= 8.
// They are all for base-2 bucket schemas, where 1 is a bucket boundary in each case, and
Expand Down Expand Up @@ -1549,7 +1548,7 @@ detection between two samples has happened upon ingestion, it either has to
perform another counter reset detection or it has to return a
`CounterResetHint` of `UnknownCounterReset` for the second sample.

Note that there is the possiblity of counter resets that are not detected by
Note that there is the possibility of counter resets that are not detected by
the procedure described above, namely if the counts in the reset histogram have
increased quickly enough so that the 1st sample after the counter reset has no
counts that have decreased compared to the last sample prior to the counter
Expand Down Expand Up @@ -1612,7 +1611,7 @@ is then possible in an efficient way:
the last successfully appended exemplar (which might be from the previous
scrape for the same metric).
4. The append succeeds for exemplars that would be sorted after the last
successfully appendend exemplar.
successfully appended exemplar.

Exemplars are only counted as out of order if all exemplars of an ingested
histogram would be sorted before the last successfully appended exemplar. This
Expand Down Expand Up @@ -1729,7 +1728,7 @@ schemas, linear interpolation can be seen as a misfit. While exponential
schemas primarily intend to minimize the relative error of quantile
estimations, they also benefit from a balanced usage of buckets, at least over
certain ranges of observed values. The basic assumption is that for most
practically occurring destributions, the density of observations tends to be
practically occurring distributions, the density of observations tends to be
higher for smaller observed values. Therefore, PromQL uses exponential
extrapolation for the standard schemas, which models the assumption
that dividing a bucket into two when increasing the schema number by one (i.e.
Expand Down Expand Up @@ -1918,7 +1917,7 @@ To prevent extrapolation below zero, the same heuristics is applied as for
but solely based on the count of observations. Therefore, individual buckets
might still be extrapolated below zero in some cases. An alternative could have
been to find the smallest extrapolation where neither the count nor any bucket
would be extropolated below zero. However, this does not necessarily lead to a
would be extrapolated below zero. However, this does not necessarily lead to a
better heuristics while inflicting a significant cost in complexity. In the
common and important case where the first sample in the range is a synthetic
zero sample derived from the created-at timestamp, the limited extrapolation
Expand Down Expand Up @@ -2101,7 +2100,7 @@ float values in the original histogram.
Alerts work as usual with native histograms. However, it is RECOMMENDED to
avoid native histograms as output values for alerts. If native histogram
samples are used in templates, they are [rendered in their simple text
form](#template-expansion) (as producted by the Go `FloatHistogram.String`
form](#template-expansion) (as produced by the Go `FloatHistogram.String`
method), which is hard to read for humans.

### Testing framework
Expand Down Expand Up @@ -2303,11 +2302,10 @@ Example for the text representation of a float histogram:

The [protobuf specs for remote write &
read](https://github.com/prometheus/prometheus/blob/main/prompb) were extended
for native histograms as an experimental feature. Receivers not capable of
processing native histograms will simply ignore the newly added fields.
Nevertheless, Prometheus has to be configured to send native histograms via
remote write (by setting the `send_native_histograms` remote write config
setting to true).
for native histograms. Receivers not capable of processing native histograms
will simply ignore the newly added fields. Nevertheless, Prometheus has to be
configured to send native histograms via remote write (by setting the
`send_native_histograms` remote write config setting to true).

In [remote write v2](https://prometheus.io/docs/specs/remote_write_spec_2_0/),
native histograms are a stable feature.
Expand Down