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).

[github-actions]

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.