add MetricProducer to metric SDK, which can provide additional sources

of metrics to MetricReaders.
open-telemetry · Aug 10, 2022 · c4efc75 · c4efc75
1 parent 82707fd
commit c4efc75
Showing 1 changed file with 50 additions and 7 deletions.
diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -751,14 +751,15 @@ 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 and [MetricProducers](#metricproducer) on demand.
 * Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from
   the SDK.
 
 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.
+* [MetricProducers](#metricproducer) (optional) to collect metrics from in addition to 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.
 
@@ -768,15 +769,19 @@ 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
+synchronous SDK 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
+aggregation temporality.  For asynchronous SDK instruments being output
 with Delta temporality, this means converting [Cumulative to
 Delta](supplementary-guidelines.md#asynchronous-example-delta-temporality) aggregation
 temporality.
 
+The `MetriccReader` is not required to ensure data points from non-SDK
+[MetricProducers](#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`
@@ -813,9 +818,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 and [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,
 failed or timed out. When the `Collect` operation fails or times out on
@@ -1085,6 +1090,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 ------------>                              |
+  +-----------------+            | Exporting MetricReader      |
+  | MetricProducer A------------>                              |
+  +-----------------+            |  +-----------------------+  |
+  | MetricProducer B------------>   |                       |  |
+  +-----------------+            |  | MetricExporter (pull) +------> Another process (scraper)
+                                 |  |                       |  |
+                                 |  +-----------------------+  |
+                                 |                             |
+                                 +-----------------------------+
+  ```
+
+#### 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