PrometheusにおけるUTF-8

はじめに

Prometheus 3.0 より前のバージョンでは、メトリック名とラベル名は厳格な文字要件に従う必要がありました。Prometheus 3.0 では、すべての UTF-8 文字列が有効な名前となりますが、UTF-8 文字を含む名前を導入するために、エコシステムの他の部分には手動の変更が必要となる場合があります。

また、古い Prometheus やまだ UTF-8 をサポートしていない他のスクレイパーとの互換性のために、レガシー文字セットを強制したい場合もあります。

このドキュメントでは、UTF-8 移行の詳細について説明します。

Go のインストルメンテーション

現在、公式の Prometheus client_golang ライブラリによって作成されたメトリックは、デフォルトで UTF-8 名を受け入れます。

以前は、ドキュメントでは、ユーザーが `model.NameValidationScheme` の値をオーバーライドして、デフォルトでレガシー検証を選択することを推奨していました。このブール値は廃止され、常に `UTF8Validation` に設定されるべきです。レガシー検証の強制が必要な場合は、個々の実装で適切な検証 API を呼び出すことによって行われ、ライブラリ機能ではなくなります。

その他の言語でのインストルメンテーション

他のクライアントライブラリでは、まだ UTF-8 がサポートされていない場合があり、特別な処理や設定が必要になることがあります。使用しているライブラリのドキュメントを確認してください。

スクレイピング中の名前検証の設定

デフォルトでは、Prometheus 3.0 はすべての UTF-8 文字列を有効なメトリック名およびラベル名として受け入れます。スクレイプされたターゲットに対してこの動作をオーバーライドし、レガシー文字セットに準拠していない名前を拒否することができます。

このオプションは、Prometheus YAML ファイルでグローバルに設定できます。

global:
  metric_name_validation_scheme: legacy

または、スクレイプ設定ごとに設定できます。

scrape_configs:
  - job_name: prometheus
    metric_name_validation_scheme: legacy

スクレイプ設定の設定は、グローバル設定をオーバーライドします。スクレイプ設定の検証が設定されているが、エスケープスキームが設定されていない場合、エスケープスキームは検証スキームから推測されます。これにより、ユーザーは `metric_name_validation_scheme` のみをスクレイプ設定に指定し、`metric_name_escaping_scheme` を指定する必要がなくなります。

UTF-8 エスケープのためのスクレイプコンテンツネゴシエーション

スクレイプ時には、UTF-8 名をサービスとして提供するには、スクレイピングシステムは Accept ヘッダーに `escaping=allow-utf-8` を渡す必要があります。スクレイプターゲットがこのヘッダーを表示しない場合、UTF-8 名はアンダースコア置換を使用してレガシー互換に自動的に変換されます。

Prometheus および互換性のあるスクレイピングシステムは、必要に応じて `escaping` ヘッダーを別の値に設定することで、特定のエスケープ方法を要求することもできます。

`underscores`: デフォルト：レガシー無効文字をアンダースコアに変換します。
`dots`: UnderscoreEscaping と似ていますが、ドットが `_dot_` に変換され、既存のアンダースコアが `__` に変換されます。これにより、ドットを含む単純なメトリック名をラウンドトリップできます。
`values`: このモードは、名前に `U__` をプレフィックスとして追加し、無効な文字をすべて Unicode 値に置き換え、アンダースコアで囲みます。単一のアンダースコアは二重アンダースコアに置き換えられます。このモードにより、レガシー Prometheus と UTF-8 名の完全なラウンドトリップが可能になります。

コンテンツネゴシエーションでの UTF-8 サポートのアナウンスは、Prometheus が UTF-8 文字を受け入れる能力があることを示していますが、メトリック名に以前はサポートされていなかった文字が含まれていることを要求するものではありません。また、UTF-8 サポートをアナウンスする Accept ヘッダーが、メトリックプロデューサーに名前変換を無効にすることを要求するものでもありません。正確な名前変換戦略の選択は、メトリックプロデューサー次第です。要件は、Prometheus が allow-utf-8 以外のエスケープスキームを要求した場合、プロデューサーが要求された方法で名前を変換することです。

Remote Write 2.0

Remote Write 2.0 は、Prometheus 3.0 ではすべての UTF-8 名を自動的に受け入れます。Remote Write 2.0 でレガシー文字セット検証を強制する方法はありません。

OTLP メトリック

Prometheus 3.0 の OTLP レシーバーは、デフォルトではすべての名前を Prometheus フォーマットに正規化します。これは Prometheus 設定の `otlp` セクションで次のように変更できます。

otlp:
  # Ingest OTLP data keeping UTF-8 characters in metric/label names.
  translation_strategy: NoTranslation

タイプと単位の接尾辞を付加しない場合、同じ名前でもタイプや単位が異なる 2 つのメトリックが存在すると、Prometheus で競合が発生することに注意してください。Prometheus がタイプと単位のメタデータをネイティブにサポートするようになると、この問題は解消されます。

詳細については、OpenTelemetry ガイドを参照してください。

クエリ

UTF-8 名を持つメトリックのクエリには、PromQL で少し異なる構文が必要になります。

従来のクエリ構文は、レガシー互換名では引き続き機能します。

my_metric{}

しかし、UTF-8 名は引用符で囲み、中括弧内に入れる必要があります。

{"my.metric"}

レガシー非互換文字を含むラベル名も引用符で囲む必要があります。

{"metric.name", "my.label.name"="bar"}

メトリック名は中括弧内のどこにでも出現できますが、スタイルとしては最初の項であることが推奨されます。

このページの内容