Loutresのメモ

Prometheus v3.8.0: Native Histograms安定化(Opt-in)

5 min read

概要

LWKD（Week Ending November 30, 2025）の依存関係アップデート枠で、Prometheus v3.8.0 が Native Histograms（ネイティブヒストグラム）を「安定（stable）」扱いにしつつ、スクレイプ取り込みは明示的に有効化する（opt-in） 形に移行した点が紹介されました。 なお、LWKD本文では設定名が scrape_native_histogram と書かれていますが、Prometheus v3.8.0 での正しい設定名は scrape_native_histograms です。

変更内容（何が変わったか）

  • 安定化（stable）: v3.8.0 は「Native Histograms を stable として扱う最初のリリース」とされています。
  • ただし opt-in: Native Histograms を“取り込む（scrape/ingest）”には、新設された scrape_native_histograms を明示的に有効化する必要があります。
  • 移行のための暫定挙動: v3.8.0 では --enable-feature=native-histograms が完全な no-op ではなく、scrape_native_histograms のデフォルトを true に寄せるために残されています。次リリース（v3.9）では no-op になり、scrape_native_histograms のデフォルトは常に false になる予定、と明記されています。
  • スクレイプ時の content negotiation に影響: scrape_native_histograms を有効にすると、スクレイプのプロトコル交渉で protobuf（PrometheusProto）を優先する方向になります（必要に応じて scrape_protocols で調整可能）。

背景（なぜこの変更が必要か）

  • Native Histograms は Prometheus のデータモデルに「ヒストグラムを第一級のサンプル型」として入れる大きな変更で、長らく experimental として提供されてきました（初期導入は 2022年11月、最初にサーバー側が対応したのは v2.40.0、当初は --enable-feature=native-histograms が必要）。
  • stable 化の方針としては「破壊的変更は Prometheus のメジャーバージョン更新時のみ許容する」扱いにする一方、スクレイプのデフォルト挙動（特に protobuf 優先など）をいきなり変えるのは互換性・オーバーヘッド面でリスクがあるため、取り込み自体は opt-in として段階移行する設計になっています（追跡 Issue でも、デフォルトの scrape protocol 順序変更が breaking になり得る点が議論されています）。

影響（運用者/利用者/開発者への影響、注意点、移行）

  • 運用者（Prometheus を Kubernetes 上で運用する人）
    • v3.8.0 以降、Native Histograms を実際に収集したい場合は scrape_native_histograms: true を（グローバルまたは対象の scrape config に）設定する必要があります。
    • 既に --enable-feature=native-histograms を使っていた場合、v3.8.0 のリリースノートが推奨する移行手順は次の通りです：
      1. v3.8 に上げても当面フラグは残す
      2. 収集したい job へ scrape_native_histograms: true を設定（必要なら収集したくない job には明示的に false）
      3. フラグを外して動作確認
      4. v3.9 以降に備える
    • scrape_native_histograms を有効にすると content negotiation が変わるため、想定しているエンドポイント/プロキシ経路で protobuf スクレイプが問題にならないか事前検証が重要です（細かい制御は scrape_protocols で可能）。
  • 開発者（メトリクスを出す側）
    • Native Histograms は「classic histogram（_bucket/_sum/_count の複数系列）」とは別物として扱われ、PromQL や API 上でも“ヒストグラムサンプル型”として現れます。Native Histograms を前提にした可観測性設計・クエリ/ダッシュボードを作る場合、収集側が opt-in を済ませているかが前提条件になります。

用語メモ（用語の軽い説明）

  • Native Histograms: ヒストグラムを複数の float 系列に分解せず、1サンプルとして構造化データ（count/sum/buckets）で扱う方式。
  • classic histogram: *_bucket/*_sum/*_count など複数系列（float サンプル）で表現する従来方式。
  • scrape / scrape config: Prometheus が対象エンドポイントを取りに行ってサンプルを取り込む設定（job ごとの設定ブロック）。
  • --enable-feature=native-histograms: 以前の experimental 機能フラグ。v3.8.0 では移行用に残り、v3.9 以降は no-op になる予定。
  • content negotiation / scrape_protocols / PrometheusProto: スクレイプでどの exposition 形式（protobuf/テキスト等）を使うかの交渉・優先順。

参考リンク

グラフビュー

バックリンク