UTF-8メトリクスおよびラベル名のエスケープスキーム
概要
このドキュメントでは、Prometheusが、レガシー文字セット以外の文字を含むメトリクス名およびラベル名を生成する際に使用するさまざまなエスケープスキームについて説明します。これらのスキームは、AcceptおよびContent-Typeヘッダーのescapingパラメータを介して、スクレイピング中にネゴシエートされます。
はじめに
Prometheusは、レガシー文字セット（a-zA-Z0-9_:）以外の文字を含むテキスト表示のメトリクス名とラベル名を処理するために、複数のエスケープスキームをサポートしています。エスケープスキームはスクレイピング中にネゴシエートされ、メトリクスプロデューサーがメトリクス名をどのようにフォーマットすべきかに影響します。
エスケープスキーム
エスケープなし (allow-utf-8)
ヘッダー値: escaping=allow-utf-8
動作:
- メトリクス名およびラベル名は有効なUTF-8文字列である必要があります。
- 名前が展示フォーマットで二重引用符内に現れる場合、
\、\n、および"はバックスラッシュでエスケープする必要があります。 - 名前が展示フォーマットで引用符なしで現れる場合、
\および\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_:)以外の各文字は、アンダースコアで囲まれた16進数形式のUnicodeコードポイントに置き換える必要があります。
- 単一のアンダースコアは二重アンダースコアに置き換える必要があります。
- 例:
metric.nameはU__metric_2E_nameになります（ここで、2Eは'.'の16進数Unicodeコードポイントです）。
デフォルトの動作
Acceptヘッダーにエスケープスキームが指定されていない場合、underscoresエスケープを使用することを推奨します。
セキュリティに関する考慮事項
- ターゲットは、エスケープを適用する前に、入力名を検証する必要があります。
- インジェクション攻撃を防ぐために、エスケープスキームを検証する必要があります。
allow-utf-8スキームは、プロデューサーとコンシューマーの両方がUTF-8名をサポートしている場合にのみ使用する必要があります。