From 3f358caa6bfdab658a95c1e5a71bb86adcc62cba Mon Sep 17 00:00:00 2001
From: Justin Foote <justinandrewfoote@gmail.com>
Date: Tue, 17 Nov 2020 09:15:45 -0800
Subject: [PATCH] Add OpenMetrics guidance (#1154)

* Add OpenMetrics interop guidelines

* Add Prometheus Receiver guidelines; reference collector design

* Add OpenMetrics guidelines to changelog

* Add work in progress note to OpenMetrics guidance

Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>
---
 .../metrics/semantic_conventions/README.md    |  4 ++
 .../openmetrics-guidelines.md                 | 51 +++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 specification/metrics/semantic_conventions/openmetrics-guidelines.md

diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md
index e188029d0..29fc0409c 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 000000000..b098d522d
--- /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.