From e02d40cc1389f9eb312f61772001100bc7b6c6ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 25 Feb 2021 15:01:55 +0100 Subject: [PATCH 01/13] Add SpanExporter.ForceFlush. --- specification/trace/sdk.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index b4f6b8e06c6..cc8111e9d26 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -467,14 +467,20 @@ 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 the `SpanProcessor` has any associated exporters, it MUST call +the exporter's `Export` with all spans for which this was not already done and +then invoke `ForceFlush` on it. `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 @@ -582,6 +588,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 any `Spans` passed to the exporter 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 `Processor` 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 From 43f12aad5a6f45d37eb39d2bba2a53129a7cdcd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 25 Feb 2021 15:18:40 +0100 Subject: [PATCH 02/13] Add CHANGELOG, compliance matrix entries. --- CHANGELOG.md | 1 + spec-compliance-matrix.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index f35d8c18516..239c83da6ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ release. - Adds `none` as a possible value for OTEL_TRACES_EXPORTER and OTEL_METRICS_EXPORTER to disable export ([#1439](https://github.com/open-telemetry/opentelemetry-specification/pull/1439)) - Add [`ForceFlush`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#forceflush) to SDK's `TracerProvider` ([#1452](https://github.com/open-telemetry/opentelemetry-specification/pull/1452)) +- Add `ForceFlush` to `Span Exporter` interface [#????](https://github.com/open-telemetry/opentelemetry-specification/pull/????). ## v1.0.1 (2021-02-11) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index dc48507ef7e..995de38837d 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -142,6 +142,8 @@ Note: Support for environment variables is optional. | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .Net | Swift | |-------------------------------------------------------|----------|----|-----------------------------------------------------------------------|----|-------------------------------------------------------------------------|------|--------|-----|------|-----|------|-------| +| Exporter interface | | | + | | + | | | | | | + | | +| Exporter interface has `ForceFlush` | | | + | | | | | | | | | | | Standard output (logging) | | + | + | + | + | + | + | - | + | + | + | + | | In-memory (mock exporter) | | + | + | + | + | + | + | - | - | + | + | + | | [OTLP](specification/protocol/otlp.md) | | | | | | | | | | | | | From 4be0529065792901e611595e2a0a160a37877457 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 25 Feb 2021 15:20:55 +0100 Subject: [PATCH 03/13] Fill out PR#. --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 239c83da6ba..90ae78c706c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ release. - Adds `none` as a possible value for OTEL_TRACES_EXPORTER and OTEL_METRICS_EXPORTER to disable export ([#1439](https://github.com/open-telemetry/opentelemetry-specification/pull/1439)) - Add [`ForceFlush`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#forceflush) to SDK's `TracerProvider` ([#1452](https://github.com/open-telemetry/opentelemetry-specification/pull/1452)) -- Add `ForceFlush` to `Span Exporter` interface [#????](https://github.com/open-telemetry/opentelemetry-specification/pull/????). +- Add `ForceFlush` to `Span Exporter` interface [#1467](https://github.com/open-telemetry/opentelemetry-specification/pull/1467). ## v1.0.1 (2021-02-11) From 5f8f89071bcc863cfc6f67f3921352079fae9c77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 25 Feb 2021 18:44:23 +0100 Subject: [PATCH 04/13] Apply suggestions from code review Co-authored-by: Armin Ruech --- CHANGELOG.md | 2 +- specification/trace/sdk.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 90ae78c706c..6dfb88ac053 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ release. - Adds `none` as a possible value for OTEL_TRACES_EXPORTER and OTEL_METRICS_EXPORTER to disable export ([#1439](https://github.com/open-telemetry/opentelemetry-specification/pull/1439)) - Add [`ForceFlush`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#forceflush) to SDK's `TracerProvider` ([#1452](https://github.com/open-telemetry/opentelemetry-specification/pull/1452)) -- Add `ForceFlush` to `Span Exporter` interface [#1467](https://github.com/open-telemetry/opentelemetry-specification/pull/1467). +- Add `ForceFlush` to `Span Exporter` interface ([#1467](https://github.com/open-telemetry/opentelemetry-specification/pull/1467)) ## v1.0.1 (2021-02-11) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index cc8111e9d26..f13209f749e 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -599,7 +599,7 @@ 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 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 From 2f27ddf16dedd167402f2e80af7aabf86e112fd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 25 Feb 2021 18:44:34 +0100 Subject: [PATCH 05/13] Update specification/trace/sdk.md --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index f13209f749e..51e9b57e1ad 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -590,7 +590,7 @@ want to make the shutdown timeout configurable. #### `ForceFlush()` -This is a hint to ensure that any `Spans` passed to the exporter prior to the +This is a hint to ensure that the export of any `Spans` passed to the exporter prior to the call to `ForceFlush` SHOULD be completed as soon as possible, preferably before returning from this method. From 04e3e29f63f7058d69da3e599529cb4ea740ccc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 26 Feb 2021 20:18:03 +0100 Subject: [PATCH 06/13] Tweak wording on SpanProcessor.ForceFlush --- specification/trace/sdk.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 51e9b57e1ad..6c246d68d21 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -471,9 +471,13 @@ 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 the `SpanProcessor` has any associated exporters, it MUST call -the exporter's `Export` with all spans for which this was not already done and -then invoke `ForceFlush` on it. +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. From c74590f678fd8065257e802b2f960dad35d9ce2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Fri, 26 Feb 2021 20:33:06 +0100 Subject: [PATCH 07/13] Update specification/trace/sdk.md --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 6c246d68d21..d9a7ef55132 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -594,7 +594,7 @@ want to make the shutdown timeout configurable. #### `ForceFlush()` -This is a hint to ensure that the export of any `Spans` passed to the exporter prior to the +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. From 1d26e921ca5fe5e64268ad247427abbc01f165a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 15 Mar 2021 17:39:10 +0100 Subject: [PATCH 08/13] Update compliance matrix: Add row, add links Add "SpanProcessor implements ForceFlushes spec" row --- spec-compliance-matrix.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 54deb40b21b..2106025359a 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 | | + | | | + | | | | | | + | +| [SpanProcessor implements ForceFlushes spec](specification/trace/sdk.md#force-flush-2) | | | | | | | | | | | | | ## Baggage @@ -142,8 +143,8 @@ Note: Support for environment variables is optional. | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .Net | Swift | |-------------------------------------------------------|----------|----|-----------------------------------------------------------------------|----|-------------------------------------------------------------------------|------|--------|-----|------|-----|------|-------| -| Exporter interface | | | + | | + | | | | | | + | | -| Exporter interface has `ForceFlush` | | | + | | | | | | | | | | +| [Exporter interface](https://github.com/dynatrace-oss-contrib/opentelemetry-specification/blob/exporter-forceflush/specification/trace/sdk.md#span-exporter) | | | + | | + | | | | | | + | | +| [Exporter interface has `ForceFlush`](https://github.com/dynatrace-oss-contrib/opentelemetry-specification/blob/exporter-forceflush/specification/trace/sdk.md#forceflush-2) | | | + | | | | | | | | | | | Standard output (logging) | | + | + | + | + | + | + | - | + | + | + | + | | In-memory (mock exporter) | | + | + | + | + | + | + | - | - | + | + | + | | [OTLP](specification/protocol/otlp.md) | | | | | | | | | | | | | From e71c9ef2cb9611b50fbb4b181b93d380c9db3ec2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 15 Mar 2021 17:40:59 +0100 Subject: [PATCH 09/13] Fix links --- spec-compliance-matrix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2106025359a..2bb2a69b73c 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -143,8 +143,8 @@ Note: Support for environment variables is optional. | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .Net | Swift | |-------------------------------------------------------|----------|----|-----------------------------------------------------------------------|----|-------------------------------------------------------------------------|------|--------|-----|------|-----|------|-------| -| [Exporter interface](https://github.com/dynatrace-oss-contrib/opentelemetry-specification/blob/exporter-forceflush/specification/trace/sdk.md#span-exporter) | | | + | | + | | | | | | + | | -| [Exporter interface has `ForceFlush`](https://github.com/dynatrace-oss-contrib/opentelemetry-specification/blob/exporter-forceflush/specification/trace/sdk.md#forceflush-2) | | | + | | | | | | | | | | +| [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) | | | | | | | | | | | | | From 59a05e0ee4d2f0c480350806d5f912093abe2d66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 15 Mar 2021 17:42:50 +0100 Subject: [PATCH 10/13] Fix link again --- spec-compliance-matrix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2bb2a69b73c..be68278cf50 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -72,7 +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 | | + | | | + | | | | | | + | -| [SpanProcessor implements ForceFlushes spec](specification/trace/sdk.md#force-flush-2) | | | | | | | | | | | | | +| [SpanProcessor implements ForceFlushes spec](specification/trace/sdk.md#force-flush-1) | | | | | | | | | | | | | ## Baggage @@ -144,7 +144,7 @@ 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) | | | + | | | | | | | | | | +| [Exporter interface has `ForceFlush`](specification/trace/sdk.md#forceflush-1) | | | + | | | | | | | | | | | Standard output (logging) | | + | + | + | + | + | + | - | + | + | + | + | | In-memory (mock exporter) | | + | + | + | + | + | + | - | - | + | + | + | | [OTLP](specification/protocol/otlp.md) | | | | | | | | | | | | | From 4b79b870678e6fbb34fe352cc9e40e8c6ba78433 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 15 Mar 2021 17:45:02 +0100 Subject: [PATCH 11/13] Fix links again (2) --- spec-compliance-matrix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index be68278cf50..1480cfde464 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -72,7 +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 | | + | | | + | | | | | | + | -| [SpanProcessor implements ForceFlushes spec](specification/trace/sdk.md#force-flush-1) | | | | | | | | | | | | | +| [SpanProcessor implements ForceFlushes spec](specification/trace/sdk.md#forceflush-1) | | | | | | | | | | | | | ## Baggage @@ -144,7 +144,7 @@ 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-1) | | | + | | | | | | | | | | +| [Exporter interface has `ForceFlush`](specification/trace/sdk.md#forceflush-2) | | | + | | | | | | | | | | | Standard output (logging) | | + | + | + | + | + | + | - | + | + | + | + | | In-memory (mock exporter) | | + | + | + | + | + | + | - | - | + | + | + | | [OTLP](specification/protocol/otlp.md) | | | | | | | | | | | | | From a4e9209c202255f43cccea7735579cd6836f9d08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Mon, 15 Mar 2021 17:48:25 +0100 Subject: [PATCH 12/13] Update spec-compliance-matrix.md --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 1480cfde464..bcfbf7ce8f9 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -72,7 +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 | | + | | | + | | | | | | + | -| [SpanProcessor implements ForceFlushes spec](specification/trace/sdk.md#forceflush-1) | | | | | | | | | | | | | +| [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | | | | | | | | | | | ## Baggage From 30af37a753b383986d7a4ade71ff327bbea4c0b0 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Mon, 15 Mar 2021 17:59:14 +0100 Subject: [PATCH 13/13] Update spec-compliance-matrix.md --- spec-compliance-matrix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index bcfbf7ce8f9..28c9c21dd84 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -72,7 +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) | | | | | | | | | | | | | +| [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | | | | | | | | | | | ## Baggage @@ -143,7 +143,7 @@ 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](specification/trace/sdk.md#span-exporter) | | | + | | + | | | | | | + | | | [Exporter interface has `ForceFlush`](specification/trace/sdk.md#forceflush-2) | | | + | | | | | | | | | | | Standard output (logging) | | + | + | + | + | + | + | - | + | + | + | + | | In-memory (mock exporter) | | + | + | + | + | + | + | - | - | + | + | + |