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.