OTLP ingestion

Prometheus accepts metrics over the OpenTelemetry Protocol (OTLP) at /api/v1/otlp/v1/metrics. The receiver translates OTLP gauges, sums, histograms, and summaries into Prometheus's internal append model.

Enabling

CLI flag: --web.enable-otlp-receiver. The handler is storage/remote/write_otlp_handler.go.

Translation

storage/remote/otlptranslator/prometheusremotewrite/ is a thin in-tree wrapper around the upstream github.com/prometheus/otlptranslator library. The translator owns:

• Metric naming. OTLP names are translated under one of two strategies:
  • NoUTF8EscapingWithSuffixes — preserve UTF-8 names, append unit/type suffixes (_seconds, _total, _ratio).
  • UnderscoreEscapingWithSuffixes — escape non-[a-zA-Z0-9_:] chars to _. Configure via --storage.otlp.translation-strategy=....
• Resource and scope attributes. Promotable into series labels (promote_resource_attributes, promote_scope_metadata).
• Histogram conversion. OTLP explicit-bucket histograms become NHCB (custom-bucket native histograms). OTLP exponential histograms map directly to native histograms.
• Summary expansion. Summaries become <name> + <name>_count + <name>_sum + per-quantile series.
• Delta -> cumulative. Optional, behind --enable-feature=otlp-deltatocumulative.
• Native delta ingestion. Preserve delta temporality (--enable-feature=otlp-native-delta-ingestion).

Configuration

otlp:
  translation_strategy: NoUTF8EscapingWithSuffixes
  promote_resource_attributes:
    - service.name
    - service.namespace
    - service.instance.id
  promote_scope_metadata: false

Authentication and TLS

Inherit from the same --web.config.file that gates the rest of the API. There are no OTLP-specific auth options.

Recent fixes

• 3.10 #17917 — filter __name__ from OTLP attributes to avoid duplicate labels.
• 3.10 #17954 — fix silent data loss for sum metrics.
• 3.11 #18056 — fix exemplars getting mixed between incorrect parts of a histogram.
• 3.11 #18084 — return HTTP 400 on stale samples in PRW v2 histogram write paths to prevent infinite client retries.

Self-metrics

The OTLP path shares its metrics with the remote-write receiver: prometheus_remote_storage_received_*. The translator emits its own observability via the upstream library.

Entry points for modification

• New translation rule: in many cases the upstream library is the right place. In-tree behaviour (resource promotion, name strategy) lives in storage/remote/write_otlp_handler.go::OTLPOptions.
• Histogram delta -> cumulative: the conversion is in the upstream otlptranslator. In-tree config is in OTLPOptions.ConvertDelta.

See Remote write and Remote for the receiver context.