PrometheusにおけるUTF-8

はじめに

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

また、古いPrometheusやまだUTF-8をサポートしていない他のスクレーパーとの互換性のために、レガシー文字セットを強制したい状況もあるかもしれません。

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

Goによる計測

現在、公式のPrometheus client_golangライブラリによって作成されたメトリックは、デフォルトでUTF-8名を拒否します。UTF-8を許可するようにデフォルトの検証スキームを変更する必要があります。この値を設定する要件は、将来の共通ライブラリのバージョンで削除されます。

import "github.com/prometheus/common/model"

func init() {
	model.NameValidationScheme = model.UTF8Validation
}

ユーザーがレガシー文字セットを強制したい場合は、検証スキームをLegacyValidationに設定できます。

検証スキームの設定は、メトリックのインスタンス化前に行う必要があり、必要であれば実行中に設定できます。

他の言語での計測

他のクライアントライブラリも、検証スキームを設定するために同様の要件を持つ場合があります。使用しているライブラリのドキュメントを確認してください。

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

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

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

global:
  metric_name_validation_scheme: legacy

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

scrape_configs:
  - job_name: prometheus
    metric_name_validation_scheme: legacy

スクレイプ構成の設定は、グローバル設定を上書きします。

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

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

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

• underscores: デフォルト。レガシー互換でない文字をアンダースコアに変換します。
• dots: UnderscoreEscapingに似ていますが、ドットは`_dot_`に変換され、既存のアンダースコアは`__`に変換されます。これにより、ドットを含む単純なメトリック名の往復が可能になります。
• values: このモードでは、名前に`U__`を前置し、すべての無効な文字をアンダースコアで囲まれたユニコード値に置き換えます。単一のアンダースコアは二重アンダースコアに置き換えられます。このモードにより、レガシー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: NoUTF8EscapingWithSuffixes

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

クエリ

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

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

my_metric{}

しかし、UTF-8名は引用符で囲み、中括弧の中に移動する必要があります

{"my.metric"}

ラベル名にレガシー互換でない文字が含まれている場合も引用符で囲む必要があります

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

メトリック名は中括弧内のどこにでも記述できますが、慣例として最初の項目に置くのが好ましいです。