Add OpenMetrics guidance

CHANGELOG.md

@@ -61,6 +61,8 @@ New:
  ([#937](https:/open-telemetry/opentelemetry-specification/pull/937))
 - Add OTEL_TRACE_SAMPLER env variable definition
  ([#1136](https:/open-telemetry/opentelemetry-specification/pull/1136/))
+- Add guidelines for OpenMetrics interoperability
+ ([#1154](https:/open-telemetry/opentelemetry-specification/pull/1154))
 
 Updates:
 

specification/metrics/semantic_conventions/README.md

@@ -56,6 +56,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).
+
 ## General Metric Semantic Conventions
 
 The following semantic conventions aim to keep naming consistent. They

specification/metrics/semantic_conventions/openmetrics-guidelines.md

@@ -0,0 +1,48 @@
+# Guidance for Interoperating with OpenMetrics
+
+## 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:/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.