Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explicitly define metric reader force flush operation #3084

Closed
wants to merge 5 commits into from
Closed

Explicitly define metric reader force flush operation #3084

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a9aae7a
Explicitly define metric reader force flush operation
legendecas Jan 9, 2023
903e5a0
fixup! Explicitly define metric reader force flush operation
legendecas Jan 13, 2023
621b325
Merge branch 'main' into metric-reader-flush
legendecas Jan 14, 2023
09d4ea0
Merge branch 'main' into metric-reader-flush
legendecas Jan 24, 2023
060bd1f
Merge branch 'main' into metric-reader-flush
legendecas Feb 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ release.
"base2_exponential_bucket_histogram". Mark exponential histogram data model and
base2 exponential histogram aggregation as stable.
([#3041](https://github.com/open-telemetry/opentelemetry-specification/pull/3041))
- Explicitly define metric reader force flush operation.
([#3084](https://github.com/open-telemetry/opentelemetry-specification/pull/3084))

### Logs

Expand Down
29 changes: 22 additions & 7 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ linkTitle: SDK
* [MetricReader operations](#metricreader-operations)
+ [RegisterProducer(metricProducer)](#registerproducermetricproducer)
+ [Collect](#collect)
+ [ForceFlush](#forceflush-1)
+ [Shutdown](#shutdown-1)
* [Periodic exporting MetricReader](#periodic-exporting-metricreader)
- [MetricExporter](#metricexporter)
Expand Down Expand Up @@ -120,11 +121,7 @@ decide if they want to make the shutdown timeout configurable.

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
data when it is being asked by the scraper, so `ForceFlush` would not make much
sense.
so they can do as much as they could to consume or send the metrics.

`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
Expand Down Expand Up @@ -884,6 +881,23 @@ 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#).

#### ForceFlush

This method provides a way for the `MetricReader` and the configured
[Metric Exporter](#metricexporter) to do as much as they could to consume or
send the metrics.

`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
failed or timed out. 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 data when it is
being asked by the scraper, so `ForceFlush` would not make much sense.

`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. [OpenTelemetry SDK](../overview.md#sdk) authors MAY
decide if they want to make the timeout configurable.

#### Shutdown

This method provides a way for the `MetricReader` to do any cleanup required.
Expand Down Expand Up @@ -915,8 +929,9 @@ Configurable parameters:

One possible implementation of periodic exporting MetricReader is to inherit
from `MetricReader` and start a background task which calls the inherited
`Collect()` method at the requested `exportIntervalMillis`. The reader's
`Collect()` method may still be invoked by other callers. For example,
`Collect()` method at the requested `exportIntervalMillis` and on the invocation
of inherited `ForceFlush`. The reader's `Collect()` method may still be invoked
by other callers. For example,

* A user configures periodic exporting MetricReader with a push exporter and a
30 second interval.
Expand Down