root
/
prometheus
mirror of https://github.com/prometheus/prometheus.git
1
0
Fork 0
Code Issues Actions 11 Packages Projects Releases Wiki Activity

feat(nh): mark native histograms as stable and keep optional 

Fixes: #16572

Keep the feature optional but mark as stable, meaning that breaking
changes are only allowed together with major version release of
Prometheus.

Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>
This commit is contained in:
György Krajcsovits 2025-09-26 16:35:11 +02:00
parent e697dfa3ff
commit 6f1f48f01c
No known key found for this signature in database
GPG Key ID: 47A8F9CE80FD7C7F
6 changed files with 34 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
cmd/prometheus/main.go
View File

@ -259,7 +259,7 @@ func (c *flagConfig) setFeatureListOptions(logger *slog.Logger) error {
// Change relevant global variables. Hacky, but it's hard to pass a new option or default to unmarshallers. // Change relevant global variables. Hacky, but it's hard to pass a new option or default to unmarshallers.
config.DefaultConfig.GlobalConfig.ScrapeProtocols = config.DefaultProtoFirstScrapeProtocols config.DefaultConfig.GlobalConfig.ScrapeProtocols = config.DefaultProtoFirstScrapeProtocols
config.DefaultGlobalConfig.ScrapeProtocols = config.DefaultProtoFirstScrapeProtocols config.DefaultGlobalConfig.ScrapeProtocols = config.DefaultProtoFirstScrapeProtocols
logger.Info("Experimental native histogram support enabled. Changed default scrape_protocols to prefer PrometheusProto format.", "global.scrape_protocols", fmt.Sprintf("%v", config.DefaultGlobalConfig.ScrapeProtocols)) logger.Info("Native histogram support enabled. Changed default scrape_protocols to prefer PrometheusProto format.", "global.scrape_protocols", fmt.Sprintf("%v", config.DefaultGlobalConfig.ScrapeProtocols))
case "ooo-native-histograms": case "ooo-native-histograms":
logger.Warn("This option for --enable-feature is now permanently enabled and therefore a no-op.", "option", o) logger.Warn("This option for --enable-feature is now permanently enabled and therefore a no-op.", "option", o)
case "created-timestamp-zero-ingestion": case "created-timestamp-zero-ingestion":

38
docs/feature_flags.md
View File

@ -50,23 +50,31 @@ computed at all.
`--enable-feature=native-histograms` `--enable-feature=native-histograms`
When enabled, Prometheus will ingest native histograms (formerly also known as When enabled, Prometheus will ingest native histograms (formerly also known as
sparse histograms or high-res histograms). Native histograms are still highly sparse histograms or high-res histograms). Native histograms are considered a
experimental. Expect breaking changes to happen (including those rendering the stable feature.
TSDB unreadable).
Native histograms may be directly scraped from targets (see below). Prometheus
can also convert classic histograms scraped from targets into native histograms
with custom buckets during scrape. Native histograms may be ingested on
Remote-Write 1.0, 2.0, OTLP.
Native histograms are currently only supported in the traditional Prometheus Native histograms are currently only supported in the traditional Prometheus
protobuf exposition format. This feature flag therefore also enables a new (and protobuf exposition format. This feature flag therefore also enables a the
also experimental) protobuf parser, through which _all_ metrics are ingested protobuf parser by changing the default for the `scrape_protocols` scrape
(i.e. not only native histograms). Prometheus will try to negotiate the configuration parameter to `[ PrometheusProto, OpenMetricsText1.0.0,
protobuf format first. The instrumented target needs to support the protobuf OpenMetricsText0.0.1, PrometheusText0.0.4 ]`. Which means that Prometheus
format, too, _and_ it needs to expose native histograms. The protobuf format will try to negotiate the protobuf format first and if the target supports
allows to expose classic and native histograms side by side. With this feature the protobuf expostion format then _all_ metrics are ingested via protobuf
flag disabled, Prometheus will continue to parse the classic histogram (albeit (i.e. not only native histograms). The protobuf format allows to expose
via the text format). With this flag enabled, Prometheus will still ingest classic and native histograms side by side.
those classic histograms that do not come with a corresponding native
histogram. However, if a native histogram is present, Prometheus will ignore With this feature flag disabled, Prometheus will continue to parse the classic
the corresponding classic histogram, with the notable exception of exemplars, histogram (albeit via the text format).
which are always ingested. To keep the classic histograms as well, enable With this flag enabled, Prometheus will still ingest those classic histograms
that do not come with a corresponding native histogram. However, if a native
histogram is present, Prometheus will ignore the corresponding classic
histogram, with the notable exception of exemplars, which are always ingested.
To keep the classic histograms as well, enable
`always_scrape_classic_histograms` in the scrape job. `always_scrape_classic_histograms` in the scrape job.
## Experimental PromQL functions ## Experimental PromQL functions

8
docs/federation.md
View File

@ -6,10 +6,10 @@ sort_rank: 6
Federation allows a Prometheus server to scrape selected time series from Federation allows a Prometheus server to scrape selected time series from
another Prometheus server. another Prometheus server.
_Note about native histograms (experimental feature): To scrape native histograms _Note about native histograms: To scrape native histograms via federation, the
via federation, the scraping Prometheus server needs to run with native histograms scraping Prometheus server needs to run with native histograms enabled (via the
enabled (via the command line flag `--enable-feature=native-histograms`), implying command line flag `--enable-feature=native-histograms`), implying that the
that the protobuf format is used for scraping. Should the federated metrics contain protobuf format is used for scraping. Should the federated metrics contain
a mix of different sample types (float64, counter histogram, gauge histogram) for a mix of different sample types (float64, counter histogram, gauge histogram) for
the same metric name, the federation payload will contain multiple metric families the same metric name, the federation payload will contain multiple metric families
with the same name (but different types). Technically, this violates the rules of with the same name (but different types). Technically, this violates the rules of

9
docs/querying/api.md
View File

@ -578,9 +578,9 @@ sample values. JSON does not support special float values such as `NaN`, `Inf`,
and `-Inf`, so sample values are transferred as quoted JSON strings rather than and `-Inf`, so sample values are transferred as quoted JSON strings rather than
raw numbers. raw numbers.
The keys `"histogram"` and `"histograms"` only show up if the experimental The keys `"histogram"` and `"histograms"` only show up if native histograms
native histograms are present in the response. Their placeholder `<histogram>` are present in the response. Their placeholder `<histogram>` is explained
is explained in detail in its own section below. in detail in its own section below.
### Range vectors ### Range vectors
@ -648,9 +648,6 @@ String results are returned as result type `string`. The corresponding
The `<histogram>` placeholder used above is formatted as follows. The `<histogram>` placeholder used above is formatted as follows.
_Note that native histograms are an experimental feature, and the format below
might still change._
```json ```json
{ {
"count": "<count_of_observations>", "count": "<count_of_observations>",

2
docs/querying/basics.md
View File

@ -37,7 +37,7 @@ user-specified expression.
For [instant queries](api.md#instant-queries), any of the above data types are allowed as the root of the expression. For [instant queries](api.md#instant-queries), any of the above data types are allowed as the root of the expression.
[Range queries](api.md#range-queries) only support scalar-typed and instant-vector-typed expressions. [Range queries](api.md#range-queries) only support scalar-typed and instant-vector-typed expressions.
_Notes about the experimental native histograms:_ _Notes about the native histograms:_
* Ingesting native histograms has to be enabled via a [feature * Ingesting native histograms has to be enabled via a [feature
flag](../feature_flags.md#native-histograms). flag](../feature_flags.md#native-histograms).

4
tsdb/wlog/watcher.go
View File

@ -563,7 +563,7 @@ func (w *Watcher) readSegment(r *LiveReader, segmentNum int, tail bool) error {
w.writer.AppendExemplars(exemplars) w.writer.AppendExemplars(exemplars)
case record.HistogramSamples, record.CustomBucketsHistogramSamples: case record.HistogramSamples, record.CustomBucketsHistogramSamples:
// Skip if experimental "histograms over remote write" is not enabled. // Skip if "histograms over remote write" is not enabled.
if !w.sendHistograms { if !w.sendHistograms {
break break
} }
@ -591,7 +591,7 @@ func (w *Watcher) readSegment(r *LiveReader, segmentNum int, tail bool) error {
} }
case record.FloatHistogramSamples, record.CustomBucketsFloatHistogramSamples: case record.FloatHistogramSamples, record.CustomBucketsFloatHistogramSamples:
// Skip if experimental "histograms over remote write" is not enabled. // Skip if "histograms over remote write" is not enabled.
if !w.sendHistograms { if !w.sendHistograms {
break break
} }