Loutresのメモ

Prometheus v3.8.1: Remote Write の不具合修正

5 min read

概要

Prometheus v3.8.1（2025-12-16リリース）では、Remote Write を受ける側（receiver）が Remote Write v1（PRWv1）相当のリクエストに対して誤った統計レスポンスヘッダを返してしまう不具合が修正されました。これにより、送信側（sender）が「2xx なのに一部書き込めていない」という 誤検知（partial error）ログや誤ったメトリクスを出す問題が改善します。

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

  • v3.8.1 の BUGFIX は「PRWv1 フローで誤ったレスポンスヘッダを返し、Prometheus sender 側で誤った partial error ログ/メトリクスを出す」問題の修正（#17683）。
  • Prometheus 本体側では、主に以下が行われています（#17683 の差分より）:
    • github.com/prometheus/client_golang/exp/api/remote を修正込みの版へ更新（commit 7ba246a... を含む）
    • 回帰テスト追加（Issue #17659 を回帰対象にしたテスト）
    • インターフェース（PRWv1/v2 と stats の扱い）が紛らわしい点のコメント補強
  • 依存ライブラリ（client_golang）側の修正では、v1 リクエスト処理時に v2 の stats ヘッダを付与しないように変更（client_golang #1927 / commit 7ba246a...）。

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

Issue #17659 では、v3.8.0 へのアップグレード後に送信側 Prometheus が次のエラーを頻繁に出す事例が報告されました（受信側からは 2xx が返るが、統計上「書けていない」ように見える）:

  • we got 2xx status code from the Receiver yet statistics indicate some data was not written; investigation needed

調査コメントでは、Remote Write のリファクタ（Prometheus #17197 で client_golang/exp/api/remote の型/ハンドラを採用）以降、PRWv1 のレスポンスでも v2 由来の統計ヘッダが付いてしまい、しかも stats が 0 扱いになりやすいため、送信側が「部分失敗」と誤解釈してしまう流れが整理されています（Issue #17659 の調査コメント）。この誤検知は「実データ欠損ではなく、ログ/メトリクスが誤る」可能性が高い旨も共有されています（Issue #17659）。

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

  • 運用者/利用者
    • Prometheus を Remote Write receiver として使っていて、送信側が PRWv1 で投げてくる構成（例: 既存の /api/v1/write 互換送信）では、v3.8.0 近辺で 誤った partial error ログや 誤った送信系メトリクスが出る可能性があり、v3.8.1 で改善します。
    • Issue の TL;DR では「誤警告であり、データは失われていないはず」とされていますが、ログ監視・アラートがノイズ化していた環境では優先度高めのアップデート対象です。
  • 開発者
    • PRWv1 と PRWv2 で「統計（stats）をヘッダで返す/解釈する」境界が曖昧だと、receiver/sender 間の相互運用で誤検知が起きうる、という教訓が明文化されています（Prometheus #17683 および client_golang #1927）。

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

  • Remote Write: Prometheus がサンプル（メトリクスデータ）を HTTP 経由で外部へ送る仕組み。
  • receiver / sender: Remote Write を「受ける側（HTTP サーバ）」と「送る側（HTTP クライアント）」。
  • PRWv1 / PRWv2: Prometheus Remote Write プロトコルのバージョン（v1 相当 / v2 相当）。
  • （統計）レスポンスヘッダ: receiver が「何件書けたか」等を HTTP ヘッダで返し、sender が成功/部分失敗を判断する材料にするもの。
  • partial error（誤検知）ログ: 2xx なのに「統計上は一部失敗」と解釈して出る警告/エラー（今回の焦点）。

参考リンク

グラフビュー

バックリンク