●Change8

Migrating to Prometheus v3.9.0

Version v3.9.0 introduces 1 breaking change. This guide details how to update your code.

Released: 1/7/2026

1
Breaking Changes
2
Migration Steps
13
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

scrape_native_histogramsnative-histogram/api/v1/featurestsdb dump--storage.tsdb.delay-compact-file.pathprometheus_notifications_latency_histogram_secondsprometheus_sd_refresh metricsprometheus_tsdb_sample_ooo_deltarate()increase()delta()label_join()label_replace()

Breaking Changes

●Issue #1

Native Histograms are no longer experimental. The feature flag `native-histogram` is now a no-op. Users must enable the configuration setting `scrape_native_histograms` to collect Native Histogram samples from exporters.

Migration Steps

  1. 1
    If you were using Native Histograms, you must now enable the configuration setting `scrape_native_histograms` in your configuration file to collect samples, as the `native-histogram` feature flag is ignored.
  2. 2
    Review PromQL queries that might have been affected by fixes related to delayed name removal or OR expressions.

Release Summary

This release stabilizes Native Histograms, requiring configuration changes for collection, and introduces numerous enhancements across the API, Promtool, UI, and PromQL query engine. Numerous bug fixes address stability and correctness issues, particularly concerning histogram handling and PromQL operations.

Need More Details?

View the full release notes and all changes for Prometheus v3.9.0.

View Full Changelog