Skip to content

Commit

Permalink
Spec out the MeterProvider ForceFlush and Shutdown requirement (open-…
Browse files Browse the repository at this point in the history
…telemetry#1913)

* spec out the MeterProvider ForceFlush and Shutdown requirement

* adjust wording

* adjust wording

* fix wording
  • Loading branch information
reyang authored and owais committed Sep 14, 2021
1 parent adb55ff commit 74f81f8
Showing 1 changed file with 38 additions and 2 deletions.
40 changes: 38 additions & 2 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,11 +66,47 @@ configuration only via this reference.

### Shutdown

TODO
This method provides a way for provider to do any cleanup required.

`Shutdown` MUST be called only once for each `MeterProvider` instance. After the
call to `Shutdown`, subsequent attempts to get a `Meter` are not allowed. SDKs
SHOULD return a valid no-op Meter for these calls, if possible.

`Shutdown` SHOULD provide a way to let the caller know whether it succeeded,
failed or timed out.

`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` can be
implemented as a blocking API or an asynchronous API which notifies the caller
via a callback or an event. OpenTelemetry client authors can decide if they want
to make the shutdown timeout configurable.

`Shutdown` MUST be implemented at least by invoking `Shutdown` on all registered
[MetricReader](#metricreader) and [MetricExporter](#metricexporter) instances.

### ForceFlush

TODO
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.

`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` can be
implemented as a blocking API or an asynchronous API which notifies the caller
via a callback or an event. OpenTelemetry client authors can 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

Expand Down

0 comments on commit 74f81f8

Please sign in to comment.