OTLP receiver

POST /api/v1/otlp/v1/metrics
Content-Type: application/x-protobuf  | application/json

The receiver accepts OpenTelemetry Protocol metric exports and translates them on the fly. Enabled with --web.enable-otlp-receiver.

Translation rules

The translator (storage/remote/otlptranslator/prometheusremotewrite/) wraps the upstream github.com/prometheus/otlptranslator library.

• Names: mapped under --storage.otlp.translation-strategy=NoUTF8EscapingWithSuffixes|UnderscoreEscapingWithSuffixes. Suffixes (_seconds, _total, _ratio, _bytes) are appended to indicate units/types.
• Resource attributes: promoted to series labels per otlp.promote_resource_attributes in prometheus.yml.
• Scope metadata: promoted per otlp.promote_scope_metadata (3.x).
• __name__ filtering: the receiver filters incoming __name__ attributes to prevent duplicate labels (3.10 fix #17917).

Histograms

• Explicit-bucket OTLP histograms become NHCB (custom-bucket native histograms).
• Exponential OTLP histograms map directly to native histograms.
• Summaries expand to <name> + <name>_count + <name>_sum + per-quantile series.

Delta vs cumulative

Two opt-in modes via --enable-feature=:

• otlp-deltatocumulative — convert delta-temporality to cumulative inside the receiver. The conversion is keyed by series identity, so out-of-order delta points within a window are folded.
• otlp-native-delta-ingestion — preserve delta semantics. Useful when the storage backend supports delta natively (e.g. some long-term stores).

Without either flag, delta metrics are rejected.

Configuration

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

Per-environment, the request comes in over the same web listener; TLS / basic auth follow the standard --web.config.file.

Self-metrics

The OTLP path shares its metrics with the remote-write receiver: prometheus_remote_storage_received_*. Translator-level counters live in the upstream library and are exposed via /metrics on the same Prometheus.

Errors

Same status codes as remote write. The 3.11 fix #18084 ensures stale samples in PRW v2 histogram write paths return 400 instead of 500 to prevent retry loops.

See OTLP feature page and Remote subsystem.