メトリクスエクスポーター - Prometheus

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/prometheus/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: Mixed

Prometheusエクスポーターモデル

Pull Metric Exporter

ステータス: Development

PrometheusエクスポーターはPull Metric Exporterであり、HTTPリクエストに対して適切な形式のPrometheusメトリクスで応答するものでなければなりません（MUST）。

メトリクスの変換

ステータス: Development

OpenTelemetryのメトリクスは、Prometheus互換性仕様に従ってPrometheusのメトリクスへMUST変換されるものとします。

クライアントライブラリ

ステータス: Stable

Prometheusエクスポーターは、実装言語向けの公式なPrometheusクライアントライブラリが存在し、それを使うことが（依存関係の懸念などの観点から）実用的である場合、Prometheusメトリクスを提供するためにそれをSHOULD使用するものとします。非公式なPrometheusクライアントライブラリはSHOULD NOT使用しないものとします。 これにより、PrometheusクライアントはContent-Typeヘッダーを使ってレスポンスの形式をネゴシエートできます。Prometheusクライアントライブラリが使われる場合、OpenTelemetry PrometheusエクスポーターはカスタムCollectorとしてモデル化されるべきです（SHOULD）。これにより、既存のPrometheus計装と組み合わせて利用できます。

バージョンと形式

ステータス: Stable

Prometheusクライアントライブラリが使われるかどうかにかかわらず、Prometheusエクスポーターはテキストベース形式のバージョン0.0.4をMUSTサポートするものとします。 Prometheusエクスポーターは、他のプロトコルをサポートすることで、現時点でPrometheusテキスト形式ではサポートされていないExemplarとExponential Histogramをサポートしてもかまいません（MAY）が、それらを実装することは必須ではありません。

OpenTelemetryメトリクスSDK向けのPrometheusエクスポーターは、Prometheus Remote Write形式やOpenMetrics protobuf形式をMUST NOT使用するものとします。

OpenTelemetryメトリクスSDK向けのPrometheusエクスポーターは、Metric pointに明示的なタイムスタンプをSHOULD NOT追加するものとします。

SDKメトリクス出力

Target

ステータス: Stable

SDKのPrometheusエクスポーターによって公開されるtarget情報メトリクスは、最大でも1つでなければなりません（MUST）。

Temporality

ステータス: Stable

Prometheusエクスポーターは、MetricReaderのtemporalityを、すべてのInstrument種別についてcumulativeとする関数としてMUST設定するものとします。

設定

Host

ステータス: Stable

Prometheusエクスポーターは、メトリクスを提供するホストを設定するオプションをSHOULDサポートするものとします。このオプションはhostと名付けてもかまいません（MAY）が、デフォルトではlocalhostでなければなりません（MUST）。

Port

ステータス: Stable

Prometheusエクスポーターは、メトリクスを提供するポートを設定するオプションをSHOULDサポートするものとします。このオプションはportと名付けてもかまいません（MAY）が、デフォルトでは9464でなければなりません（MUST）。

デフォルトの集約

ステータス: Stable

Prometheusエクスポーターは、MetricReaderのデフォルトのaggregationをInstrument種別の関数として設定するオプションをSHOULDサポートするものとします。このオプションはdefault_aggregationと名付けてもかまいません（MAY）が、デフォルトではデフォルトの集約をMUST使用するものとします。

メトリクスラベルとしてのリソース属性

ステータス: Development

Prometheusエクスポーターは、リソース属性をメトリクスラベルとして追加する設定を提供してもかまいません（MAY）。デフォルトでは、リソース属性をメトリクスラベルとして追加してはなりません（MUST NOT）。 この設定は、利用者が含めるまたは除外するリソース属性を選択できるようにSHOULDするものとします。コピーされたリソース属性はtarget_infoメトリクスから除外してはなりません（MUST NOT）。このオプションはresource_constant_labelsと名付けるべきです（SHOULD）。

変換戦略

ステータス: Development

Prometheusエクスポーターは、メトリクス名をOpenTelemetryの命名規則からPrometheusの命名規則へ変換する方法を制御する設定オプションをサポートしてもかまいません（MAY）。Prometheusエクスポーターがそうした設定をサポートする場合、それはPrometheusの設定オプションtranslation_strategyに似た名前でなければならず（MUST）、変換の選択肢は以下でなければなりません（MUST）。

• UnderscoreEscapingWithSuffixes（デフォルト）。これは、クラシックなPrometheusのメトリクス名との互換性のためにメトリクス名を完全にエスケープし、型・単位のサフィックスの付加も含みます。
• UnderscoreEscapingWithoutSuffixes。メトリクス名は特殊文字を_にエスケープし続けますが、サフィックスは付加されません。
• NoUTF8EscapingWithSuffixesは特殊文字を_に変換する処理を無効にします。単位やCounterの_totalのような特殊なサフィックスは付加されます。
• NoTranslation。この戦略はメトリクス名とラベル名のすべての変換を回避し、そのまま通過させます。

Scope Info

ステータス: Stable

Prometheusエクスポーターは、メトリクスにスコープラベルを含めるかどうかを指定する設定をサポートしてもかまいません（MAY）。このオプションはscope_info_enabledと名付けてもかまいません（MAY）が、デフォルトではtrueでなければなりません（MUST）。

Target Info

ステータス: Development

Prometheusエクスポーターは、target infoメトリクスを生成するかどうかを指定する設定をサポートしてもかまいません（MAY）。このオプションはtarget_info_enabledと名付けてもかまいません（MAY）が、デフォルトではtrueでなければなりません（MUST）。

コンテンツネゴシエーション

ステータス: Development

Prometheusエクスポーターは、HTTPリクエストのAcceptヘッダーに基づいて、クライアントが異なる形式でメトリクスを要求できるようにするコンテンツネゴシエーションをMUSTサポートするものとします。コンテンツネゴシエーションはPrometheusコンテンツネゴシエーションガイドラインにMUST従うものとします。

変換戦略との相互作用

ステータス: Development

設定されたtranslation_strategyにかかわらず、最終的な出力形式と文字エスケープは、コンテンツネゴシエーションのAcceptヘッダーに基づく制約にMUST準拠するものとします。

まず、translation_strategyがMUSTメトリクス名の構築に適用されるものとします。次に、Prometheusエクスポーターは、要求されたエスケープスキームを使ったメトリクス名の2回目の変換を含むことがあるコンテンツネゴシエーションをMUST適用するものとします。

例えば、単位Byを持つfoo.barという名前のCounterメトリクスの場合は以下の通りです。