PrometheusとOpenMetricsとの互換性

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

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

ステータス: Mixed

Differences between Prometheus formats

この文書は、以下を含む、さまざまなPrometheus関連の形式とのOpenTelemetryの互換性を扱います。

メトリクスのスクレイピング（プル）に使われる形式:

Prometheusテキスト表現形式
Prometheus protobuf形式
OpenMetricsテキスト形式
（Prometheusではまだサポートされていない）OpenMetrics protobuf形式

メトリクスのプッシュに使われる形式:

Prometheus Remote Write形式

以下の文書では、特定の機能が個々の形式でサポートされていない場合もありますが、これらすべての形式の総称として「Prometheus」を使います。形式ごとに仕様を重複して記述することを避けるため、この文書には、すべてのPrometheus形式で実装可能とは限らない要求事項が含まれます。執筆時点で、以下の機能は一貫してサポートされていません。

エグゼンプラーは、現在Prometheusテキスト表現形式ではサポートされていません。
- サポートされていない場合、エグゼンプラーは破棄されなければなりません（MUST）。
Info型とStateSet型のメトリクスは、現在Prometheusテキスト表現形式またはPrometheus protobuf形式ではサポートされていません。
- 以下の仕様がPrometheusのInfo型メトリクスの生成を要求している場合、Info型メトリクスがサポートされていなければ、_infoという追加のサフィックスを持つPrometheusのGaugeを生成しなければなりません（MUST）。
- 以下の仕様がPrometheusのStateSet型メトリクスの生成を要求している場合、StateSet型メトリクスがサポートされていなければ、代わりにPrometheusのGaugeを生成しなければなりません（MUST）。
指数（Native）Histogramは、現在Prometheusテキスト表現形式、またはOpenMetricsのテキスト形式・proto形式ではサポートされていません。
- サポートされていない場合、指数（Native）Histogramは破棄すべき（SHOULD）であり、固定バケットのHistogramへ変換してもかまいません（MAY）。

Prometheus Metric points to OTLP

ステータス: Development

Metric Metadata

ステータス: Stable

Prometheusのメトリクス名は、OTLPメトリクスの名前として追加されなければなりません（MUST）。名前は変更すべきではありません（SHOULD NOT）。

PrometheusのUNITメタデータが存在する場合、それはOTLPメトリクスの単位に変換されなければなりません（MUST）。単位が以下のよく使われる単位の集合に含まれる場合、単語からUCUMの略記へ翻訳されなければなりません（MUST）。

Prometheusの単位	UCUMの略記
`days`	`d`
`hours`	`h`
`minutes`	`min`
`seconds`	`s`
`milliseconds`	`ms`
`microseconds`	`us`
`nanoseconds`	`ns`
`bytes`	`By`
`kibibytes`	`KiBy`
`mebibytes`	`MiBy`
`gibibytes`	`GiBy`
`tebibytes`	`TiBy`
`kilobytes`	`kBy`
`megabytes`	`MBy`
`gigabytes`	`GBy`
`terabytes`	`TBy`
`meters`	`m`
`volts`	`V`
`amperes`	`A`
`joules`	`J`
`watts`	`W`
`grams`	`g`
`celsius`	`Cel`
`hertz`	`Hz`
`percent`	`%`

PrometheusのHELPメタデータが存在する場合、それはOTLPメトリクスの説明として追加されなければなりません（MUST）。

PrometheusのTYPEメタデータが存在する場合、それはOTLPのデータ型を決定するために使わなければならず（MUST）、以下に列挙する型固有の変換規則を左右します。TYPEメタデータを持たないメトリクスファミリーは、以下のunknown-typedメトリクスの規則に従います。TYPEメタデータは、OTLPのmetric.metadata内のprometheus.typeキー（例えばprometheus.type="unknown"）にも追加されなければなりません（MUST）。

Timestamps

ステータス: Stable

Prometheusのメトリクスサンプルの開始タイムスタンプ（Createdタイムスタンプとも呼ばれます）が存在する場合、それはOTLPデータポイントの開始タイムスタンプへ変換されなければなりません（MUST）。開始タイムスタンプが存在しない場合、OTLPデータポイントの開始時刻は未設定のままにすべきです（SHOULD）。

Prometheusのメトリクスサンプルのタイムスタンプが存在する場合、それはOTLPデータポイントのタイムスタンプへ変換されなければなりません（MUST）。明示的なタイムスタンプなしでPrometheusエンドポイントからスクレイピングされたメトリクスについては、OTLPデータポイントのタイムスタンプはスクレイピングを行った時刻に設定されなければなりません（MUST）。

Counters

ステータス: Stable

Prometheus Counterは、is_monotonicがtrueのOTLP Sumへ変換されなければなりません（MUST）。

Prometheus Counterのサンプルにあるエグゼンプラーは、Exemplarsの規則に従って、OpenTelemetry SumデータポイントのOpenTelemetryエグゼンプラーへ変換されなければなりません（MUST）。

Gauges

ステータス: Stable

Prometheus Gaugeは、OTLP Gaugeへ変換されなければなりません（MUST）。

Info

ステータス: Development

Prometheus Infoメトリクスは、リソース属性を構成するために使われるtargetのInfoメトリクスである場合を除き、OTLPの非モノトニックなSumへ変換されなければなりません（MUST）。Prometheus Infoメトリクスは、値が1で、そのラベルがプロセスの生存期間中おおむね変わらない、Prometheus Gaugeメトリクスの特殊なケースと考えることができます。OTLP Gaugeではなく非モノトニックなOTLP Sumへ変換されるのは、値の1がカウントとして見なされることを意図しており、ラベルを集約する際にはそれらを合算すべきだからです。

StateSet

ステータス: Development

Prometheus StateSetメトリクスは、OTLPの非モノトニックなSumへ変換されなければなりません（MUST）。Prometheus StateSetメトリクスは、値が0または1で、可能な状態それぞれについて1つのメトリクスポイントを持つ、Prometheus Gaugeの特殊なケースと考えることができます。OTLP Gaugeではなく非モノトニックなOTLP Sumへ変換されるのは、値の1がカウントとして見なされることを意図しており、ラベルを集約する際にはそれらを合算すべきだからです。

Unknown-typed

ステータス: Development

Prometheus Unknownは、OTLP Gaugeへ変換されなければなりません（MUST）。

Histograms

ステータス: Stable

Prometheus Histogramは、OTLP Histogramへ変換されなければなりません（MUST）。

Prometheusのバケット境界は、+Inf境界を除いてOTLPの明示的境界（explicit bounds）になります。Prometheusのバケット境界に関連付けられたサンプル値は、+Inf境界に関連付けられた値を含めて、OTLPのバケットカウントになります。Prometheus Histogramのカウントはそのままの形でOTLP Histogramのカウントになり、Prometheus HistogramのサムはOTLP Histogramのサムになります。

テキスト形式では、Prometheus Histogramのバケット、カウント、サムは別々のサンプルとして送出され、OTLP Histogramを構成する際にそれらをマージしなければなりません（MUST）。_bucketサフィックスを持つサンプルは、バケット境界を示すleラベルを持ち、その値はバケット境界より小さい観測値の総カウントです。OpenTelemetryバケットのカウントは、そのバケットと（存在する場合は）次に小さいバケットとの差として計算されます。_countと_sumサフィックスを持つ行は、Histogramのカウントとサムを決定するために使われます。

_countが存在しない場合、そのメトリクスは破棄されなければなりません（MUST）。
_sumが存在しない場合、Histogramのサムは未設定にしなければなりません（MUST）。

Prometheus Histogramのサンプルにあるエグゼンプラーは、Exemplarsの規則に従って、OpenTelemetry HistogramデータポイントのOpenTelemetryエグゼンプラーへ変換されなければなりません（MUST）。

Native Histograms

ステータス: Stable

標準的な（指数的な）スキーマ（すなわちスキーマ-4から8）を持ち、整数型かつCounterのflavorであるPrometheus Native Histogramは、以下のようにOTLPのExponential Histogramへ変換されなければなりません（MUST）。

Native HistogramのResetHint（またはCounterResetHint）がgauge型を示す場合、そのNative Histogramは破棄されます。それ以外の場合、このフィールドは無視されます。
SchemaはExponential HistogramのScaleへ変換されます。
SumがStale NaNの値と等しい場合、NoRecordedValueフラグはtrueに設定されます。そうでない場合、
- Countは、以下を合計したすべての有効なバケットカウントの合計になります。
  - ZeroCount。
  - 以下で説明する疎（sparse）バケットレイアウトからのバケットカウント。オーバーフローバケットは除きます。
- SumはExponential HistogramのSumへ変換されます。Native Histogramが値NaN、あるいは-Infと+Infの両方を観測した場合、SumはNaNになることがあることに注意してください。Sumは-Infまたは+Infになることもあります。
Timestampは、ミリ秒をナノ秒に変換した上で、Exponential HistogramのTimeUnixNanoへ変換されます。
ZeroCountは、そのままExponential HistogramのZeroCountへ変換されます。
ZeroThresholdは、Exponential HistogramのZeroThresholdへ変換されます。
PositiveSpansとPositiveDeltasが表す疎バケットレイアウトは、PositiveバケットカウントとOffsetが表すExponential Histogramの密（dense）レイアウトへ変換されます。
- PositiveDeltasは差分エンコードされたバケットカウントであり、最初の値は絶対的なバケットカウントで、以降の各値は直前の値との差分です。
- Exponential HistogramのPositiveのOffsetは、スパンが存在する場合は最初のPositiveSpanのOffsetから1を引いた値（PositiveSpans[0].Offset-1）に設定され、そうでなければ0のままにされます。1を引くのは、Prometheus Native Histogramのバケットが上限境界でインデックス付けされる一方、Exponential Histogramは下限境界でインデックス付けされるためです。
- PositiveSpansは、PositiveDeltas内の各値について、Positiveバケットカウントへのインデックスをエンコードします。インデックスは最初のスパンについては0から始まり、以降のスパンについては、そのスパンのOffsetを直前のインデックスに加算します。スパンのLengthは、使用する連続したインデックスの数を示します。
- Native Histogramにはオーバーフローバケットが含まれることがあります。Exponential Histogramバケットへ変換する場合、オーバーフローバケットはIEEE浮動小数点数の範囲外の値へマッピングされることになります。オーバーフローバケットは破棄しなければならず（MUST）、全体のCountにも数えてはなりません（MUST NOT）。
NegativeSpansとNegativeDeltasは、正のバケットと同じ方法で変換されます。
MinとMaxは設定されません。
StartTimeUnixNanoは、利用可能であればStart Timestampのタイムスタンプに設定されます。
AggregationTemporalityはcumulativeに設定されます。

カスタムバケット付きのNative Histogram（NHCB）スキーマ（すなわちスキーマ-53）を持ち、整数型かつCounterのflavorであるものは、以下のようにOTLP Histogramへ変換されなければなりません（MUST）。

Native HistogramのResetHint（またはCounterResetHint）がgauge型を示す場合、そのNative Histogramは破棄されます。それ以外の場合、このフィールドは無視されます。
SumがStale NaNの値と等しい場合、NoRecordedValueフラグはtrueに設定されます。そうでない場合、
- CountはHistogramのCountへ変換されます。Countはすべてのバケットカウントの合計に等しいことに注意してください。
- SumはHistogramのSumへ変換されます。Native Histogramが値NaN、あるいは-Infと+Infの両方を観測した場合、SumはNaNになることがあることに注意してください。Sumは-Infまたは+Infになることもあります。
Timestampは、ミリ秒をナノ秒に変換した上で、HistogramのTimeUnixNanoへ変換されます。
MinとMaxは設定されません。
CustomValuesはバケット境界へ変換されます。+Infバケットは暗黙的であるため、N個のCustomValuesはN+1個のHistogramバケットカウントを表します。
PositiveSpansとPositiveDeltasが表す疎バケットレイアウトは、Histogramのバケットカウントへ変換されます。
- PositiveDeltasは差分エンコードされたバケットカウントであり、最初の値は絶対的なバケットカウントで、以降の各値は直前の値との差分です。
- PositiveSpansは、PositiveDeltas内の各値について、バケットカウントへのインデックスをエンコードします。インデックスは最初のスパンのOffsetから始まり、以降のスパンについては、そのスパンのOffsetを直前のインデックスに加算します。スパンのLengthは、使用する連続したインデックスの数を示します。
StartTimeUnixNanoは、利用可能であればStart Timestampに設定されます。
AggregationTemporalityはcumulativeに設定されます。

floatまたはgaugeのflavorを持つNative Histogramは破棄されなければなりません（MUST）。

Schemaが[-4, 8]の範囲外であり、かつ-53とも等しくないNative Histogramは破棄されなければなりません（MUST）。

Prometheus Native Histogramのサンプルにあるエグゼンプラーは、Exemplarsの規則に従って、OpenTelemetry Exponential HistogramデータポイントのOpenTelemetryエグゼンプラーへ変換されなければなりません（MUST）。

Summaries

ステータス: Stable

Prometheus Summaryは、OTLP Summaryへ変換されなければなりません（MUST）。

Prometheus SummaryのQuantileはOTLP SummaryのQuantileになります。Prometheus Summaryのカウントは OTLP Summaryのカウントになり、Prometheus Summaryのサムは OTLP Summaryのサムになります。

テキスト形式では、サフィックスを持たないサンプルは、Prometheus Summaryの分位点を識別するためのquantileラベルを持ちます。同じメトリクス名を持つが_countと_sumのサフィックスを持つ追加のサンプルは、それぞれPrometheus Summaryのカウントとサムを識別するために使われます。

Prometheus Summaryが複数のサンプルで表現されるテキスト形式では、同じメトリクスファミリー名を持つサンプルは、単一のOTLP Summaryへマージされなければなりません（MUST）。

_countが存在しない場合、そのメトリクスは破棄されなければなりません（MUST）。
_sumが存在しない場合、Summaryのサムはゼロに設定されなければなりません（MUST）。

Dropped Types

ステータス: Stable

以下のPrometheusの型は破棄されなければなりません（MUST）。

Exemplars

ステータス: Stable

Prometheusエグゼンプラーは、以下のようにOpenTelemetryエグゼンプラーへ変換されなければなりません（MUST）。

タイムスタンプが存在する場合、それはOpenTelemetryエグゼンプラーのタイムスタンプとして使わなければなりません（MUST）。
trace_idとspan_idラベルが存在し、その値が有効なTrace IDとSpan IDである場合、それぞれOpenTelemetryエグゼンプラーのTrace IDとSpan IDへ変換されなければなりません（MUST）。
trace_idとspan_id以外のすべてのラベルは、フィルタリングされた属性としてOpenTelemetryエグゼンプラーに追加されなければなりません（MUST）。

Instrumentation Scope

ステータス: Stable

otel_scope_という接頭辞を持つラベルは、すべてのメトリクスポイントから破棄されなければならず（MUST）、Instrumentation Scopeの名前（otel_scope_name）、バージョン（otel_scope_version）、Schema URL（otel_scope_schema_url）、属性（otel_scope_[属性]）として使われます。

# TYPE http_server_duration counter
http_server_duration{otel_scope_name="go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp",otel_scope_schema_url="https://opentelemetry.io/schemas/1.31.0",otel_scope_version="v0.24.0",otel_scope_library_mascot="gopher"...} 1

は以下になります。

# within a resource_metrics
scope_metrics:
  scope:
    name: go.opentelemetry.io.contrib.instrumentation.net.http.otelhttp
    version: v0.24.0
    attributes:
      library_mascot: gopher
  schema_url: https://opentelemetry.io/schemas/1.31.0 
  metrics:
  - name: http_server_duration
    data:
      sum:
        data_points:
        - value: 1

otel_scope_という接頭辞を持つラベルを一切持たないメトリクスには、Prometheusから OpenTelemetryへの変換を行うエンティティ（例えばCollectorのPrometheusレシーバー）を識別するInstrumentation Scopeが割り当てられなければなりません（MUST）。

Resource Attributes

ステータス: Development

Prometheusエンドポイントをスクレイピングする際、他のPrometheusエンドポイントからのメトリクスと区別するために、リソース属性がスクレイピングされたメトリクスに追加されなければなりません（MUST）。特に、Prometheusエクスポーターがjobとinstanceラベルを使ってメトリクスを一意に区別できるようにするため、service.nameとservice.instance.idが必要です（後述のとおりです）。

以下の属性は、スクレイピングされたメトリクスにリソース属性として関連付けられなければならず（MUST）、メトリクス属性として追加してはなりません（MUST NOT）。

OTLPリソース属性	説明
`service.name`	対象が属するサービスの設定済みの名前
`service.instance.id`	対象の一意な識別子。既定では、スクレイピングされたURLの`<host>:<port>`にすべきです

以下の属性は、スクレイピングされたメトリクスにリソース属性として関連付けるべきであり（SHOULD）、メトリクス属性として追加してはなりません（MUST NOT）。

OTLPリソース属性	説明
`server.address`	スクレイピングされた対象のURLの`<host>`部分
`server.port`	スクレイピングされた対象のURLの`<port>`部分
`url.scheme`	`http`または`https`

上記の属性に加えて、target Infoメトリクスは、追加のリソース属性を提供するために使われます。target Infoメトリクスが存在する場合、それはメトリクスのバッチから破棄されなければならず（MUST）、target Infoメトリクスのすべてのラベルは、そのスクレイプの一部である他のすべてのメトリクスに付随するリソース属性へ変換されなければなりません（MUST）。既定では、ラベルのキーと値は（キー内の_を.文字に置き換えるなどの）変更を加えられてはなりません（MUST NOT）。

OTLP Metric points to Prometheus

Metric Metadata

ステータス: Stable

OpenTelemetryのメトリクスデータに対するPrometheus Pull用エクスポーターは、Prometheusエンドポイントの単一のスクレイプにおいて、同じメトリクス名について重複するUNIT、HELP、TYPEのコメントを返すことを許してはなりません（MUST NOT）。エクスポーターは、競合するTYPEコメントを避けるためメトリクス全体を破棄しなければなりません（MUST）が、競合するUNITやHELPコメントの結果としてメトリクスポイントを破棄すべきではありません（SHOULD NOT）。代わりに、競合するUNITとHELPコメント（メトリクスポイントは除く）のうち1つを除くすべてを破棄すべきです（SHOULD）。コメントやメトリクスポイントを破棄する場合、エクスポーターはエラーログを通じて利用者に警告すべきです（SHOULD）。なお、SDKは、同じ問題を示す計装の重複登録について利用者へ警告することが要求されていることに注意してください。

OTLPメトリクスの名前は、Prometheusのメトリクス名として追加されなければなりません（MUST）。Prometheusの命名規則は、メトリクス名が正規表現[a-zA-Z_:]([a-zA-Z0-9_:])*に一致することを推奨しています。Prometheusの規約との互換性を目指し、メトリクス名の中で推奨されない文字は、既定では_文字に置き換えるべきです（SHOULD）。連続する複数の_文字は、単一の_文字に置き換えるべきです（SHOULD）。

OTLPメトリクスポイントの単位は、上記のMetric Metadataにある表に含まれる場合、UCUMの単位からPrometheusにおける相当する単語へ変換されなければなりません（MUST）。

角括弧内の単位の部分（例えば{packet}）は破棄されなければなりません（MUST）。

時間に対する比率として定義された単位（例えば"m/s"）は、単語（例えば"meters_per_second"）へ変換されなければなりません（MUST）。

変換後の単位は、UNITメタデータとしてメトリクスに追加すべきです（SHOULD）。メトリクス名が（型固有のサフィックスの前で）既に単位で終わっていない限り、メトリクス名にサフィックスを追加すべきです（SHOULD）。単位のサフィックスは、型固有のサフィックスより前に置かれます。

OTLPメトリクスポイントの説明は、HELPメタデータとして追加されなければなりません（MUST）。

OTLPメトリクスのデータポイントの型は、TYPEメタデータとして追加されなければなりません（MUST）。これは、以下に列挙する型固有の変換規則も左右します。

Instrumentation Scope

ステータス: Stable

Prometheusエクスポーターは、元のデータポイントが入れ子になっていたScopeに基づき、既定でスコープ名をotel_scope_nameラベル、スコープバージョンをotel_scope_versionラベル、スコープのSchema URLをotel_scope_schema_urlラベルとして、すべてのメトリクスポイントに追加しなければならず（MUST）、スコープ属性は以下のMetric Attributesの節で説明する規則に従ってotel_scope_という接頭辞を持つラベルとして追加しなければなりません（MUST）。otel_scope_接頭辞を追加し、Metric Attributesで説明されているラベル名の変換を適用した後に、otel_scope_name、otel_scope_version、otel_scope_schema_urlと衝突することになるスコープ属性は、破棄されなければなりません（MUST）。

Gauges

ステータス: Stable

OpenTelemetry Gaugeは、metric.metadata内のヒントに従って変換されなければなりません（MUST）。

prometheus.typeキーが存在しない、またはその値がgaugeと等しい場合、そのデータポイントはPrometheus Gaugeへ変換されなければなりません（MUST）。
prometheus.typeキーの値がunkownと等しい場合、そのデータポイントはPrometheus Unknownへ変換されなければなりません（MUST）。
prometheus.typeキーの値がinfoと等しい場合、そのデータポイントはPrometheus Infoへ変換すべきです（SHOULD）。
prometheus.typeキーの値がstatesetと等しい場合、そのデータポイントはPrometheus Statesetへ変換すべきです（SHOULD）。

OpenTelemetry Gaugeにあるエグゼンプラーは破棄すべきです（SHOULD）。

Sums

ステータス: Stable

OpenTelemetry Sumは、以下の規則に従って変換されなければなりません（MUST）。

集約時間的性質（aggregation temporality）がcumulativeであり、そのSumがモノトニックである場合、Prometheus Counterへ変換されなければなりません（MUST）。
集約時間的性質がcumulativeであり、そのSumが非モノトニックである場合、OpenTelemetry Gaugeについて説明されているのと同じ規則に従うべきです（SHOULD）。
集約時間的性質がdeltaであり、そのSumがモノトニックである場合、cumulativeな時間的性質へ変換し、Prometheus Counterになってもかまいません（MAY）。以下の挙動が期待されます。
- 新しいデータポイントの型は、蓄積されたデータポイントの型と同じでなければなりません（MUST）。
- 新しいデータポイントの開始時刻は、蓄積されたデータポイントの時刻と一致しなければなりません（MUST）。一致しない場合は、整合性の問題の検出を参照してください。

モノトニックなSumメトリクスポイントのメトリクス名が_totalというサフィックスで終わっていない場合、既定では_totalというサフィックスを追加すべきです（SHOULD）。そうでない場合、名前は変更されないままでなければなりません（MUST）。

StartTimeUnixNanoを持つモノトニックなSumメトリクスポイントは、各Prometheusプロトコルで使われる適切な形式に従って、StartTimeUnixNanoをPrometheusのStartTimeへ変換すべきです（SHOULD）。

SumがPrometheus Counterへ変換される場合、ExemplarsはExemplar Conversionの節で説明されているように変換されなければなりません（MUST）。そうでない場合、Exemplarsは破棄すべきです（SHOULD）。Prometheusプロトコルが、Counterのサンプルについて単一のエグゼンプラーしかサポートしない場合、最新のエグゼンプラーを変換すべきです（SHOULD）。これは、Counter Instrumentについて最新のエグゼンプラーを保持するというPrometheusクライアントライブラリの挙動と一致します。

Histograms

ステータス: 特記のない限りStable

cumulativeな集約時間的性質を持つOpenTelemetry Histogramは、既定でPrometheus Histogramへ変換されなければなりません（MUST）。

Development: Prometheusプロトコルが許可する場合、利用者はOpenTelemetry HistogramをPrometheus Protocolが許可するカスタムバケット付きのPrometheus Native Histogram（NHCB）へ変換することをオプトインで選べます。

Deltaな集約時間的性質を持つOpenTelemetry Histogramは、Cumulativeな集約時間的性質へ集約して以下のロジックに従ってもよい（MAY）ものとし、そうでなければ破棄されなければなりません（MUST）。

Histograms as Prometheus Histograms

ステータス: Stable

Prometheus Histogramへ変換する場合、OpenTelemetry Histogramは以下の規則に従って変換されなければなりません（MUST）。

CountはHistogramのCountへ変換されます。
SumはHistogramのSumへ変換されます。Histogram内のすべての観測値が正またはゼロである場合、そのサムは正でモノトニックになります。
ExplicitBoundsのバケット境界と暗黙の+Inf境界、およびBucketCountsは、ExplicitBoundsの値の昇順でHistogramのBucketsへ変換されます。各バケットについて、明示的な境界は上限境界へ変換され、現在のバケットまでのすべてのバケットカウントの合計が累積カウントへ変換されます。
StartTimeUnixNanoが設定されている場合、各Prometheusプロトコルで使われる適切な形式に従って、PrometheusのStartTimeへ変換すべきです（SHOULD）。
MinとMaxは使われません。
ExemplarsはExemplar Conversionの節で説明されているように変換されます。Prometheusプロトコルがバケットごとに単一のエグゼンプラーしかサポートしない場合、各バケットに該当する最新のエグゼンプラーを変換すべきです（SHOULD）。

Histograms as Prometheus NHCB

ステータス: Development

NHCBの出力は、現在Prometheus Remote-Write 2.0以降のプロトコルでのみサポートされています。

Prometheus NHCBへ変換する場合、単一のNHCBメトリクスのみが作成されなければなりません（MUST）。

NHCBのflavorは整数型のCounterでなければなりません（MUST）。
NHCB内のResetHintはUNKNOWNに設定されなければなりません（MUST）。OpenTelemetryは明示的なリセットフラグを持たないため、UNKNOWNによってPrometheusが値からリセットを自動検出でき、OpenTelemetryのリセットモデルとの意味的な相違も避けられます。
NHCB内のSchemaは-53に設定されなければなりません（MUST）。
TimeUnixNanoは、ナノ秒をミリ秒に変換した上でPrometheusのTimestampへ変換されます。
StartTimeUnixNanoが設定されている場合、各Prometheusプロトコルで使われる適切な形式に従って、PrometheusのStartTimeへ変換すべきです（SHOULD）。
ExplicitBoundsのバケット境界は、昇順でNHCBのCustomValuesへ書き込まれます。暗黙の+Inf上限境界はCustomValuesに書き込んではならず（MUST NOT）、インデックスlen(CustomValues)のオーバーフローバケットによって表されます。
ここで明示的に言及されていないNHCBのすべてのフィールドは、zero threshold、zero count、negative spans、negative deltasなど、そのゼロ値に設定されなければなりません（MUST）。
MinとMaxは使われません。
Exemplarsは、Exemplar Conversionの節で説明されているように、Native HistogramのフラットなExemplarsのリストへ変換されます。
NoRecordedValueフラグがtrueに設定されている場合、NHCBはstaleとしてマークされなければなりません（MUST）。
- Native HistogramのSumはStale NaNの値に設定されなければなりません（MUST）。
- Native HistogramのCountはゼロに設定されなければなりません（MUST）。PositiveSpansとPositiveDeltasは空のままにしなければなりません（MUST）。
NoRecordedValueフラグがfalseに設定されている場合、
- CountはNative HistogramのCountへ変換されます。
- SumはNative HistogramのSumへ変換されます。
- 密なBucketCountsは、疎バケットレイアウトのPositiveSpansとPositiveDeltasへ変換されます（負の境界を持つバケットについても同様です）。
  - ゼロでないバケットカウントはPositiveDeltasへ変換されなければなりません（MUST）。ゼロカウントのバケットも、（スパンの間にギャップを作るのではなく）それを囲むスパンを拡張し、PositiveSpansの数を減らすために、PositiveDeltasに含めてもかまいません（MAY）。
  - 変換が必要なバケットカウントは、差分エンコードされたPositiveDeltasへ変換されます。最初に変換された値はそのまま書き込まれ、残りは直前に変換された値との差分として書き込まれます。Prometheus Histogramへの変換とは異なり、バケットをまたいだ累積の合算は不要です。OpenTelemetryとNative Histogramのバケットカウントは、すでにバケットごとの値になっているためです。
  - PositiveSpansは、PositiveDeltas内の各値について、CustomValuesへのインデックスをエンコードします。最初のスパンのOffsetは、最初に変換されたバケットの上限境界のインデックス（CustomValues内の0始まり）です。以降のスパンについては、Offsetは、直前のスパンの終わりから今回のスパンの開始までの間で変換されなかったバケットの数です。Lengthは、そのスパン内で連続して変換されたバケットの数です。
  - 例: バケット境界が-2, -1, 0, 1, 2, +Infで、バケットカウントが10, 0, 0, 20, 5, 2の場合、CustomValuesは-2, -1, 0, 1, 2になります。ゼロでないバケットカウント10, 20, 5, 2のみを変換する場合、PositiveSpansは{Offset: 0, Length: 1}, {Offset: 2, Length: 3}になり、PositiveDeltasは10, 10, -15, -3になります。

Exponential Histograms

ステータス: Development

cumulativeな集約時間的性質を持つOpenTelemetry Exponential Histogramは、以下のようにPrometheus Native Histogramへ変換されなければなりません（MUST）。

ScaleはNative HistogramのSchemaへ変換されます。現時点で、schemaの有効な値は-4 <= n <= 8です。Scaleが8より大きい場合、Exponential Histogramのデータポイントは、Prometheusが受け付ける範囲（[-4,8]）へダウンスケールすべきです（SHOULD）。許容範囲へリスケールできないデータポイントは破棄しなければなりません（MUST）。
NoRecordedValueフラグがfalseに設定されている場合、CountはNative HistogramのCountへ変換されます。そうでない場合、Native HistogramのCountはStale NaNの値に設定されます。
Sumが設定されており、NoRecordedValueフラグがfalseに設定されている場合、SumはNative HistogramのSumへ変換されます。そうでない場合、Native HistogramのSumはStale NaNの値に設定されます。
TimeUnixNanoは、ナノ秒をミリ秒に変換した上でNative HistogramのTimestampへ変換されます。
ZeroCountは、そのままNative HistogramのZeroCountへ変換されます。
ZeroThresholdが設定されている場合、Native HistogramのZeroThresholdへ変換されます。そうでない場合、既定値の1e-128に設定されます。
PositiveバケットカウントとOffsetが表す密なバケットレイアウトは、PositiveSpansとPositiveDeltasが表すNative Histogramの疎なレイアウトへ変換されます。NegativeバケットカウントとOffsetについても同様です。Prometheus Native Histogramのバケットは上限境界でインデックス付けされる一方、Exponential Histogramは下限境界でインデックス付けされるため、結果としてOffsetフィールドは1つずれることに注意してください。
MinとMaxは使われません。
StartTimeUnixNanoは使われません。
ExemplarsはExemplar Conversionの節で説明されているように変換されます。

deltaな集約時間的性質を持つOpenTelemetry Exponential Histogramメトリクスは破棄されます。

Summaries

ステータス: Stable

OpenTelemetry Summaryは、以下のようにPrometheus Summaryへ変換されなければなりません（MUST）。

属性はMetric Attributesの節で説明されているように変換されます。
カウントはSummaryのカウントへ変換されます。
サムはSummaryのサムへ変換されます。
QuantileはSummaryのQuantileへ変換されます。quantileラベルの値は、最低から最高までの順に並んだ、すべて非負である各Quantile（0.0から1.0の間）の文字列化された浮動小数点数値でなければなりません（MUST）。各Quantileの値は、そのQuantile点の計算済みの値です。
Prometheus Remote Writeのようなプッシュ型のプロトコルを使う場合、time_unix_nanoはSummaryのタイムスタンプへ変換されます。Prometheusがスクレイプのタイムスタンプを割り当てる、Prometheusテキスト表現形式のようなプル型のプロトコルでは、明示的なタイムスタンプを使うべきではありません（SHOULD NOT）。
start_time_unix_nanoは、サポートされている場合、Summaryの開始タイムスタンプへ変換されます。

OpenTelemetry Summaryにあるエグゼンプラーは破棄すべきです（SHOULD）。

Metric Attributes

ステータス: Stable

OpenTelemetryのメトリクス属性は、Prometheusのラベルへ変換されなければなりません（MUST）。文字列型の属性値はそのままメトリクス属性へ変換され、文字列型でない属性値は、属性の仕様に従って文字列型の属性へ変換されなければなりません（MUST）。Prometheusの命名規則は、メトリクス名が以下の正規表現に一致することを推奨しています。[a-zA-Z_]([a-zA-Z0-9_])*。推奨されない文字は_文字に置き換えるべきです（SHOULD）。連続する複数の_文字は、単一の_文字に置き換えるべきです（SHOULD）。この変換や、本仕様書によって追加される他のラベル（例えばotel_scope_name）により、異なるOpenTelemetryのキーが同じPrometheusのキーへマッピングされることがあります。そのような場合、値は;で区切り、元のキーの字句順で連結されなければなりません（MUST）。

Exemplar Conversion

ステータス: Stable

上記のメトリクス型固有の節に従ってエグゼンプラーが変換される場合、使われているPrometheusの（プッシュまたはプル）プロトコルがサポートしていれば、OpenTelemetryエグゼンプラーは以下のようにPrometheusエグゼンプラーへ変換されなければなりません（MUST）。

OpenTelemetryエグゼンプラーのTrace IDとSpan IDが存在する場合、それぞれtrace_idとspan_idキーを使ってエグゼンプラーラベルとして追加されなければなりません（MUST）。キーが競合する場合、これらのラベルはfiltered_attributes由来のラベルより優先されなければなりません（MUST）。
タイムスタンプは、Prometheusエグゼンプラーのタイムスタンプとして追加されなければなりません（MUST）。
filtered_attributesは、Prometheusプロトコルのエグゼンプラーの上限を超えない限り、Prometheusエグゼンプラーのラベルとして追加されなければなりません（MUST）。例えば、OpenMetrics 1.0は128文字の上限を課しています。

Resource Attributes

ステータス: Development

Prometheusエクスポーターでは、OpenTelemetryのResourceが空でない場合、それはtarget Infoメトリクスへ変換すべきです（SHOULD）。Resource属性は、エクスポーターの設定によって必要であれば、エクスポートされるメトリクスファミリーのラベルへコピーしてもよく（MAY）、そうでなければ破棄しなければなりません（MUST）。target Infoメトリクスは、そのラベルにResource属性を含まなければならず（MUST）、他のラベルを含んではならない（MUST NOT）、Info型のメトリクスでなければなりません（MUST）。

Collectorが提供するPrometheusエクスポーターでは、複数の対象からのメトリクスが一緒に送出されることがあるため、対象を互いに区別する必要があります。しかし、Prometheusの表現形式とremote-write形式はResourceという概念を含んでおらず、スクレイピングされた対象を区別するためにメトリクスラベルを使うことを想定しています。慣習的に、jobとinstanceラベルは対象を区別するために使われ、Prometheus Pullエクスポーター（“federated” Prometheusエンドポイント）で公開されるメトリクス、またPrometheus remote-write経由でプッシュされるメトリクスに存在することが期待されます。OpenTelemetryのセマンティック規約では、service.name、service.namespace、service.instance.idの三つ組が一意であることが要求されており、そのためjobとinstanceを構成するために使う良い候補になります。CollectorのPrometheusエクスポーターでは、service.nameとservice.namespace属性は、jobメトリクスラベルを構成するために<service.namespace>/<service.name>として（namespaceが空の場合は<service.name>として）結合されなければなりません（MUST）。service.instance.id属性は、存在する場合はinstanceラベルへ変換されなければならず（MUST）、そうでない場合はinstanceを空の値で追加すべきです（SHOULD）。他のResource属性はtarget Infoメトリクスへ変換すべきであり（SHOULD）、そうでなければ破棄しなければなりません（MUST）。targetメトリクスは、そのラベルにResource属性を含まなければならず（MUST）、jobとinstance以外の他のラベルを含んではならない（MUST NOT）、Info型のメトリクスです。一意なjobとinstanceの組み合わせごとに、エクスポートされるtarget Infoメトリクスは最大1つでなければなりません（MUST）。

言語のPrometheusクライアントライブラリがInfo型のメトリクスファミリーをまだサポートしていない場合、代わりに値1の定数を持つ、target_infoという名前のgauge型のメトリクスファミリーを使わなければなりません（MUST）。

OTLPのResource属性をPrometheusのラベルへ変換するには、文字列型の属性値はそのままラベルへ変換され、文字列型でない属性値は属性の仕様に従って文字列型の属性へ変換されなければなりません（MUST）。