From 3210212d4081ac542c698fd15cc725014feea6d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 15 Mar 2021 18:01:51 +0100 Subject: [PATCH] Add SpanExporter.ForceFlush. (#1467) Co-authored-by: Armin Ruech --- CHANGELOG.md | 1 + spec-compliance-matrix.md | 3 +++ specification/trace/sdk.md | 32 ++++++++++++++++++++++++++++++-- 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b22fca0a75a..af75d995695 100644 --- 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 index 161062f3e78..28c9c21dd84 100644 --- 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 index a99404fbecd..cdbb6790eae 100644 --- 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