From 2cb7a75f8a30a571db7ca32b2ace9de840a779d9 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 18 Aug 2022 20:06:21 +0000 Subject: [PATCH] MetricProducer is part of a MeterProvider --- specification/metrics/sdk.md | 76 +++++++++++++++--------------------- 1 file changed, 31 insertions(+), 45 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f2959ebba20..ff9efcac767 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -79,10 +79,10 @@ to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Meter`. Configuration (i.e., [MetricExporters](#metricexporter), -[MetricReaders](#metricreader) and [Views](#view)) MUST be managed solely by the -`MeterProvider` and the SDK MUST provide a way to configure all options that are -implemented by the SDK. This MAY be done at the time of MeterProvider creation -if appropriate. +[MetricReaders](#metricreader), [MetricProducers](#metricproducer) and +[Views](#view)) MUST be managed solely by the `MeterProvider` and the SDK MUST +provide a way to configure all options that are implemented by the SDK. This +MAY be done at the time of MeterProvider creation if appropriate. The `MeterProvider` MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `MetricReader`), the updated @@ -755,9 +755,7 @@ measurements using the equivalent of the following naive algorithm: common configurable aspects of the OpenTelemetry Metrics SDK and determines the following capabilities: -* Registering a [MetricProducer](#metricproducer) -* Collecting metrics from the registered [MetricProducer](#metricproducer) on - demand. +* Collecting metrics from the SDK on demand. * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from the SDK. @@ -774,8 +772,8 @@ used with pull-based metrics collection. A common sub-class of `MetricReader`, the periodic exporting `MetricReader` SHOULD be provided to be used typically with push-based metrics collection. -The `MetricReader` MUST ensure that data points from the SDK are output in the -configured aggregation temporality for each instrument kind. For +The `MetricReader` MUST ensure that data points from OTel instruments are +output in the configured aggregation temporality for each instrument kind. For synchronous instruments being output with Cumulative temporality, this means converting [Delta to Cumulative](supplementary-guidelines.md#synchronous-example-cumulative-aggregation-temporality) aggregation temporality. For asynchronous instruments being output @@ -783,7 +781,7 @@ 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 +The `MetricReader` is not required to ensure data points from a [MetricProducer](#metricproducer) are output in the configured aggregation temporality. @@ -797,8 +795,7 @@ to (Tn+1, Tn+2] - **ONLY** for this particular `MetricReader` instance. The SDK MUST NOT allow a `MetricReader` instance to be registered on more than -one `MeterProvider` instance. The SDK MUST NOT allow a `MetricReader` -registered with a non-SDK `MetricProducer` to be registered with `MeterProvider`. +one `MeterProvider` instance. ```text +-----------------+ +--------------+ @@ -822,22 +819,10 @@ functions. ### MetricReader operations -#### Register(MetricProducer) - -Register causes the MetricReader to use the provided -[MetricProducer](#metricproducer) for as a source of aggregated metric data in -subsequent invocations of Collect. It MUST NOT allow more than one -[MetricProducer](#metricproducer) or [MeterProvider](#meterprovider) instance -to be registered with the [MetricReader](#metricreader). - -If the [MeterProvider](#meterprovider) is an instance of a -[MetricProducer](#metricproducer), this MAY be used to register the -MeterProvider. - #### Collect -Collects the metrics from the SDK or the [MetricProducer](#metricproducer). If -there are [asynchronous SDK Instruments](./api.md#asynchronous-instrument-api) +Collects the metrics from the SDK and its [MetricProducers](#metricproducer). +If there are [asynchronous SDK Instruments](./api.md#asynchronous-instrument-api) involved, their callback functions will be triggered. `Collect` SHOULD provide a way to let the caller know whether it succeeded, @@ -1073,11 +1058,10 @@ scraper, and `ForceFlush` would not make sense. Implementors MAY choose the best idiomatic design for their language. For example, they could generalize the [Push Metric Exporter interface](#push-metric-exporter) design and use that for consistency, they -could model the pull exporter as [MetricReader](#metricreader) or -[MetricProducer](#metricproducer), or they could design a completely different -pull exporter interface. If the pull exporter is modeled as MetricReader, -implementors MAY name the MetricExporter interface as PushMetricExporter to -prevent naming confusion. +could model the pull exporter as [MetricReader](#metricreader), or they could +design a completely different pull exporter interface. If the pull exporter is +modeled as MetricReader, implementors MAY name the MetricExporter interface as +PushMetricExporter to prevent naming confusion. The following diagram gives some examples on how `Pull Metric Exporter` can be modeled to interact with other components in the SDK: @@ -1115,39 +1099,41 @@ modeled to interact with other components in the SDK: `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. +[MetricReader](#metricreader) as a source of aggregated metric data. ```text +-----------------+ +--------------+ | | Metrics... | | -| In-memory state +------------> MetricReader | -| | | | -+-----------------+ +--------------+ - -+-----------------+ +--------------+ -| | Metrics... | | -| MetricProducer +------------> MetricReader | +| MeterProvider +------------> MetricReader | | | | | -+-----------------+ +--------------+ ++---------------^^+ +--------------+ +| MetricProducer | ++-----------------+ ``` ### Interface Definition A `MetricProducer` MUST support the following functions: -#### Produce() batch +#### Produce() metrics `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 parameters (e.g. timeout). +MUST return a batch of [Metrics](./data-model.md#metric-points), which MUST NOT +include resource or scope information. `Produce` does not have any required +parameters, however, [OpenTelemetry SDK](../overview.md#sdk) authors MAY choose +to add 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. +#### InstrumentationScope() InstrumentationScope + +`Scope` provides the InstrumentationScope associated with the MetricProducer. +It MUST return the same instrumentation scope for each invocation of +InstrumentationScope(). + ## Defaults and configuration The SDK MUST provide configuration according to the [SDK environment