Add SpanExporter.ForceFlush. (#1467)

Co-authored-by: Armin Ruech <[email protected]>
open-telemetry · Mar 15, 2021 · 3210212 · 3210212
1 parent 2c68d36
commit 3210212
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ release.
 
 ### Traces
 
+- Add `ForceFlush` to `Span Exporter` interface ([#1467](https://github.com/open-telemetry/opentelemetry-specification/pull/1467))
 - Clarify the description for the `TraceIdRatioBased` sampler needs to include the sampler's sampling ratio. ([#1536](https://github.com/open-telemetry/opentelemetry-specification/pull/1536))
 
 ### Metrics

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -72,6 +72,7 @@ status of the feature is not known.
 | [New Span ID created also for non-recording Spans](specification/trace/sdk.md#sdk-span-creation) |          | +  | +    |    | +      | +    | +      |     |      |     | -    | +     |
 | [IdGenerators](specification/trace/sdk.md#id-generators)                                         |          |    | +    |    |        | +    |        |     |      |     |      | +     |
 | [SpanLimits](specification/trace/sdk.md#span-limits)                                             | X        |    | +    |    |        | +    |        |     |      |     |      | +     |
+| [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) |          |    |      |    |        |      |        |     |      |     |      |       |
 
 ## Baggage
 
@@ -142,6 +143,8 @@ Note: Support for environment variables is optional.
 
 | Feature                                               | Optional | Go | Java                                                                  | JS | Python                                                                  | Ruby | Erlang | PHP | Rust | C++ | .Net | Swift |
 |-------------------------------------------------------|----------|----|-----------------------------------------------------------------------|----|-------------------------------------------------------------------------|------|--------|-----|------|-----|------|-------|
+| [Exporter interface](specification/trace/sdk.md#span-exporter)                 |          |    | + |    | +                                                                       |      |        |     |      |     | +    |       |
+| [Exporter interface has `ForceFlush`](specification/trace/sdk.md#forceflush-2) |          |    | + |    |                                                                         |      |        |     |      |     |      |       |
 | Standard output (logging)                             |          | +  | + | +  | +                                                                       | +    | +      | -   | +    | +   | +    | +     |
 | In-memory (mock exporter)                             |          | +  | + | +  | +                                                                       | +    | +      | -   | -    | +   | +    | +     |
 | [OTLP](specification/protocol/otlp.md)                |          |    |   |    |                                                                         |      |        |     |      |     |      |       |

diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md
@@ -473,14 +473,24 @@ make the shutdown timeout configurable.
 
 #### ForceFlush()
 
-Exports all spans that have not yet been exported to the configured `Exporter`.
+This is a hint to ensure that any tasks associated with `Spans` for which the
+`SpanProcessor` had already received events prior to the call to `ForceFlush` SHOULD
+be completed as soon as possible, preferably before returning from this method.
+
+In particular, if any `SpanProcessor` has any associated exporter, it SHOULD
+try to call the exporter's `Export` with all spans for which this was not
+already done and then invoke `ForceFlush` on it.
+The [built-in SpanProcessors](#built-in-span-processors) MUST do so.
+If a timeout is specified (see below), the SpanProcessor MUST prioritize honoring the timeout over
+finishing all calls. It MAY skip or abort some or all Export or ForceFlush
+calls it has made to achieve this goal.
 
 `ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
 failed or timed out.
 
 `ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
 such as when using some FaaS providers that may suspend the process after an
-invocation, but before the `Processor` exports the completed spans.
+invocation, but before the `SpanProcessor` exports the completed spans.
 
 `ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be
 implemented as a blocking API or an asynchronous API which notifies the caller
@@ -588,6 +598,24 @@ return a `Failure` result.
 and the destination is unavailable). OpenTelemetry client authors can decide if they
 want to make the shutdown timeout configurable.
 
+#### `ForceFlush()`
+
+This is a hint to ensure that the export of any `Spans` the exporter has received prior to the
+call to `ForceFlush` SHOULD be completed as soon as possible, preferably before
+returning from this method.
+
+`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded,
+failed or timed out.
+
+`ForceFlush` SHOULD only be called in cases where it is absolutely necessary,
+such as when using some FaaS providers that may suspend the process after an
+invocation, but before the exporter exports the completed spans.
+
+`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.
+
 ### Further Language Specialization
 
 Based on the generic interface definition laid out above library authors must