oss_18_prometheus_openmetrics_compat

[ocelotl]

Closes #29

Prometheus/OpenMetrics compatibility bundle (Linear OSS-18, findings M5-M9): merge colliding sanitized attribute keys (;-joined, sorted); emit exemplars on counters/histograms; add without_counter_suffixes; drop same-name conflicting-type families with a warning; protect reserved otel_scope_* labels.

Validation: scope contained to the prometheus exporter package + changelog; exporter suite 38 passed (31 existing + 7 new).

Linear issue: https://linear.app/dash0/issue/OSS-18/m5-m9-prometheusopenmetrics-compatibility-bundle

[ocelotl]

🔒 Internal (dash0) — not for upstream.

• Linear: https://linear.app/dash0/issue/OSS-18/m5-m9-prometheusopenmetrics-compatibility-bundle (findings M5-M9)
• Closes: oss_18_prometheus_openmetrics_compat #29 · Branch: oss_18_prometheus_openmetrics_compat · Commit: 388bd1b3a
• Validation: prometheus exporter suite 38 passed; scope package + changelog.

[ocelotl]

📣 Public-facing draft — to be used for the upstream PR in open-telemetry/opentelemetry-python. No internal references; copy verbatim.

Title: Improve Prometheus/OpenMetrics compatibility in the Prometheus exporter

What

Brings the Prometheus exporter closer to the Prometheus and OpenMetrics compatibility specification, matching Go/Java. All changes within exporter/opentelemetry-exporter-prometheus.

• Merge colliding sanitized attributes: values whose keys sanitize to the same Prometheus label are merged (;-joined, sorted by original key) instead of overwriting.
• Emit exemplars: OTel exemplars on counters and histograms map to prometheus_client exemplars exposing hex trace_id/span_id. Prometheus supports one exemplar per sample, so the first per data point is used; for histograms it attaches to the +Inf bucket.
• without_counter_suffixes option: new PrometheusMetricReader flag to suppress the _total suffix.
• Conflicting-type handling: same-name families mapping to conflicting Prometheus types are detected within a collection; the conflicting family is dropped and a warning logged, preventing invalid exposition.
• Reserved scope labels protected: data-point attributes sanitizing to a reserved otel_scope_* label are skipped.

Why

The exporter previously dropped exemplars, lost attributes on sanitization collisions, could emit invalid exposition when two metrics shared a name with different types, allowed reserved scope labels to be overwritten, and offered no way to disable the _total suffix — all addressed by the compatibility spec and implemented in Go/Java.

Spec

specification/compatibility/prometheus_and_openmetrics.md

Tests

Unit tests for every behavior (merged colliding keys; exemplars on counters and histograms; without_counter_suffixes drops _total and default suffix present; conflicting-type family dropped with warning; reserved-scope-label collision skipped). Full exporter suite: 38 passed (31 existing + 7 new).