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 が利用可能です。

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

設定

  • スクレイプジョブレベルの設定オプション 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 を含む文字列にマッチします。これは、クエリや relabel 設定のマッチャーに適用されます。

たとえば、以下の正規表現は、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 で成功していたスクレイプが、このフォールバックプロトコルが指定されていない場合に失敗する可能性があります。

その他

TSDB フォーマットとダウングレード

Prometheus v2.55 のインデックスフォーマットへの変更の準備のため、TSDB フォーマットがわずかに変更されました。したがって、Prometheus v3 TSDB は Prometheus v2.55 以降でのみ読み取ることができます。v3 へのアップグレードを検討する際にこれを念頭に置いてください。TSDB の永続データを失うことなく、v2.55 へのダウングレードのみが可能になります。

追加の安全対策として、オプションで v2.55 に最初にアップグレードし、v3 にアップグレードする前に Prometheus が期待どおりに動作することを確認することを検討してください。

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 vs テキストフォーマット）に依存していました。これにより、ラベルの値がスクレイププロトコルによって変更されていました。例：テキストフォーマット経由で 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

Alertmanager の v1 API による設定を禁止する

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 ドキュメント を参照してください。

このページの内容