Prometheus logo

Prometheus

ドキュメントダウンロードコミュニティサポート & トレーニングブログ

Ctrl + K

GitHub Logo

Prometheus 3.0 移行ガイド

Prometheus 3.0 リリースには、当社の安定性に関する約束に沿って、いくつかの後方互換性のない変更が含まれています。このドキュメントでは、Prometheus 2.x から Prometheus 3.0 以降のバージョンへの移行に関するガイダンスを提供します。

フラグ

  • 以下の機能フラグは削除され、Prometheus v3 のデフォルト動作に追加されました。

    • promql-at-modifier
    • promql-negative-offset
    • new-service-discovery-manager
    • expand-external-labels
      • 外部ラベル値の環境変数参照 ${var} または $var は、現在の環境変数の値に従って置き換えられます。
      • 未定義の変数への参照は空の文字列に置き換えられます。$ 文字は $$ を使用してエスケープできます。
    • no-default-scrape-port
      • Prometheus v3 は、指定されたスキームに従ってスクレイプターゲットにポートを追加しなくなりました。ターゲットは、設定どおりにラベルに表示されます。
      • https://example.com/metrics または http://example.com/metrics のようなスクレイプターゲットが、それぞれ https://example.com/metrics:443 および http://example.com/metrics:80 として表現されることに依存している場合は、それらをターゲット URL に追加してください。
    • agent
      • 代わりに、専用の --agent CLI フラグを使用してください。
    • remote-write-receiver
      • 代わりに、専用の --web.enable-remote-write-receiver CLI フラグを使用して、リモート書き込みレシーバーを有効にしてください。
    • auto-gomemlimit
      • Prometheus v3 は、Linux コンテナのメモリ制限に合わせて GOMEMLIMIT を自動的に設定します。コンテナの制限がない場合、またはプロセスがコンテナ外で実行されている場合は、システムメモリの合計が使用されます。これを無効にするには、--no-auto-gomemlimit が利用可能です。
    • auto-gomaxprocs
      • Prometheus v3 は、Linux コンテナの CPU クォータに合わせて GOMAXPROCS を自動的に設定します。これを無効にするには、--no-auto-gomaxprocs が利用可能です。

    Prometheus v3 は、引き続きこれらを --enable-feature に渡すと警告をログに記録します。

設定

  • スクレイプジョブレベルの設定オプション scrape_classic_histograms は always_scrape_classic_histograms に名称変更されました。ネイティブヒストグラムを取り込むために --enable-feature=native-histograms 機能フラグを使用し、かつエンドポイントがネイティブヒストグラムと共に公開する可能性があるクラシックヒストグラムも取り込みたい場合は、この設定を追加するか、古い名前から設定を変更してください。
  • remote_write 項目の http_config.enable_http2 のデフォルトが false に変更されました。Prometheus v2 では、リモート書き込み http クライアントはデフォルトで http2 を使用していました。複数のリモート書き込みキューを複数のソケットで並列化するには、http2 をデフォルトにしない方が望ましいです。リモート書き込みに http2 を使用したい場合は、remote_write 設定セクションで http_config.enable_http2: true を設定する必要があります。

PromQL

正規表現が改行に一致する

PromQL の正規表現における . パターンは改行文字に一致するようになりました。この変更により、.* のような正規表現は \n を含む文字列に一致します。これはクエリのマッチャーとリラベル設定に適用されます。

たとえば、以下の正規表現は、Prometheus v2 では一致しなかった以下の文字列に一致するようになりました。- .* はさらに foo\n および Foo\nBar に一致する - foo.?bar はさらに foo\nbar に一致する - foo.+bar はさらに foo\nbar に一致する

Prometheus v3 の動作を v2 と同じにしたい場合は、すべての . パターンを [^\n] に置き換えて正規表現を変更する必要があります（例: foo[^\n]*）。

範囲セレクターとルックバックは、左境界と一致するサンプルを除外する

ルックバックと範囲セレクターは左側が開で右側が閉じるようになりました（以前は左側と右側が閉じる）。これにより、動作の一貫性が向上します。この変更は、範囲の左境界またはルックバックデルタが1つ以上のサンプルのタイムスタンプと一致するクエリに影響します。

例えば、1分間隔で均等に配置された時系列を照会しているとします。Prometheus v3 より前は、5m の範囲クエリは通常 5 つのサンプルを返しました。しかし、クエリ評価がスクレイプと完全に一致した場合、6 つのサンプルが返されました。Prometheus v3 では、このようなクエリは、均等な間隔が与えられた場合、常に 5 つのサンプルを返します。

この変更は通常、サブクエリに影響を与えます。なぜなら、サブクエリの評価タイミングは自然に完全に均等に配置され、サブクエリの解像度の倍数であるタイムスタンプと整合しているためです。さらに、クエリフロントエンドはサブクエリをステップサイズの倍数に合わせることがよくあります。これらの組み合わせにより、完璧な相互整合の状況が容易に作成されますが、これはユーザーには意図せず、また知られていないことが多いため、新しい動作は驚きかもしれません。Prometheus V3 より前では、このようなシステムでの foo[1m:1m] のサブクエリは常に2つのポイントを返しており、レート計算が可能でした。しかし、Prometheus V3 では、このようなサブクエリは1つのポイントしか返さないため、レート計算や増加計算には不十分であり、結果として「データなし」が返されます。

このようなクエリは、複数のポイントを適切にカバーするようにウィンドウを拡張するために書き直す必要があります。この例では、foo[2m:1m] はクエリの配置に関係なく常に2つのポイントを返します。書き換えられたクエリの正確な形式は意図する結果によって異なり、動作が変更されたクエリに対する普遍的なドロップイン置換はありません。

テストも同様に影響を受ける可能性が高くなります。これらを修正するには、期待されるサンプル数を調整するか、範囲を拡張します。

holt_winters 関数名の変更

holt_winters 関数は double_exponential_smoothing に名前が変更され、現在は promql-experimental-functions 機能フラグによって保護されています。holt_winters を引き続き使用したい場合は、以下の両方を実行する必要があります。

  • クエリで holt_winters を double_exponential_smoothing に変更します。
  • Prometheus CLI 呼び出しで --enable-feature=promql-experimental-functions を渡します。

スクレイピングプロトコル

Prometheus v3 は、スクレイプ時に受信する Content-Type ヘッダーに関して、より厳格になりました。Prometheus v2 では、スクレイプされるターゲットが Content-Type ヘッダーを指定しなかった場合、またはヘッダーが解析不能または認識不能だった場合、標準の Prometheus テキストプロトコルにデフォルトで設定されていました。これにより、スクレイプで誤ったデータが解析される可能性がありました。Prometheus v3 は、そのような場合、スクレイプを失敗させるようになりました。

スクレイプターゲットが正しい Content-Type ヘッダーを提供しない場合、フォールバックプロトコルは fallback_scrape_protocol パラメータを使用して指定できます。Prometheus の scrape_config ドキュメントを参照してください。

この変更は、Prometheus v2 では成功していたスクレイプが、このフォールバックプロトコルが指定されていない場合、Prometheus v3 では失敗する可能性があるため、破壊的変更です。

その他

TSDB 形式とダウングレード

Prometheus v2.55 では、インデックス形式の変更に備えて TSDB 形式がわずかに変更されました。結果として、Prometheus v3 TSDB は Prometheus v2.55 以降でしか読み取ることができません。v3 にアップグレードする際には、この点に留意してください。TSDB の永続データを失うことなく、v2.55 より前のバージョンにダウングレードすることはできません。

追加の安全対策として、まず v2.55 にアップグレードし、Prometheus が期待どおりに動作することを確認してから、v3 にアップグレードすることを検討してもよいでしょう。

TSDB ストレージ契約

TSDB 互換ストレージは、指定されたセレクタに一致する結果を返すことが期待されるようになりました。これは、一部のサードパーティ実装、特に remote_read を実装しているものに影響を与える可能性があります。

この契約は明示的に強制されていませんが、未定義の動作を引き起こす可能性があります。

UTF-8名

Prometheus v3 はメトリック名とラベル名で UTF-8 をサポートしています。これは、エンドポイントによって公開される内容に応じて、アップグレード後にメトリック名とラベル名が変更される可能性があることを意味します。さらに、以前は無効とフラグ付けされていたメトリック名とラベル名は、無効とされなくなります。

元の検証動作を維持したいユーザーは、Prometheus の YAML 設定を更新して、従来の検証スキームを指定できます。

global:
  metric_name_validation_scheme: legacy

または、スクレイプごとに

scrape_configs:
  - job_name: job1
    metric_name_validation_scheme: utf8
  - job_name: job2
    metric_name_validation_scheme: legacy

ログメッセージ形式

Prometheus v3 は、以前の go-kit/log に代わって log/slog を採用しました。これにより、ログメッセージの形式が変更されます。古いログ形式の例は次のとおりです。

ts=2024-10-23T22:01:06.074Z caller=main.go:627 level=info msg="No time or size retention was set so using the default time retention" duration=15d
ts=2024-10-23T22:01:06.074Z caller=main.go:671 level=info msg="Starting Prometheus Server" mode=server version="(version=, branch=, revision=91d80252c3e528728b0f88d254dd720f6be07cb8-modified)"
ts=2024-10-23T22:01:06.074Z caller=main.go:676 level=info build_context="(go=go1.23.0, platform=linux/amd64, user=, date=, tags=unknown)"
ts=2024-10-23T22:01:06.074Z caller=main.go:677 level=info host_details="(Linux 5.15.0-124-generic #134-Ubuntu SMP Fri Sep 27 20:20:17 UTC 2024 x86_64 gigafips (none))"

新しいログ形式での同様のシーケンスは次のようになります。

time=2024-10-24T00:03:07.542+02:00 level=INFO source=/home/user/go/src/github.com/prometheus/prometheus/cmd/prometheus/main.go:640 msg="No time or size retention was set so using the default time retention" duration=15d
time=2024-10-24T00:03:07.542+02:00 level=INFO source=/home/user/go/src/github.com/prometheus/prometheus/cmd/prometheus/main.go:681 msg="Starting Prometheus Server" mode=server version="(version=, branch=, revision=7c7116fea8343795cae6da42960cacd0207a2af8)"
time=2024-10-24T00:03:07.542+02:00 level=INFO source=/home/user/go/src/github.com/prometheus/prometheus/cmd/prometheus/main.go:686 msg="operational information" build_context="(go=go1.23.0, platform=linux/amd64, user=, date=, tags=unknown)" host_details="(Linux 5.15.0-124-generic #134-Ubuntu SMP Fri Sep 27 20:20:17 UTC 2024 x86_64 gigafips (none))" fd_limits="(soft=1048576, hard=1048576)" vm_limits="(soft=unlimited, hard=unlimited)"

le および quantile ラベル値

Prometheus v3 では、クラシックヒストグラムの le ラベルの値とサマリーの quantile ラベルの値が取り込み時に正規化されます。Prometheus v2 では、これらのラベルの値は、状況によってはスクレイププロトコル (protobuf 対テキスト形式) に依存していました。これにより、スクレイププロトコルに基づいてラベル値が変更されることがありました。たとえば、my_classic_hist{le="1"} として公開されたメトリックは、テキスト形式では my_classic_hist{le="1"} として取り込まれましたが、protobuf 経由では my_classic_hist{le="1.0"} として取り込まれました。これによりメトリックの識別情報が変更され、メトリックをクエリする際に問題が発生しました。Prometheus v3 では、これらのラベル値は常に浮動小数点数のような表現に正規化されます。つまり、上記の例は、どのプロトコル経由であっても、常に my_classic_hist{le="1.0"} が Prometheus に取り込まれることになります。この変更の影響により、le="1" のような整数値としてラベル値を直接参照するアラート、記録ルール、およびダッシュボードは機能しなくなります。

この変更に対処する方法（グローバルまたはメトリック単位）

  • 整数値の le、quantile ラベルへの参照を修正し、それ以外は何もしないで、移行期間をまたぐ一部のクエリが不正確または予期しない結果を生成することを容認します。これが推奨される解決策です。
  • metric_relabel_config を使用して、ターゲットをスクレイプする際に古いラベルを保持します。これは、現在そのようなラベルを生成しているメトリックに**のみ**適用されるべきです。
    metric_relabel_configs:
      - source_labels:
          - quantile
        target_label: quantile
        regex: (\d+)\.0+
      - source_labels:
          - le
          - __name__
        target_label: le
        regex: (\d+)\.0+;.*_bucket

v1 API を使用した Alertmanager の設定を禁止する

Prometheus 3 は Alertmanager の v1 API をサポートしなくなりました。事実上、Prometheus 3 は Alertmanager 0.16.0 以降を必要とします。Alertmanager の古いバージョンを使用しているユーザー、または alerting: alertmanagers: [api_version: v1] を使用する設定を使用しているユーザーは、Alertmanager をアップグレードし、設定を api_version: v2 を使用するように変更する必要があります。

Prometheus 2.0 移行ガイド

Prometheus 1.8 から 2.0 への移行ガイドについては、Prometheus v2.55 ドキュメントを参照してください。

このページの内容