diff --git a/CHANGELOG.md b/CHANGELOG.md index bfe96fd1f8a..48d8d79453e 100644 --- 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. + ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) ### 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. + ([#TODO](https://github.com/open-telemetry/opentelemetry-specification/pull/TODO)) ### SDK Configuration diff --git a/specification/compatibility/opencensus.md b/specification/compatibility/opencensus.md index f1e55bac3ce..950d941d812 100644 --- 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/data-model.md#collect), the bridge +SHOULD delegate all calls to its underlying `MetricReader`. When +[Collect()](../metrics/data-model.md#collect) is invoked, the bridge invokes +[Collect()](../metrics/data-model.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](./data-model.md#metric-points) +from [Collect()](../metrics/data-model.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 index 98dfa5deff0..f800d4cd0ef 100644 --- 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