From 013fb6307df59f0c2009c48bd46d6480c4ed4512 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 16 Aug 2022 18:26:01 +0000 Subject: [PATCH 01/12] add MetricProducer to support third-party sources of metrics --- specification/metrics/sdk.md | 59 ++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 6 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 402e2b14d6e..7f449f5b08a 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -47,6 +47,9 @@ 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) @@ -752,7 +755,7 @@ measurements using the equivalent of the following naive algorithm: common configurable aspects of the OpenTelemetry Metrics SDK and determines the following capabilities: -* Collecting metrics from the SDK on demand. +* Collecting metrics from the SDK or a [MetricProducer](#metricproducer) on demand. * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from the SDK. @@ -760,6 +763,7 @@ To construct a `MetricReader` when setting up an SDK, the caller SHOULD provide at least the following: * The `exporter` to use, which is a `MetricExporter` instance. +* A [MetricProducer](#metricproducer) (optional) to collect metrics from instead of collecting from the SDK. * The default output `aggregation` (optional), a function of instrument kind. If not configured, the [default aggregation](#default-aggregation) SHOULD be used. * The default output `temporality` (optional), a function of instrument kind. If not configured, the Cumulative temporality SHOULD be used. @@ -769,7 +773,7 @@ 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 are output in the +The `MetricReader` MUST ensure that data points from the SDK 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) @@ -778,6 +782,10 @@ 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. + 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` @@ -788,7 +796,8 @@ 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. +one `MeterProvider` instance. The SDK MUST NOT allow a `MetricReader` +configured with a `MetricProducer` to be registered with a `MeterProvider`. ```text +-----------------+ +--------------+ @@ -814,9 +823,9 @@ functions. #### Collect -Collects the metrics from the SDK. If there are [asynchronous -Instruments](./api.md#asynchronous-instrument-api) involved, their callback -functions will be triggered. +Collects the metrics from the SDK or the [MetricProducer](#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, failed or timed out. When the `Collect` operation fails or times out on @@ -1086,6 +1095,44 @@ 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. + +```text ++-----------------+ +--------------+ +| | Metrics... | | +| In-memory state +------------> MetricReader | +| | | | ++-----------------+ +--------------+ + ++-----------------+ +--------------+ +| | Metrics... | | +| MetricProducer +------------> MetricReader | +| | | | ++-----------------+ +--------------+ +``` + +### Interface Definition + +A `MetricProducer` MUST support the following functions: + +#### Produce() batch + +`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. + +`Produce` does not have any required parameters, however, [OpenTelemetry +SDK](../overview.md#sdk) authors MAY choose to add parameters (e.g. timeout). +`Produce` MUST return a batch of [Metric points](./data-model.md#metric-points). + ## Defaults and configuration The SDK MUST provide configuration according to the [SDK environment From 280295e90849e392c2734e2c5b95421a120022a5 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 17 Aug 2022 14:11:12 +0000 Subject: [PATCH 02/12] clarify registration uniqueness --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7f449f5b08a..96b8ee14b2b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -797,7 +797,7 @@ to (Tn+1, Tn+2] - **ONLY** for this particular The SDK MUST NOT allow a `MetricReader` instance to be registered on more than one `MeterProvider` instance. The SDK MUST NOT allow a `MetricReader` -configured with a `MetricProducer` to be registered with a `MeterProvider`. +configured with a non-SDK `MetricProducer` to be registered with `MeterProvider`. ```text +-----------------+ +--------------+ From 5d5c091ada2efba277af899952fc31880ee55d5d Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 17 Aug 2022 15:02:53 +0000 Subject: [PATCH 03/12] describe the produce function --- specification/metrics/sdk.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 96b8ee14b2b..d0a53dbb0e9 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1124,15 +1124,16 @@ 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 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. -`Produce` does not have any required parameters, however, [OpenTelemetry -SDK](../overview.md#sdk) authors MAY choose to add parameters (e.g. timeout). -`Produce` MUST return a batch of [Metric points](./data-model.md#metric-points). - ## Defaults and configuration The SDK MUST provide configuration according to the [SDK environment From e2e6a8ae63c38fd2e8f1a4c26b5878be57f99981 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 17 Aug 2022 20:42:35 +0000 Subject: [PATCH 04/12] add MetricReader.Register --- specification/metrics/sdk.md | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index d0a53dbb0e9..24496322a80 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -37,6 +37,7 @@ linkTitle: SDK * [Exemplar defaults](#exemplar-defaults) - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) + + [Register(MetricProducer)](#registermetricproducer) + [Collect](#collect) + [Shutdown](#shutdown-1) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) @@ -755,7 +756,9 @@ measurements using the equivalent of the following naive algorithm: common configurable aspects of the OpenTelemetry Metrics SDK and determines the following capabilities: -* Collecting metrics from the SDK or a [MetricProducer](#metricproducer) on demand. +* Registering a [MetricProducer](#metricproducer) +* Collecting metrics from the registered [MetricProducer](#metricproducer) on + demand. * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from the SDK. @@ -763,7 +766,6 @@ To construct a `MetricReader` when setting up an SDK, the caller SHOULD provide at least the following: * The `exporter` to use, which is a `MetricExporter` instance. -* A [MetricProducer](#metricproducer) (optional) to collect metrics from instead of collecting from the SDK. * The default output `aggregation` (optional), a function of instrument kind. If not configured, the [default aggregation](#default-aggregation) SHOULD be used. * The default output `temporality` (optional), a function of instrument kind. If not configured, the Cumulative temporality SHOULD be used. @@ -797,7 +799,7 @@ to (Tn+1, Tn+2] - **ONLY** for this particular The SDK MUST NOT allow a `MetricReader` instance to be registered on more than one `MeterProvider` instance. The SDK MUST NOT allow a `MetricReader` -configured with a non-SDK `MetricProducer` to be registered with `MeterProvider`. +registered with a non-SDK `MetricProducer` to be registered with `MeterProvider`. ```text +-----------------+ +--------------+ @@ -821,6 +823,18 @@ 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 invokations 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 of +[MetricProducer](#metricproducer), this MAY be used to register the +MeterProvider. + #### Collect Collects the metrics from the SDK or the [MetricProducer](#metricproducer). If @@ -1060,10 +1074,11 @@ 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 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 +[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. The following diagram gives some examples on how `Pull Metric Exporter` can be modeled to interact with other components in the SDK: From 79c859a3f498f45a57207baf01570112a1bbf4c2 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 18 Aug 2022 10:45:17 -0400 Subject: [PATCH 05/12] Apply suggestions from code review Co-authored-by: Tyler Yahn --- specification/metrics/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 24496322a80..2d797635e1b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -827,11 +827,11 @@ functions. Register causes the MetricReader to use the provided [MetricProducer](#metricproducer) for as a source of aggregated metric data in -subsequent invokations of Collect. It MUST NOT allow more than one +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 of +If the [MeterProvider](#meterprovider) is an instance of a [MetricProducer](#metricproducer), this MAY be used to register the MeterProvider. From 203a04887a6be090cdae5e348d4494e6c4a0c28f Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 18 Aug 2022 20:06:21 +0000 Subject: [PATCH 06/12] MetricProducer is part of a MeterProvider --- specification/metrics/sdk.md | 81 +++++++++++++++--------------------- 1 file changed, 34 insertions(+), 47 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2d797635e1b..5a891fd90c9 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -37,7 +37,6 @@ linkTitle: SDK * [Exemplar defaults](#exemplar-defaults) - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) - + [Register(MetricProducer)](#registermetricproducer) + [Collect](#collect) + [Shutdown](#shutdown-1) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) @@ -50,7 +49,8 @@ linkTitle: SDK * [Pull Metric Exporter](#pull-metric-exporter) - [MetricProducer](#metricproducer) * [Interface Definition](#interface-definition-1) - + [Produce() batch](#produce-batch) + + [Produce() metrics](#produce-metrics) + + [InstrumentationScope() InstrumentationScope](#instrumentationscope-instrumentationscope) - [Defaults and configuration](#defaults-and-configuration) - [Numerical limits handling](#numerical-limits-handling) - [Compatibility requirements](#compatibility-requirements) @@ -80,10 +80,10 @@ 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 @@ -756,9 +756,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. @@ -775,8 +773,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 @@ -784,7 +782,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. @@ -798,8 +796,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 +-----------------+ +--------------+ @@ -823,22 +820,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, @@ -1074,11 +1059,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: @@ -1116,39 +1100,42 @@ 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 + +`InstrumentationScope` provides the +[InstrumentationScope](../glossary.md#instrumentation-scope) associated with +the MetricProducer. A MetricProducer instance MUST return the same +instrumentation scope for each invocation of InstrumentationScope(). + ## Defaults and configuration The SDK MUST provide configuration according to the [SDK environment From c7eb9265e2c4405442ddb29083ba4bba44024881 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Fri, 19 Aug 2022 15:43:54 +0000 Subject: [PATCH 07/12] MetricProducers are passed to MeterProviders --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 5a891fd90c9..10917bb2fb3 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1100,7 +1100,7 @@ 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. +[MeterProvider](#meterprovider) as a source of aggregated metric data. ```text +-----------------+ +--------------+ From 763213cbbd5e21ae3de01a37662edb028fb97b38 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 30 Aug 2022 17:55:32 +0000 Subject: [PATCH 08/12] address feedback from sig meeting --- specification/metrics/sdk.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 10917bb2fb3..eb9f6a78108 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -66,7 +66,8 @@ linkTitle: SDK A `MeterProvider` MUST provide a way to allow a [Resource](../resource/sdk.md) to be specified. If a `Resource` is specified, it SHOULD be associated with all the -metrics produced by any `Meter` from the `MeterProvider`. The [tracing SDK +metrics produced by any `Meter` from the `MeterProvider` or produced by any +`MetricProducer`. The [tracing SDK specification](../trace/sdk.md#additional-span-interfaces) has provided some suggestions regarding how to implement this efficiently. @@ -140,7 +141,9 @@ instances. ### View A `View` provides SDK users with the flexibility to customize the metrics that -are output by the SDK. Here are some examples when a `View` might be needed: +are output by the SDK from Measurements made by OpenTelemetry +[Instruments](./api.md#instrument). Here are some examples when a `View` might +be needed: * Customize which [Instruments](./api.md#instrument) are to be processed/ignored. For example, an [instrumented @@ -823,7 +826,8 @@ functions. #### Collect Collects the metrics from the SDK and its [MetricProducers](#metricproducer). -If there are [asynchronous SDK Instruments](./api.md#asynchronous-instrument-api) +It retrieves a batch of metric points from MetricProducers by invoking +`Produce()`. 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, @@ -836,6 +840,11 @@ SDK](../overview.md#sdk) authors MAY choose to add parameters (e.g. callback, filter, timeout). [OpenTelemetry SDK](../overview.md#sdk) authors MAY choose the return value type, or do not return anything. +The `MetricReader` MUST ensure the batch of metric points from +`MetricProducers` are associated with the `MetricProducer`'s +`InstrumentationScope()`, and with the `MeterProvider`'s configured resource if +it is possible for those to conflict. + Note: it is expected that the `MetricReader.Collect` implementations will be provided by the SDK, so it is RECOMMENDED to prevent the user from accidentally overriding it, if possible (e.g. `final` in C++ and Java, `sealed` in C#). @@ -906,8 +915,12 @@ primarily a simple telemetry data encoder and transmitter. Metric Exporter has access to the [aggregated metrics data](./data-model.md#timeseries-model). Metric Exporters SHOULD report an error condition for data output by the `MetricReader` with -unsupported Aggregation or Aggregation Temporality, as this condition -can be corrected by a change of `MetricReader` configuration. +unsupported Aggregation or Aggregation Temporality. For data originating from +OpenTelemetry Instruments, this condition can be corrected by a change of +`MetricReader` configuration. For metric data from a `MetricProducer`, it is an +indication to the user that metric data is being dropped. The presence of data +with an unsupported Aggregation or Aggregation Temporality SHOULD NOT prevent +the exporter from sending other metric data. There could be multiple [Push Metric Exporters](#push-metric-exporter) or [Pull Metric Exporters](#pull-metric-exporter) or even a mixture of both configured at @@ -1119,10 +1132,12 @@ A `MetricProducer` MUST support the following functions: #### Produce() metrics `Produce` provides metrics from the MetricProducer to the caller. `Produce` -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). +MUST return a batch of [Metrics](./data-model.md#metric-points). If the batch +of Metrics includes an Instrumentation Scope, it MUST be the same as the +InstrumentationScope returned by InstrumentationScope(). The batch of metrics +SHOULD NOT include resource. `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` From c2e7ef5ea67b58e3a37aa16503d9424abe871063 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 7 Sep 2022 18:13:52 +0000 Subject: [PATCH 09/12] add instrumentation link --- specification/metrics/sdk.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index eb9f6a78108..412f94f92fe 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -776,10 +776,11 @@ 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 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) +The `MetricReader` MUST ensure that data points from OTel +[instruments](./api.md#instrument) 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 with Delta temporality, this means converting [Cumulative to Delta](supplementary-guidelines.md#asynchronous-example-delta-temporality) aggregation From fd3c9c8e816c49669993223ef9f283020b6e07cd Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Fri, 9 Sep 2022 10:21:14 -0400 Subject: [PATCH 10/12] Update specification/metrics/sdk.md Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 412f94f92fe..54745486cb8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -776,7 +776,7 @@ 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 OTel +The `MetricReader` MUST ensure that data points from OpenTelemetry [instruments](./api.md#instrument) are output in the configured aggregation temporality for each instrument kind. For synchronous instruments being output with Cumulative temporality, this means converting From 4877d9d8efe2e46b9bee15324009fe038525402a Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Tue, 13 Sep 2022 18:28:16 +0000 Subject: [PATCH 11/12] emit warnings for duplicate scopes --- specification/metrics/sdk.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 54745486cb8..c343beb04df 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -86,6 +86,12 @@ Configuration (i.e., [MetricExporters](#metricexporter), 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. +If a meter is created which produces an +[`InstrumentationScope`](../glossary.md#instrumentation-scope), which matches +the InstrumentationScope of a [MetricProducer](#metricproducer), or if multiple +[MetricProducers](#metricproducer) have the same InstrumenatationScope the SDK +SHOULD emit a warning. + The `MeterProvider` MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `MetricReader`), the updated configuration MUST also apply to all already returned `Meters` (i.e. it MUST NOT From 79948c5a7930882d8dfd1a304c46fbc9f3ea692e Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Wed, 14 Sep 2022 14:12:56 -0400 Subject: [PATCH 12/12] Update specification/metrics/sdk.md Co-authored-by: Andrew Hayworth --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index c343beb04df..8810c938e1d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -89,7 +89,7 @@ MAY be done at the time of MeterProvider creation if appropriate. If a meter is created which produces an [`InstrumentationScope`](../glossary.md#instrumentation-scope), which matches the InstrumentationScope of a [MetricProducer](#metricproducer), or if multiple -[MetricProducers](#metricproducer) have the same InstrumenatationScope the SDK +[MetricProducers](#metricproducer) have the same InstrumentationScope the SDK SHOULD emit a warning. The `MeterProvider` MAY provide methods to update the configuration. If