From ff5ea6145d2f51eb3dca4fffd33fbc460ea8c2a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20Paj=C4=85k?= <pellared@hotmail.com>
Date: Wed, 9 Aug 2023 00:57:06 +0200
Subject: [PATCH] Refine MetricProvider.ForceFlush and define ForceFlush for
 periodic exporting MetricReader (#3563)

---
 CHANGELOG.md                 |  2 ++
 specification/metrics/sdk.md | 38 +++++++++++++++++++++++++++---------
 2 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae5cd663d22..9c52d225d68 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
index 580b90cfd71..e09f18ff222 100644
--- a/specification/metrics/sdk.md
+++ b/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.