remove MetricProducer, and OpenCensus bridges wrap existing interface…

…s instead of using MetricProducer
open-telemetry · Aug 1, 2023 · c4e2131 · c4e2131
1 parent 065b250
commit c4e2131
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 87 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,8 @@ release.
   ([#3546](https://github.com/open-telemetry/opentelemetry-specification/pull/3546))
 - Revise the exemplar default reservoirs.
   ([#3627](https://github.com/open-telemetry/opentelemetry-specification/pull/3627))
+- Remove experimental MetricProducer from the metric SDK specification.
+  ([#3635](https://github.com/open-telemetry/opentelemetry-specification/pull/3635))
 
 ### Logs
 
@@ -26,6 +28,8 @@ release.
 
 - Prometheus exporters SHOULD provide configuration to disable the addition of `_total` suffixes.
   ([#3590](https://github.com/open-telemetry/opentelemetry-specification/pull/3590))
+- OpenCensus bridges should wrap MetricExporter and MetricReader instead of implementing MetricProducer.
+  ([#3635](https://github.com/open-telemetry/opentelemetry-specification/pull/3635))
 
 ### SDK Configuration
 

diff --git a/specification/compatibility/opencensus.md b/specification/compatibility/opencensus.md
@@ -211,11 +211,41 @@ default, but SHOULD provide configuration to allow users to enable it.
 
 ## Metrics / Stats
 
-OpenTelemetry will provide an OpenCensus-Metrics-Shim component which
-implements the OpenTelemetry [MetricProducer](../metrics/sdk.md#metricproducer)
-interface. When Produce() is invoked, the shim collects metrics from the
-OpenCensus global state, converts the metrics to an OpenTelemetry metrics
-batch, and returns.
+OpenTelemetry will provide two OpenCensus-Metrics-Shim components. One which
+implements the OpenTelemetry [MetricExporter](../metrics/sdk.md#metricexporter)
+interface, and is used to and another which implements the
+[MetricReader](../metrics/sdk.md#metricreader) interface.
+
+### MetricExporter bridge
+
+To construct the `MetricExporter` bridge, the caller MUST provide a
+`MetricExporter`, and authors MAY include other required or optional
+parameters.
+
+With the exception of [Export(batch)](../metrics/sdk.md#exportbatch), the
+bridge MUST delegate all calls directly to this MetricExporter. When
+[Export(batch)](../metrics/sdk.md#exportbatch) is invoked, the bridge collects
+metrics from the global OpenCensus store, translates and integrates them to the
+provided batch of OpenTelemetry [Metric points](../metrics/data-model.md#metric-points),
+and invokes the "wrapped" exporter's [Export(batch)](../metrics/sdk.md#exportbatch)
+function with the merged batch. All metrics from OpenCensus MUST be associated
+a single instrumentation scope.
+
+### MetricReader bridge
+
+Constructing the `MetricReader` bridge does not have any required parameters,
+although SDK authors MAY require callers to provide a `MetricReader` or other
+required or optional parameters. If the bridge does not require a
+`MetricReader`, it should construct one.
+
+With the exception of [Collect()](../metrics/sdk.md#collect), the bridge
+SHOULD delegate all calls to its underlying `MetricReader`. When
+[Collect()](../metrics/sdk.md#collect) is invoked, the bridge invokes
+[Collect()](../metrics/sdk.md#collect) on its underlying MetricReader.
+It then collects metrics from the global OpenCensus store, and translate and integrate
+them into the batch of OpenTelmeetry [Metric points](../metrics/data-model.md#metric-points)
+from [Collect()](../metrics/sdk.md#collect). All metrics from OpenCensus
+MUST be associated a single instrumentation scope.
 
 ### Requirements
 

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -59,7 +59,6 @@ linkTitle: SDK
     + [AlignedHistogramBucketExemplarReservoir](#alignedhistogrambucketexemplarreservoir)
 - [MetricReader](#metricreader)
   * [MetricReader operations](#metricreader-operations)
-    + [RegisterProducer(metricProducer)](#registerproducermetricproducer)
     + [Collect](#collect)
     + [Shutdown](#shutdown-1)
   * [Periodic exporting MetricReader](#periodic-exporting-metricreader)
@@ -70,9 +69,6 @@ linkTitle: SDK
       - [ForceFlush()](#forceflush)
       - [Shutdown()](#shutdown)
   * [Pull Metric Exporter](#pull-metric-exporter)
-- [MetricProducer](#metricproducer)
-  * [Interface Definition](#interface-definition-1)
-    + [Produce() batch](#produce-batch)
 - [Defaults and configuration](#defaults-and-configuration)
 - [Numerical limits handling](#numerical-limits-handling)
 - [Compatibility requirements](#compatibility-requirements)
@@ -1034,9 +1030,7 @@ measurements using the equivalent of the following naive algorithm:
 common configurable aspects of the OpenTelemetry Metrics SDK and
 determines the following capabilities:
 
-* Registering [MetricProducer](#metricproducer)(s)
-* Collecting metrics from the SDK and any registered
-  [MetricProducers](#metricproducer) on demand.
+* Collecting metrics from the SDK on demand.
 * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from
   the SDK.
 
@@ -1064,11 +1058,6 @@ with Delta temporality, this means converting [Cumulative to
 Delta](supplementary-guidelines.md#asynchronous-example-delta-temporality) aggregation
 temporality.
 
-The `MetricReader` is not required to ensure data points from a non-SDK
-[MetricProducer](#metricproducer) are output in the configured aggregation
-temporality, as these data points are not collected using OpenTelemetry
-instruments.
-
 The SDK MUST support multiple `MetricReader` instances to be registered on the
 same `MeterProvider`, and the [MetricReader.Collect](#collect) invocation on one
 `MetricReader` instance SHOULD NOT introduce side-effects to other `MetricReader`
@@ -1103,25 +1092,9 @@ functions.
 
 ### MetricReader operations
 
-#### RegisterProducer(metricProducer)
-
-**Status**: [Experimental](../document-status.md)
-
-RegisterProducer causes the MetricReader to use the provided
-[MetricProducer](#metricproducer) as a source of aggregated metric data in
-subsequent invocations of Collect. RegisterProducer is expected to be called
-during initialization, but MAY be invoked later. Multiple registrations
-of the same MetricProducer MAY result in duplicate metric data being collected.
-
-If the [MeterProvider](#meterprovider) is an instance of
-[MetricProducer](#metricproducer), this MAY be used to register the
-MeterProvider, but MUST NOT allow multiple [MeterProviders](#meterprovider)
-to be registered with the same MetricReader.
-
 #### Collect
 
-Collects the metrics from the SDK and any registered
-[MetricProducers](#metricproducer). If there are
+Collects the metrics from the SDK. If there are
 [asynchronous SDK Instruments](./api.md#asynchronous-instrument-api) involved,
 their callback functions will be triggered.
 
@@ -1393,59 +1366,6 @@ modeled to interact with other components in the SDK:
                                  +-----------------------------+
   ```
 
-## MetricProducer
-
-**Status**: [Experimental](../document-status.md)
-
-`MetricProducer` defines the interface which bridges to third-party metric
-sources MUST implement so they can be plugged into an OpenTelemetry
-[MetricReader](#metricreader) as a source of aggregated metric data. The SDK's
-in-memory state MAY implement the `MetricProducer` interface for convenience.
-
-`MetricProducer` implementations SHOULD accept configuration for the
-`AggregationTemporality` of produced metrics. SDK authors MAY provide utility
-libraries to facilitate conversion between delta and cumulative temporalities.
-
-If the batch of [Metric points](./data-model.md#metric-points) returned by
-`Produce()` includes a [Resource](../resource/sdk.md), the `MetricProducer` MUST
-accept configuration for the [Resource](../resource/sdk.md).
-
-```text
-+-----------------+            +--------------+
-|                 | Metrics... |              |
-| In-memory state +------------> MetricReader |
-|                 |            |              |
-+-----------------+            |              |
-                               |              |
-+-----------------+            |              |
-|                 | Metrics... |              |
-| MetricProducer  +------------>              |
-|                 |            |              |
-+-----------------+            +--------------+
-```
-
-### Interface Definition
-
-A `MetricProducer` MUST support the following functions:
-
-#### Produce() batch
-
-`Produce` provides metrics from the MetricProducer to the caller. `Produce`
-MUST return a batch of [Metric points](./data-model.md#metric-points).
-`Produce` does not have any required parameters, however, [OpenTelemetry
-SDK](../overview.md#sdk) authors MAY choose to add required or optional
-parameters (e.g. timeout).
-
-`Produce` SHOULD provide a way to let the caller know whether it succeeded,
-failed or timed out. When the `Produce` operation fails, the `MetricProducer`
-MAY return successfully collected results and a failed reasons list to the
-caller.
-
-If a batch of [Metric points](./data-model.md#metric-points) can include
-[`InstrumentationScope`](../glossary.md#instrumentation-scope) information,
-`Produce` SHOULD include a single InstrumentationScope which identifies the
-`MetricProducer`.
-
 ## Defaults and configuration
 
 The SDK MUST provide configuration according to the [SDK environment