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. 最も低い品質値を持つ包括的な`*/*`を追加することを推奨します。

品質値

品質値は、Acceptヘッダー内のプロトコルの位置に基づいて降順に割り当てるべきです。

  • 最初のプロトコル: q=0.{n+1}
  • 2番目のプロトコル: q=0.{n}
  • 以下同様に、nはサポートされるプロトコルの数

エスケープスキーム

PrometheusText1.0.0およびOpenMetricsText1.0.0プロトコルでは、Acceptヘッダーにエスケープスキームパラメータ`escaping=`を含める必要があります。

ここで、`scheme`は次のいずれかである必要があります。

  • allow-utf8
  • underscores
  • dots
  • values

エスケープスキームの機能については、エスケープスキームの仕様を参照してください。

圧縮

Accept-Encoding ヘッダーは次のように設定されるべきです。

  • 圧縮が有効な場合は`gzip`
  • 圧縮が無効な場合は`identity`

フォーマットの選択

スクレイピングターゲットは、Prometheusによって生成されたAcceptヘッダー内のプロトコルリストに基づいて、適切なContent-Typeを選択するために以下のプロセスを使用すべきです。

  1. Prometheusがサポートする、最も高い重み付けを持つAcceptヘッダー内のプロトコルを使用しなければなりません。
  2. サポートされるプロトコルがない場合、ターゲットはユーザーが設定したフォールバックのスクレイピングプロトコルを使用することができます。
  3. フォールバックが指定されていない場合、ターゲットは最終手段としてPrometheusText0.0.4を使用しなければなりません。

Content-Typeレスポンス

ターゲットは、受け入れられたフォーマットのいずれかに一致するContent-Typeヘッダーで応答すべきです。Content-Typeヘッダーには以下を含まなければなりません。

  1. 適切なMIMEタイプ。
  2. バージョンパラメーター。
  3. バージョン1.0.0以降のテキスト形式の場合、エスケープスキームパラメーター。

セキュリティに関する考慮事項

  1. ターゲットは、潜在的なインジェクション攻撃を防ぐためにAcceptヘッダーを検証しなければなりません。
  2. プロトコル混同を防ぐため、エスケープスキームパラメータは検証されなければなりません。
  3. MIMEタイプの混同を防ぐため、Content-Typeヘッダーは適切にサニタイズされなければなりません。

例

デフォルトのAcceptヘッダー

Accept: application/openmetrics-text;version=1.0.0;escaping=allow-utf8;q=0.5,application/openmetrics-text;version=0.0.1;q=0.4,text/plain;version=1.0.0;escaping=allow-utf8;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-utf8;q=0.4,application/openmetrics-text;version=0.0.1;q=0.3,text/plain;version=1.0.0;escaping=allow-utf8;q=0.2,text/plain;version=0.0.4;q=0.1,/;q=0.0

このページの内容