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 將不再根據指定的方案（scheme）向抓取目標新增埠。目標現在將按照配置直接顯示在標籤中。
      • 如果您依賴像 https://example.com/metrics 或 http://example.com/metrics 這樣的抓取目標分別被表示為 https://example.com/metrics:443 和 http://example.com/metrics:80，請將埠新增到您的目標 URL 中
    • agent
      • 請改用專用的 --agent 命令列標誌。
    • remote-write-receiver
      • 請改用專用的 --web.enable-remote-write-receiver 命令列標誌來啟用遠端寫入接收器。
    • auto-gomemlimit
      • Prometheus v3 將自動設定 GOMEMLIMIT 以匹配 Linux 容器的記憶體限制。如果不存在容器限制，或者程序在容器外部執行，則使用系統總記憶體。可以透過 --no-auto-gomemlimit 來停用此行為。
    • auto-gomaxprocs
      • Prometheus v3 將自動設定 GOMAXPROCS 以匹配 Linux 容器的 CPU 配額。可以透過 --no-auto-gomaxprocs 來停用此行為。

    如果您繼續將這些引數傳遞給 --enable-feature，Prometheus v3 將記錄一條警告。

  • 從 v3.9 開始，特性標誌 native-histograms 將不再起作用（no-op）。原生直方圖現在是一個穩定特性，但必須透過全域性或每個抓取配置選項 scrape_native_histograms（在 v3.8 中新增）來啟用對其的抓取。

配置

  • 抓取任務級別的配置選項 scrape_classic_histograms 已重新命名為 always_scrape_classic_histograms。如果您使用 scrape_native_histograms 抓取配置選項來攝取原生直方圖，並且還想攝取端點在暴露原生直方圖時可能同時暴露的經典直方圖（classic histograms），請務必新增此配置，或將您的配置從舊名稱進行更改。
  • remote_write 項中的 http_config.enable_http2 預設值已更改為 false。在 Prometheus v2 中，遠端寫入 HTTP 客戶端預設使用 HTTP/2。為了在多個套接字（socket）上並行化多個遠端寫入佇列，最好不要預設使用 HTTP/2。如果您更傾向於為遠端寫入使用 HTTP/2，現在必須在 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]*。

區間向量選擇器和回溯（lookback）排除了與左邊界重合的樣本

回溯和區間選擇器現在是左開右閉的（以前是左閉右閉的），這使得它們的行為更加一致。此更改會影響那些範圍左邊界或回溯時間差（lookback delta）與一個或多個樣本的時間戳重合的查詢。

例如，假設我們正在查詢一個時間間隔剛好為 1 分鐘且分佈均勻的時間序列。在 Prometheus v3 之前，一個 5m 的範圍查詢通常會返回 5 個樣本。但如果查詢評估恰好與抓取對齊，它將返回 6 個樣本。在 Prometheus v3 中，假設樣本間距均勻，此類查詢將始終返回 5 個樣本。

這一變化通常會影響子查詢，因為子查詢的評估時間自然是完美均勻分佈的，並且與作為子查詢解析度整數倍的時間戳對齊。此外，查詢前端通常會將子查詢對齊到步長（step size）的整數倍。這些因素結合起來，很容易造成完美對齊的情況（這通常是使用者無意且未知的），因此新行為可能會令人感到意外。在 Prometheus V3 之前，在此類系統上進行 foo[1m:1m] 的子查詢可能總是返回兩個點，從而可以進行速率計算。然而，在 Prometheus V3 中，此類子查詢將僅返回一個點，這對於 rate（速率）或 increase（增量）計算來說是不足的，從而導致返回“無資料（No Data）”。

此類查詢需要進行重寫以擴大視窗，從而確保能夠正確覆蓋多個點。在此示例中，無論查詢如何對齊，foo[2m:1m] 都將始終返回兩個點。重寫查詢的具體形式可能取決於預期的結果，對於行為發生變化的查詢，沒有通用的直接替代方案。

測試同樣更有可能受到影響。要修復這些問題，要麼調整預期的樣本數量，要麼擴大範圍。

holt_winters 函式已重新命名

holt_winters 函式已重新命名為 double_exponential_smoothing，現在受 promql-experimental-functions 特性標誌保護。如果您想繼續使用 holt_winters，您必須同時完成以下兩件事

  • 在您的查詢中，將 holt_winters 重新命名為 double_exponential_smoothing。
  • 在啟動 Prometheus 命令列時，傳入 --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 中本可以成功的抓取現在可能會失敗。請確保您的抓取端點響應時帶有所支援的 Content-Type 標頭之一

  • application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited
  • text/plain;version=0.0.4
  • text/plain;version=1.0.0
  • application/openmetrics-text;version=0.0.1
  • application/openmetrics-text;version=1.0.0

其他更改

TSDB 格式與降級

為了準備索引格式的更改，TSDB 格式在 Prometheus v2.55 中進行了輕微修改。因此，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 採用了 log/slog，取代了之前的 go-kit/log。這導致了日誌訊息格式的變化。舊日誌格式的一個示例如下

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"}。這改變了指標的唯一標識（identity），並在查詢指標時引發問題。在 Prometheus v3 中，這些標籤值將始終被歸一化為類似浮點數的表示。即無論透過哪種協議，上述示例在攝取到 Prometheus 時都將始終得到 my_classic_hist{le="1.0"}。此項更改的影響是，直接引用整數標籤值（如 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 文件。

本頁內容