Prometheus SDK exporter specification cleanups (#3872)

Fixes
#3702
Fixes
#2468

Addresses
#3737 (comment)

## Changes

* Add option to disable `target` info metric.
* Move SDK-specific language from the compatibility spec to the
prometheus exporter spec.
* Disallow using OpenMetrics proto format, or Prometheus remote write
formats in SDK exporters
* Recommend using Prometheus client libraries
* Clarify that only features supported by the text format are required
to be implemented by Prometheus exporters
* Require prometheus SDK exporters to follow the compatibility
specification.

@open-telemetry/wg-prometheus

CHANGELOG.md

@@ -15,6 +15,8 @@ release.
 
 - Clarify that exemplar reservoir default may change in a minor version.
   ([#3943](https://github.com/open-telemetry/opentelemetry-specification/pull/3943))
+- Add option to disable target info metric to Prometheus exporters.
+  ([#3872](https://github.com/open-telemetry/opentelemetry-specification/pull/3872))
 
 ### Logs
 
@@ -35,6 +37,8 @@ release.
   ([#3871](https://github.com/open-telemetry/opentelemetry-specification/pull/3871))
 - Prometheus compatibility: Clarify that the service triplet is required to be unique by semantic conventions.
   ([#3945](https://github.com/open-telemetry/opentelemetry-specification/pull/3945))
+- Update and reorganize the prometheus sdk exporter specification.
+  ([#3872](https://github.com/open-telemetry/opentelemetry-specification/pull/3872))
 
 ### SDK Configuration
 

specification/compatibility/prometheus_and_openmetrics.md

@@ -241,7 +241,7 @@ in keys).
 
 ### Metric Metadata
 
-Prometheus SDK exporters MUST NOT allow duplicate UNIT, HELP, or TYPE
+Prometheus Pull exporters MUST NOT allow duplicate UNIT, HELP, or TYPE
 comments for the same metric name to be returned in a single scrape of the
 Prometheus endpoint. Exporters MUST drop entire metrics to prevent conflicting
 TYPE comments, but SHOULD NOT drop metric points as a result of conflicting
@@ -408,16 +408,16 @@ Prometheus exemplar unless they would exceed the
 
 ### Resource Attributes
 
-In SDK Prometheus (pull) exporters, resource attributes SHOULD be converted to
-a single [`target` info metric](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems)
+In Prometheus exporters, an OpenTelemetry Resource SHOULD be converted to
+a [`target` info metric](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems)
 if the resource is not [empty](../resource/sdk.md#the-empty-resource).
-The resource attributes MAY be copied to labels of exported metric families
+The Resource attributes MAY be copied to labels of exported metric families
 if required by the exporter configuration, or MUST be dropped. The `target`
-info metric MUST be an info-typed metric whose labels MUST include the resource
-attributes, and MUST NOT include any other labels. There MUST be at most one
-`target` info metric exposed on an SDK Prometheus endpoint.
+info metric MUST be an info-typed
+metric whose labels MUST include the resource attributes, and MUST NOT include
+any other labels.
 
-In the Collector's Prometheus pull and push (remote-write) exporters, it is
+In the Collector's Prometheus exporters, it is
 possible for metrics from multiple targets to be sent together, so targets must
 be disambiguated from one another. However, the Prometheus exposition format
 and [remote-write](https://github.com/Prometheus/Prometheus/blob/main/prompb/remote.proto)

specification/metrics/sdk_exporters/prometheus.md

@@ -6,37 +6,54 @@ linkTitle: Prometheus
 
 **Status**: [Experimental](../../document-status.md)
 
-A Prometheus Exporter is a [Pull Metric Exporter](../sdk.md#pull-metric-exporter)
-which reports metrics by responding to the [Prometheus](https://prometheus.io/)
-scraper requests.
+A Prometheus Exporter MUST be a [Pull Metric Exporter](../sdk.md#pull-metric-exporter)
+which responds to HTTP requests with Prometheus metrics in the appropriate format.
 
-A Prometheus Exporter MUST support [Pull mode](../sdk.md#pull-metric-exporter).
+OpenTelemetry metrics MUST be converted to Prometheus metrics according to the
+[Prometheus Compatibility specification](../../compatibility/prometheus_and_openmetrics.md).
 
-A Prometheus Exporter MUST NOT support [Push
-mode](../sdk.md#push-metric-exporter).
+A Prometheus Exporter SHOULD use
+[Prometheus client libraries](https://prometheus.io/docs/instrumenting/clientlibs/)
+for serving Prometheus metrics. This allows the prometheus client to negotiate
+the [format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md)
+of the response using the `Content-Type` header. If a prometheus client library
+is used, the OpenTelemetry Prometheus Exporter SHOULD be modeled as a
+[custom Collector](https://prometheus.io/docs/instrumenting/writing_clientlibs/#overall-structure)
+so it can be used in conjunction with existing Prometheus instrumentation.
 
-A Prometheus Exporter MUST only support [Cumulative
-Temporality](../data-model.md#temporality).
+Regardless of whether a Prometheus client library is used, the Prometheus
+Exporter MUST support version `0.0.4` of the
+[Text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format).
+A Prometheus Exporter MAY support Exemplars and Exponential Histograms,
+which are [not currently supported by the Prometheus text format](../../compatibility/prometheus_and_openmetrics.md#differences-between-prometheus-formats),
+by supporting other Protocols, but is not required to implement them.
 
-A Prometheus Exporter MUST support version `0.0.4` of the [Text-based
-format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format).
+A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT use
+[Prometheus Remote Write format](https://github.com/prometheus/prometheus/blob/main/prompb/remote.proto)
+or [OpenMetrics protobuf format](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#protobuf-format).
 
-A Prometheus Exporter MAY support [OpenMetrics Text
-Format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#openmetrics-text-format),
-including the
-[Exemplars](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars).
+A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add
+[explicit timestamps on Metric points](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#metric).
+
+There MUST be at most one `target` info metric exposed by an SDK
+Prometheus exporter.
+
+## Configuration
 
 A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes.
 By default, it MUST NOT add any resource attributes as metric attributes.
 The configuration SHOULD allow the user to select which resource attributes to copy (e.g.
 include / exclude or regular expression based). Copied Resource attributes MUST NOT be
-excluded from target_info.
+excluded from the `target` info metric.
 
 A Prometheus Exporter MAY support a configuration option to produce metrics without a [unit suffix](../../compatibility/prometheus_and_openmetrics.md#metric-metadata)
 or UNIT metadata. The option MAY be named `without_units`, and MUST be `false` by default.
 
 A Prometheus Exporter MAY support a configuration option to produce metrics without a [type suffix](../../compatibility/prometheus_and_openmetrics.md#metric-metadata).
 The option MAY be named `without_type_suffix`, and MUST be `false` by default.
 
-A Prometheus Exporter MAY support a configuration option to produce metrics without a [scope info](../../compatibility/prometheus_and_openmetrics.md#instrumentation-scope)
-metric. The option MAY be named `without_scope_info`, and MUST be `false` by default.
+A Prometheus Exporter MAY support a configuration option to produce metrics without a [scope info](../../compatibility/prometheus_and_openmetrics.md#instrumentation-scope-1)
+metric, or scope labels. The option MAY be named `without_scope_info`, and MUST be `false` by default.
+
+A Prometheus Exporter MAY support a configuration option to produce metrics without a [target info](../../compatibility/prometheus_and_openmetrics.md#resource-attributes-1)
+metric. The option MAY be named `without_target_info`, and MUST be `false` by default.