UTF-8メトリック名とラベル名のエスケープ方式
概要
このドキュメントでは、レガシー文字セット外の文字を含むメトリック名とラベル名のテキストExpositionを生成する際にPrometheusが使用するさまざまなエスケープ方式を規定します。これらの方式は、`Accept`ヘッダーと`Content-Type`ヘッダーの`escaping`パラメータを介してスクレイプ時にネゴシエートされます。
はじめに
Prometheusは、レガシー文字セット（a-zA-Z0-9_:）外の文字を含むテキストExpositionのメトリック名とラベル名を処理するために、複数のエスケープ方式をサポートしています。エスケープ方式はスクレイプ時にネゴシエートされ、メトリックの生成者がメトリック名をどのようにフォーマットすべきかに影響します。
エスケープ方式
エスケープなし (allow-utf-8)
ヘッダー値: `escaping=allow-utf-8`
動作:
- メトリック名とラベル名は、有効なUTF-8文字列でなければなりません。
- 名前がExpositionフォーマット内で二重引用符で囲まれている場合、`\`、`\n`、`"`はバックスラッシュでエスケープされなければなりません。
- 名前がExpositionフォーマット内で引用符で囲まれていない場合、`\`と`\n`はバックスラッシュでエスケープされなければなりません。
- この方式は、生成者と消費者の両方がUTF-8名をサポートしている場合にのみ使用しなければなりません。
アンダースコアエスケープ (underscores)
ヘッダー値: `escaping=underscores`
動作:
- レガシー文字セット（a-zA-Z0-9_:)に含まれない文字は、アンダースコアに置き換えられなければなりません。
- 最初の文字は、文字、アンダースコア、またはコロンでなければなりません。
- 後続の文字は、文字、数字、アンダースコア、またはコロンでなければなりません。
- 例: `metric.name/with/slashes`は`metric_name_with_slashes`になります。
ドットエスケープ (dots)
ヘッダー値: `escaping=dots`
動作:
- ドット（.）は`_dot_`に置き換えられなければなりません。
- 既存のアンダースコアは、二重アンダースコア（`__`）に置き換えられなければなりません。
- その他の非レガシー文字は、単一のアンダースコアに置き換えられなければなりません。
- 最初の文字は、文字、アンダースコア、またはコロンでなければなりません。
- 後続の文字は、文字、数字、アンダースコア、またはコロンでなければなりません。
- 例: `metric.name.with.dots`は`metric_dot_name_dot_with_dot_dots`になります。
値エンコーディングエスケープ (values)
ヘッダー値: `escaping=values`
動作:
- 名前は`U__`で始まらなければなりません。
- レガシー文字セット（a-zA-Z0-9_:)に含まれない各文字は、そのUnicodeコードポイントを16進数で表し、アンダースコアで囲んで置き換えられなければなりません。
- 単一のアンダースコアは、二重のアンダースコアに置き換えられなければなりません。
- 例: `metric.name`は`U__metric_2E_name`になります（2Eは「.」の16進数Unicodeコードポイントです）。
デフォルトの動作
Acceptヘッダーでエスケープ方式が指定されていない場合、`underscores`エスケープを使用すべきです。
セキュリティに関する考慮事項
- ターゲットは、エスケープを適用する前に入力名を検証しなければなりません。
- インジェクション攻撃を防ぐために、エスケープ方式を検証しなければなりません。
- `allow-utf-8`方式は、生成者と消費者の両方がUTF-8名をサポートしている場合にのみ使用しなければなりません。