diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e39b8d12d4..8e0b07abd8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,6 +69,8 @@ New: ([#1141](https://github.com/open-telemetry/opentelemetry-specification/pull/1141)) - Add OTEL_TRACE_SAMPLER env variable definition ([#1136](https://github.com/open-telemetry/opentelemetry-specification/pull/1136/)) +- Add guidelines for OpenMetrics interoperability + ([#1154](https://github.com/open-telemetry/opentelemetry-specification/pull/1154)) - Add OTEL_TRACE_SAMPLER_ARG env variable definition ([#1202](https://github.com/open-telemetry/opentelemetry-specification/pull/1202)) diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md index e188029d0d7..29fc0409c2a 100644 --- a/specification/metrics/semantic_conventions/README.md +++ b/specification/metrics/semantic_conventions/README.md @@ -71,6 +71,10 @@ units in the metric name. Units may be included when it provides additional meaning to the metric name. Metrics MUST, above all, be understandable and usable. +When building components that interoperate between OpenTelemetry and a system +using the OpenMetrics exposition format, use the +[OpenMetrics Guidelines](./openmetrics-guidelines.md). + ### Pluralization Metric names SHOULD NOT be pluralized, unless the value being recorded diff --git a/specification/metrics/semantic_conventions/openmetrics-guidelines.md b/specification/metrics/semantic_conventions/openmetrics-guidelines.md new file mode 100644 index 00000000000..b098d522d8f --- /dev/null +++ b/specification/metrics/semantic_conventions/openmetrics-guidelines.md @@ -0,0 +1,51 @@ +# Guidance for Interoperating with OpenMetrics + +**Note:** This document is work in progress and will be updated as the +OpenMetrics specification further develops. + +## Overview + +OpenTelemetry will need to interoperate with systems using the OpenMetrics or +Prometheus exposition format in two ways: + +* OpenTelemetry may need to accept and propagate metrics expressed in + the OpenMetrics exposition format, and export them to downstream systems + (including OpenTelemetry Collector(s), zPages, vendor backends, etc...) +* OpenTelemetry may need to expose OpenTelemetry generated metrics in the + OpenMetrics exposition format. + +### OpenMetrics to OpenTelemetry + +The OpenTelemetry collector implements a Prometheus receiver, which reads +metrics in the OpenMetrics exposition format. For more information, refer to the +[Prometheus Receiver Design Document](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/prometheusreceiver/DESIGN.md). + +### OpenTelemetry to OpenMetrics + +#### Name and Label Keys + +Exposting OpenTelemetry metrics in the OpenMetrics format is primarily +problematic for metric and label naming; the OpenMetrics exposition format +expressly forbits some characters that are allowed in OpenTelemetry. + +When converting OpenTelemetry metric events to the OpenMetrics exposition +format, the name field and all label keys MUST be sanitized by replacing +every character that is not a letter or a digit with an underscore. + +Example pseudocode: + +```ruby +def sanitize(name) + return name.sub(/\W/, '_') +``` + +See also [Metric names and labels](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels) +in the Prometheus data model documentation. + +OpenMetrics does not allow metric names to begin with a digit. OpenTelemetry's +[instrument naming requirements](../api.md#instrument-naming-requirements) also +require that the first character of a metric instrument is non-numeric. + +If a metric event is generated in OpenTelemetry that does not conform to this +specification, the name of the resulting OpenMetrics metric MAY be prepended +with an underscore.