Refine MetricProvider.ForceFlush and define ForceFlush for periodic e…

…xporting MetricReader (#3563)

CHANGELOG.md

@@ -21,6 +21,8 @@ release.
   ([#3642](https://github.com/open-telemetry/opentelemetry-specification/pull/3642))
 - MetricProducers are provided as config to MetricReaders instead of through a RegisterProducer operation.
   ([#3613](https://github.com/open-telemetry/opentelemetry-specification/pull/3613))
+- Refine `MetricProvider.ForceFlush` and define `ForceFlush` for periodic exporting MetricReader.
+  ([#3563](https://github.com/open-telemetry/opentelemetry-specification/pull/3563))
 
 ### Logs
 

specification/metrics/sdk.md

@@ -62,6 +62,7 @@ linkTitle: SDK
     + [Collect](#collect)
     + [Shutdown](#shutdown-1)
   * [Periodic exporting MetricReader](#periodic-exporting-metricreader)
+    + [ForceFlush](#forceflush-1)
 - [MetricExporter](#metricexporter)
   * [Push Metric Exporter](#push-metric-exporter)
     + [Interface Definition](#interface-definition)
@@ -159,13 +160,16 @@ decide if they want to make the shutdown timeout configurable.
 ### ForceFlush
 
 This method provides a way for provider to notify the registered
-[MetricReader](#metricreader) and [MetricExporter](#metricexporter) instances,
-so they can do as much as they could to consume or send the metrics. Note:
-unlike [Push Metric Exporter](#push-metric-exporter) which can send data on its
-own schedule, [Pull Metric Exporter](#pull-metric-exporter) can only send the
+[MetricReader](#metricreader) instances that have an associated
+[Push Metric Exporter](#push-metric-exporter), so they can do as much
+as they could to collect and send the metrics.
+Note: [Pull Metric Exporter](#pull-metric-exporter) can only send the
 data when it is being asked by the scraper, so `ForceFlush` would not make much
 sense.
 
+`ForceFlush` MUST invoke `ForceFlush` on all registered
+[MetricReader](#metricreader) instances that implement `ForceFlush`.
+
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there
 is an error condition; and if there is no error condition, it should return some
@@ -177,10 +181,6 @@ implemented as a blocking API or an asynchronous API which notifies the caller
 via a callback or an event. [OpenTelemetry SDK](../overview.md#sdk) authors MAY
 decide if they want to make the flush timeout configurable.
 
-`ForceFlush` MUST invoke `ForceFlush` on all registered
-[MetricReader](#metricreader) and [Push Metric Exporter](#push-metric-exporter)
-instances.
-
 ### View
 
 A `View` provides SDK users with the flexibility to customize the metrics that
@@ -1168,6 +1168,25 @@ from `MetricReader` and start a background task which calls the inherited
   the background task calls `Collect()` which passes metrics to the push
   exporter.
 
+#### ForceFlush
+
+This method provides a way for the periodic exporting MetricReader
+so it can do as much as it could to collect and send the metrics.
+
+`ForceFlush` SHOULD collect metrics, call [`Export(batch)`](#exportbatch)
+and [`ForceFlush()`](#forceflush-2) on the configured
+[Push Metric Exporter](#push-metric-exporter).
+
+`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
+failed or timed out. `ForceFlush` SHOULD return some **ERROR** status if there
+is an error condition; and if there is no error condition, it should return some
+**NO ERROR** status, language implementations MAY decide how to model **ERROR**
+and **NO ERROR**.
+
+`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` MAY be
+implemented as a blocking API or an asynchronous API which notifies the caller
+via a callback or an event.
+
 ## MetricExporter
 
 **Status**: [Stable](../document-status.md)
@@ -1478,7 +1497,8 @@ called concurrently.
 
 **ExemplarReservoir** - all methods are safe to be called concurrently.
 
-**MetricReader** - `Collect` and `Shutdown` are safe to be called concurrently.
+**MetricReader** - `Collect`, `ForceFlush` (for periodic exporting MetricReader)
+and `Shutdown` are safe to be called concurrently.
 
 **MetricExporter** - `ForceFlush` and `Shutdown` are safe to be called
 concurrently.