Prometheus logo

Prometheus

文件下載社群支援與培訓部落格

Ctrl + K

GitHub Logo

抓取協議內容協商

摘要

本文件規範了 Prometheus 從目標抓取指標時使用的協議協商機制。它定義了 Accept 標頭格式、支援的 Content Type（內容型別）以及用於確定最佳可用指標展示格式的協商過程。

簡介

Prometheus 支援多種用於抓取指標的格式，包括基於文字的格式和二進位制 protobuf 格式。根據 Accept 標頭的值，目標將選擇最合適的可用 Content Type 進行回覆。

協議型別

支援的協議

Prometheus 支援以下協議

  1. PrometheusProto - 二進位制 protobuf 格式
  2. PrometheusText0.0.4 - Prometheus 文字格式版本 0.0.4
  3. PrometheusText1.0.0 - Prometheus 文字格式版本 1.0.0
  4. OpenMetricsText0.0.1 - OpenMetrics 文字格式版本 0.0.1
  5. OpenMetricsText1.0.0 - OpenMetrics 文字格式版本 1.0.0

協議標頭

每個協議都必須與特定的 MIME 型別和版本相關聯

協議MIME 型別引數
PrometheusProtoapplication/vnd.google.protobufproto=io.prometheus.client.MetricFamily;encoding=delimited
PrometheusText0.0.4text/plainversion=0.0.4
PrometheusText1.0.0text/plainversion=1.0.0
OpenMetricsText0.0.1application/openmetrics-textversion=0.0.1
OpenMetricsText1.0.0application/openmetrics-textversion=1.0.0

Accept 標頭的構建

Accept 標頭由 Prometheus 構建，用於指示其支援的格式。

基本格式

Accept 標頭必須按如下方式構建

  1. 對於目標支援的每個協議
    • 必須指定該協議的 MIME 型別和引數。
    • 對於 protobuf 協議，必須指定 "delimited" 編碼。
    • 對於 PrometheusText1.0.0 和 OpenMetricsText1.0.0，應該追加轉義方案引數。
    • 應該追加權重值（q）引數。
  2. 應該追加一個具有最低權重值的萬用字元 */*。

權重值 (Quality Values)

權重值應該根據協議在 Accept 標頭中的位置按降序分配

  • 第一個協議：q=0.{n+1}
  • 第二個協議：q=0.{n}
  • 依此類推，其中 n 是支援的協議數量

轉義方案

對於 PrometheusText1.0.0 和 OpenMetricsText1.0.0 協議，Accept 標頭應該包含一個轉義方案引數：escaping=<scheme>

其中 <scheme> 必須是以下之一

  • allow-utf-8
  • underscores
  • dots
  • values

有關轉義方案如何運作的詳細資訊，請參見 轉義方案 規範。

壓縮

Accept-Encoding 標頭應該設定為

  • 如果啟用了壓縮，則為 gzip
  • 如果停用了壓縮，則為 identity

格式選擇

抓取目標應該根據 Prometheus 生成的 Accept 標頭中的協議列表，使用以下過程來選擇合適的 Content-Type

  1. 它必須使用 Accept 標頭中權重最高且 Prometheus 支援的協議。
  2. 如果不支援任何協議，目標可以使用使用者配置的備用抓取協議。
  3. 如果未指定備用協議，則目標必須使用 PrometheusText0.0.4 作為最後手段。

Content-Type 響應

目標應該響應一個與接受的格式之一相匹配的 Content-Type 標頭。Content-Type 標頭必須包含

  1. 相應的 MIME 型別。
  2. version（版本）引數。
  3. 對於 1.0.0 及以上版本的文字格式，轉義方案引數。

安全考量

  1. 目標必須驗證 Accept 標頭，以防止潛在的注入攻擊
  2. 必須驗證轉義方案引數，以防止協議混淆
  3. 必須正確淨化 Content-Type 標頭，以防止 MIME 型別混淆

示例

預設 Accept 標頭

Accept: application/openmetrics-text;version=1.0.0;escaping=allow-utf-8;q=0.5,application/openmetrics-text;version=0.0.1;q=0.4,text/plain;version=1.0.0;escaping=allow-utf-8;q=0.3,text/plain;version=0.0.4;q=0.2,/;q=0.1

Protobuf 優先 Accept 標頭

Accept: application/vnd.google.protobuf;proto=io.prometheus.client.MetricFamily;encoding=delimited;q=0.5,application/
openmetrics-text;version=1.0.0;escaping=allow-utf-8;q=0.4,application/openmetrics-text;version=0.0.1;q=0.3,text/plain;version=1.0.0;escaping=allow-utf-8;q=0.2,text/plain;version=0.0.4;q=0.1,/;q=0.0

本頁內容