diff --git a/CHANGELOG.md b/CHANGELOG.md index d988257b244..517ac7c863d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,10 @@ release. ### Compatibility +- Stabilize sections of Prometheus and OpenMetrics Compatibility. + - Stabilize OpenTelemetry Gauge and Sum to Prometheus transformations. + ([#5034](https://github.com/open-telemetry/opentelemetry-specification/pull/5034)) + ### SDK Configuration ### Supplementary Guidelines diff --git a/specification/compatibility/prometheus_and_openmetrics.md b/specification/compatibility/prometheus_and_openmetrics.md index 4ef57debd27..48bddf307a3 100644 --- a/specification/compatibility/prometheus_and_openmetrics.md +++ b/specification/compatibility/prometheus_and_openmetrics.md @@ -466,34 +466,32 @@ to avoid conflicts with the already existing `otel_scope_name`, `otel_scope_vers ### Gauges -**Status**: [Development](../document-status.md) +**Status**: [Stable](../document-status.md) -An [OpenTelemetry Gauge](../metrics/data-model.md#gauge) MUST be converted to -a Prometheus Unknown-typed metric if the `prometheus.type` key of -[metric.metadata][metricMetadata] is `unknown`. Otherwise, it MUST be converted -to a Prometheus Gauge. +An [OpenTelemetry Gauge](../metrics/data-model#gauge) MUST be converted following +a hint present in [metric.metadata][metricMetadata]: +- If the `prometheus.type` key is absent, or its value is equal to `gauge`, the datapoint MUST be transformed to a Prometheus Gauge. +- If the `prometheus.type` key has value equal to `unkown`, the datapoint MUST be transformed to a Prometheus Unknown. +- If the `prometheus.type` key has value equal to `info`, the datapoint SHOULD be transformed to a Prometheus Info. +- If the `prometheus.type` key has value equal to `stateset`, the datapoint SHOULD be transformed to a Prometheus Stateset. Exemplars on OpenTelemetry Gauges SHOULD be dropped. ### Sums -**Status**: [Development](../document-status.md) +**Status**: [Stable](../document-status.md) -[OpenTelemetry Sums](../metrics/data-model.md#sums) follows this logic: +An [OpenTelemetry Sum](../metrics/data-model.md#sums) MUST be converted following the rules below: - If the aggregation temporality is cumulative and the sum is monotonic, it MUST be converted to a Prometheus Counter. -- If the aggregation temporality is cumulative and the sum is non-monotonic and the `prometheus.type` key of -[metric.metadata][metricMetadata] is `info`, it MUST be converted to an OpenMetrics Info metric. -- If the aggregation temporality is cumulative and the sum is non-monotonic and the `prometheus.type` key of -[metric.metadata][metricMetadata] is `stateset`, it MUST be converted to an OpenMetrics StateSet metric. -- If the aggregation temporality is cumulative and the sum is non-monotonic, it MUST be converted to a Prometheus Gauge. -- If the aggregation temporality is delta and the sum is monotonic, it SHOULD be converted to a cumulative temporality and become a Prometheus Counter. The following behaviors are expected: +- If the aggregation temporality is cumulative and the sum is non-monotonic, it should follow the same rules as described for [OpenTelemetry Gauge](#gauges-1) +- If the aggregation temporality is delta and the sum is monotonic, it MAY be converted to a cumulative temporality and become a Prometheus Counter. The following behaviors are expected: - The new data point type must be the same as the accumulated data point type. - The new data point's start time must match the time of the accumulated data point. If not, see [detecting alignment issues](../metrics/data-model.md#sums-detecting-alignment-issues). -- Otherwise, it MUST be dropped. -If the metric name for monotonic Sum metric points does not end in a suffix of `_total` a suffix of `_total` SHOULD be added by default, otherwise the name MUST remain unchanged. Exporters SHOULD provide a configuration option to disable the addition of `_total` suffixes. -Monotonic Sum metric points with `StartTimeUnixNano` should export the `{name}_created` metric as well. +If the metric name for monotonic Sum metric points does not end in a suffix of `_total` a suffix of `_total` SHOULD be added by default, otherwise the name MUST remain unchanged. + +Monotonic Sum metric points with `StartTimeUnixNano` SHOULD transform `StartTimeUnixNano` into Prometheus `StartTime`, following the appropriate format used by each Prometheus protocol. If Sum is converted to a Prometheus Counter, then `Exemplars` MUST be converted as described in the [Exemplar Conversion](#exemplar-conversion) section.