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

> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/metrics/sdk_exporters/prometheus/


**ステータス**: [Mixed](../../../document-status/)

## Prometheusエクスポーターモデル

### Pull Metric Exporter

**ステータス**: [Development](../../../document-status/)

Prometheusエクスポーターは[Pull Metric Exporter](../../sdk/#pull-metric-exporter)であり、HTTPリクエストに対して適切な形式のPrometheusメトリクスで応答するものでなければなりません（MUST）。

### メトリクスの変換

**ステータス**: [Development](../../../document-status/)

OpenTelemetryのメトリクスは、[Prometheus互換性仕様](/works/otel-specs-ja/spec/compatibility/prometheus_and_openmetrics/)に従ってPrometheusのメトリクスへMUST変換されるものとします。

### クライアントライブラリ

**ステータス**: [Stable](../../../document-status/)

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

### バージョンと形式

**ステータス**: [Stable](../../../document-status/)

Prometheusクライアントライブラリが使われるかどうかにかかわらず、Prometheusエクスポーターは[テキストベース形式](https://github.com/prometheus/docs/blob/main/docs/instrumenting/exposition_formats.md#prometheus-text-format)のバージョン`0.0.4`をMUSTサポートするものとします。
Prometheusエクスポーターは、他のプロトコルをサポートすることで、[現時点でPrometheusテキスト形式ではサポートされていない](/works/otel-specs-ja/spec/compatibility/prometheus_and_openmetrics/#differences-between-prometheus-formats)ExemplarとExponential Histogramをサポートしてもかまいません（MAY）が、それらを実装することは必須ではありません。

OpenTelemetryメトリクスSDK向けのPrometheusエクスポーターは、[Prometheus Remote Write形式](https://github.com/prometheus/prometheus/blob/main/prompb/remote.proto)や[OpenMetrics protobuf形式](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#protobuf-format)をMUST NOT使用するものとします。

OpenTelemetryメトリクスSDK向けのPrometheusエクスポーターは、[Metric pointに明示的なタイムスタンプ](https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#metric)をSHOULD NOT追加するものとします。

## SDKメトリクス出力

### Target

**ステータス**: [Stable](../../../document-status/)

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

### Temporality

**ステータス**: [Stable](../../../document-status/)

Prometheusエクスポーターは、[MetricReader](../../sdk/#metricreader)の`temporality`を、すべてのInstrument種別について`cumulative`とする関数としてMUST設定するものとします。

## 設定

### Host

**ステータス**: [Stable](../../../document-status/)

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

### Port

**ステータス**: [Stable](../../../document-status/)

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

### デフォルトの集約

**ステータス**: [Stable](../../../document-status/)

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

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

**ステータス**: [Development](../../../document-status/)

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

### 変換戦略

**ステータス**: [Development](../../../document-status/)

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

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

### Scope Info

**ステータス**: [Stable](../../../document-status/)

Prometheusエクスポーターは、メトリクスに[スコープラベル](/works/otel-specs-ja/spec/compatibility/prometheus_and_openmetrics/#instrumentation-scope-1)を含めるかどうかを指定する設定をサポートしてもかまいません（MAY）。このオプションは`scope_info_enabled`と名付けてもかまいません（MAY）が、デフォルトでは`true`でなければなりません（MUST）。

### Target Info

**ステータス**: [Development](../../../document-status/)

Prometheusエクスポーターは、[target info](/works/otel-specs-ja/spec/compatibility/prometheus_and_openmetrics/#resource-attributes-1)メトリクスを生成するかどうかを指定する設定をサポートしてもかまいません（MAY）。このオプションは`target_info_enabled`と名付けてもかまいません（MAY）が、デフォルトでは`true`でなければなりません（MUST）。

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

**ステータス**: [Development](../../../document-status/)

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

### 変換戦略との相互作用

**ステータス**: [Development](../../../document-status/)

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

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

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

| `translation_strategy` | `escaping`パラメータなし、または`escaping=underscores` | `escaping=allow-utf-8` |
| :--- | :--- | :--- |
| `UnderscoreEscapingWithSuffixes` | `foo_bar_bytes_total` | `foo_bar_bytes_total` |
| `UnderscoreEscapingWithoutSuffixes` | `foo_bar` | `foo_bar` |
| `NoUTF8EscapingWithSuffixes` | `foo_bar_bytes_total` | `foo.bar_bytes_total` |
| `NoTranslation` | `foo_bar` | `foo.bar` |