feat(nh): mark native histograms as stable and keep optional by krajorama · Pull Request #17232 · prometheus/prometheus

krajorama · 2025-09-26T14:37:15Z

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

Which issue(s) does the PR fix:

Related to: #16572

Does this PR introduce a user-facing change?

[FEATURE] Native histograms are now a stable, but optional feature. This means that breaking changes will require a major release bump.

ArthurSens

just some small comments, but non blocking

docs/feature_flags.md

roidelapluie · 2025-09-29T14:44:22Z

As far as I remember, this should be enabled with --scrape.native-histograms or another real cli variable.

Every feature behind --enable-feature is considered experimental.

Here is a list of features that are disabled by default since they are breaking changes or are considered experimental. Their behaviour can change in future releases which will be communicated via the release changelog.

https://prometheus.io/docs/prometheus/latest/feature_flags/

It also means that the documentatin needs to be moved as well.

juliusv · 2025-09-29T14:48:01Z

@roidelapluie Good point, that's true!

beorn7 · 2025-09-30T16:37:11Z

We have a new plan. Presumably, some things need adjustment here in this PR.

Maybe we should first implement the new scrape config option and then come back to this?

The detailed plan for this is laid out in #16572 . This commit adds a global and local scrape config option `scrape_native_histograms`, which has to be set to true to ingest native histograms. To ease the transition, the feature flag is changed to simply set the default of `scrape_native_histograms` to true. Further implications: - The default scrape protocols now depend on the `scrape_native_histograms` setting. - Everywhere else, histograms are now "on by default". Documentation beyond the one for the feature flag and the scrape config are deliberately left out. See #17232 for that. Signed-off-by: beorn7 <beorn@grafana.com>

beorn7 · 2025-10-16T12:58:16Z

Note: Updated the release notes line to be shorter and "more correct".

docs/querying/basics.md

docs/federation.md

beorn7 · 2025-10-16T13:16:49Z

Not sure if needed, but the migration.md file says "If you use the --enable-feature=native-histograms feature flag...". If somebody migrates from v2 to v3 now, we should probably tell them "If you have set scrape_native_histograms: true in your scrape config..."

Maybe we mention both: "If you have set scrape_native_histograms: true in your scrape config or you use the --enable-feature=native-histograms feature flag..."

docs/querying/basics.md

docs/federation.md

beorn7 · 2025-10-18T18:33:32Z

Not sure if needed, but the migration.md file says "If you use the --enable-feature=native-histograms feature flag...". If somebody migrates from v2 to v3 now, we should probably tell them "If you have set scrape_native_histograms: true in your scrape config..."

Maybe we mention both: "If you have set scrape_native_histograms: true in your scrape config or you use the --enable-feature=native-histograms feature flag..."

Do you want to keep migration.md as is or adopt my suggestion? (I'm fine if you want to keep it as is, but I would like to make sure you have seen my comment.)

docs/querying/basics.md

krajorama · 2025-10-20T09:09:44Z

Not sure if needed, but the migration.md file says "If you use the --enable-feature=native-histograms feature flag...". If somebody migrates from v2 to v3 now, we should probably tell them "If you have set scrape_native_histograms: true in your scrape config..."
Maybe we mention both: "If you have set scrape_native_histograms: true in your scrape config or you use the --enable-feature=native-histograms feature flag..."

Do you want to keep migration.md as is or adopt my suggestion? (I'm fine if you want to keep it as is, but I would like to make sure you have seen my comment.)

Not sure. Technically we should mention that from 3.8 the feature flag is deprecated. But do we really have to keep updating this doc?

beorn7 · 2025-10-20T18:10:28Z

Not sure if needed, but the migration.md file says "If you use the --enable-feature=native-histograms feature flag...". If somebody migrates from v2 to v3 now, we should probably tell them "If you have set scrape_native_histograms: true in your scrape config..."
Maybe we mention both: "If you have set scrape_native_histograms: true in your scrape config or you use the --enable-feature=native-histograms feature flag..."

Do you want to keep migration.md as is or adopt my suggestion? (I'm fine if you want to keep it as is, but I would like to make sure you have seen my comment.)

Not sure. Technically we should mention that from 3.8 the feature flag is deprecated. But do we really have to keep updating this doc?

Not forever, of course, but this is an easy update, and I assume that there are still a bunch of users who migrate from v2 to v3 these days, probably even when v3.9 is out, and we save them a lot of confusion by adding this.

beorn7

Just a few things left.

docs/querying/basics.md

krajorama · 2025-10-24T06:14:46Z

Not sure if needed, but the migration.md file says "If you use the --enable-feature=native-histograms feature flag...". If somebody migrates from v2 to v3 now, we should probably tell them "If you have set scrape_native_histograms: true in your scrape config..."
Maybe we mention both: "If you have set scrape_native_histograms: true in your scrape config or you use the --enable-feature=native-histograms feature flag..."

Do you want to keep migration.md as is or adopt my suggestion? (I'm fine if you want to keep it as is, but I would like to make sure you have seen my comment.)

Not sure. Technically we should mention that from 3.8 the feature flag is deprecated. But do we really have to keep updating this doc?

Not forever, of course, but this is an easy update, and I assume that there are still a bunch of users who migrate from v2 to v3 these days, probably even when v3.9 is out, and we save them a lot of confusion by adding this.

I've made an update , but not here, rather at the feature flags section, ptal

beorn7

Only the location of the gauge vs counter histograms left.

docs/querying/basics.md

Fixes: #16572 Mark as stable means that breaking changes are only allowed together with major version release of Prometheus. Co-authored-by: Björn Rabenstein <beorn@grafana.com> Signed-off-by: George Krajcsovits <krajorama@users.noreply.github.com> Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>

Plus some docstrings Signed-off-by: György Krajcsovits <gyorgy.krajcsovits@grafana.com>

krajorama requested review from beorn7, bwplotka and juliusv September 26, 2025 14:37

krajorama force-pushed the krajo/nh-stable branch 2 times, most recently from 6e499a4 to 863ecd0 Compare September 29, 2025 07:50

krajorama marked this pull request as ready for review September 29, 2025 08:06

krajorama requested review from Nexucis and jesusvazquez as code owners September 29, 2025 08:06

krajorama mentioned this pull request Sep 29, 2025

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

Merged

ArthurSens approved these changes Sep 29, 2025

View reviewed changes

docs/feature_flags.md Outdated Show resolved Hide resolved

docs/feature_flags.md Outdated Show resolved Hide resolved

juliusv reviewed Sep 29, 2025

View reviewed changes