From cdf5c3650ffa613dcc9c252d57a89540f2faf189 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 26 Oct 2021 19:12:23 -0700 Subject: [PATCH 1/4] add exporter ForceFlush --- src/OpenTelemetry/BaseExportProcessor.cs | 6 +++ src/OpenTelemetry/BaseExporter.cs | 53 ++++++++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/src/OpenTelemetry/BaseExportProcessor.cs b/src/OpenTelemetry/BaseExportProcessor.cs index e05c377aa49..df07767da40 100644 --- a/src/OpenTelemetry/BaseExportProcessor.cs +++ b/src/OpenTelemetry/BaseExportProcessor.cs @@ -59,6 +59,12 @@ internal override void SetParentProvider(BaseProvider parentProvider) protected abstract void OnExport(T data); + /// + protected override bool OnForceFlush(int timeoutMilliseconds) + { + return this.exporter.ForceFlush(timeoutMilliseconds); + } + /// protected override bool OnShutdown(int timeoutMilliseconds) { diff --git a/src/OpenTelemetry/BaseExporter.cs b/src/OpenTelemetry/BaseExporter.cs index 079cd4be26e..e520699d2a8 100644 --- a/src/OpenTelemetry/BaseExporter.cs +++ b/src/OpenTelemetry/BaseExporter.cs @@ -57,6 +57,38 @@ public abstract class BaseExporter : IDisposable /// Result of the export operation. public abstract ExportResult Export(in Batch batch); + /// + /// Flushes the exporter, blocks the current thread until flush + /// completed, shutdown signaled or timed out. + /// + /// + /// The number (non-negative) of milliseconds to wait, or + /// Timeout.Infinite to wait indefinitely. + /// + /// + /// Returns true when flush succeeded; otherwise, false. + /// + /// + /// Thrown when the timeoutMilliseconds is smaller than -1. + /// + /// + /// This function guarantees thread-safety. + /// + public bool ForceFlush(int timeoutMilliseconds = Timeout.Infinite) + { + Guard.InvalidTimeout(timeoutMilliseconds, nameof(timeoutMilliseconds)); + + try + { + return this.OnForceFlush(timeoutMilliseconds); + } + catch (Exception ex) + { + OpenTelemetrySdkEventSource.Log.SpanProcessorException(nameof(this.ForceFlush), ex); + return false; + } + } + /// /// Attempts to shutdown the exporter, blocks the current thread until /// shutdown completed or timed out. @@ -102,6 +134,27 @@ public void Dispose() GC.SuppressFinalize(this); } + /// + /// Called by ForceFlush. This function should block the current + /// thread until flush completed, shutdown signaled or timed out. + /// + /// + /// The number (non-negative) of milliseconds to wait, or + /// Timeout.Infinite to wait indefinitely. + /// + /// + /// Returns true when flush succeeded; otherwise, false. + /// + /// + /// This function is called synchronously on the thread which called + /// ForceFlush. This function should be thread-safe, and should + /// not throw exceptions. + /// + protected virtual bool OnForceFlush(int timeoutMilliseconds) + { + return true; + } + /// /// Called by Shutdown. This function should block the current /// thread until shutdown completed or timed out. From 864da45f5f20826176a1f8439c89155b91352419 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 26 Oct 2021 19:16:11 -0700 Subject: [PATCH 2/4] update changelog --- src/OpenTelemetry/CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/OpenTelemetry/CHANGELOG.md b/src/OpenTelemetry/CHANGELOG.md index c3d325864ff..01aedbec05d 100644 --- a/src/OpenTelemetry/CHANGELOG.md +++ b/src/OpenTelemetry/CHANGELOG.md @@ -6,6 +6,9 @@ `FormatException` if it fails to parse any of the supported environment variables. +* Added `BaseExporter.ForceFlush`. + ([#2525](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2525)) + ## 1.2.0-beta1 Released 2021-Oct-08 From e225e0287ba689d6b993ba0e5a60747947d0bf60 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 26 Oct 2021 19:26:50 -0700 Subject: [PATCH 3/4] update docs --- docs/logs/extending-the-sdk/README.md | 5 +++-- docs/trace/extending-the-sdk/README.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/logs/extending-the-sdk/README.md b/docs/logs/extending-the-sdk/README.md index 3628e77eb86..7368aea4f9e 100644 --- a/docs/logs/extending-the-sdk/README.md +++ b/docs/logs/extending-the-sdk/README.md @@ -18,11 +18,12 @@ not covered by the built-in exporters: * Exporters should derive from `OpenTelemetry.BaseExporter` (which belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package) and implement the `Export` method. -* Exporters can optionally implement the `OnShutdown` method. +* Exporters can optionally implement the `OnForceFlush` and `OnShutdown` method. * Depending on user's choice and load on the application, `Export` may get called with one or more log records. * Exporters will only receive sampled-in log records. -* Exporters should not throw exceptions from `Export` and `OnShutdown`. +* Exporters should not throw exceptions from `Export`, `OnForceFlush` and + `OnShutdown`. * Exporters should not modify log records they receive (the same log records may be exported again by different exporter). * Exporters are responsible for any retry logic needed by the scenario. The SDK diff --git a/docs/trace/extending-the-sdk/README.md b/docs/trace/extending-the-sdk/README.md index da1d51ed700..056712fc877 100644 --- a/docs/trace/extending-the-sdk/README.md +++ b/docs/trace/extending-the-sdk/README.md @@ -22,11 +22,12 @@ not covered by the built-in exporters: * Exporters should derive from `OpenTelemetry.BaseExporter` (which belongs to the [OpenTelemetry](../../../src/OpenTelemetry/README.md) package) and implement the `Export` method. -* Exporters can optionally implement the `OnShutdown` method. +* Exporters can optionally implement the `OnForceFlush` and `OnShutdown` method. * Depending on user's choice and load on the application, `Export` may get called with one or more activities. * Exporters will only receive sampled-in and ended activities. -* Exporters should not throw exceptions from `Export` and `OnShutdown`. +* Exporters should not throw exceptions from `Export`, `OnForceFlush` and + `OnShutdown`. * Exporters should not modify activities they receive (the same activity may be exported again by different exporter). * Exporters are responsible for any retry logic needed by the scenario. The SDK From f839c975ed44031d74abf5b0069b462214e9a6cf Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 26 Oct 2021 20:01:58 -0700 Subject: [PATCH 4/4] update public API file --- build/Common.prod.props | 11 +++++------ .../.publicApi/netstandard2.0/PublicAPI.Unshipped.txt | 6 +++++- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/build/Common.prod.props b/build/Common.prod.props index 1c810c880f3..6cd80de7e49 100644 --- a/build/Common.prod.props +++ b/build/Common.prod.props @@ -6,13 +6,12 @@ runtime; build; native; contentfiles; analyzers; buildtransitive all - - - + + --> + diff --git a/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt b/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt index 45e87d487f6..df10ae4eae8 100644 --- a/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt +++ b/src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt @@ -1,2 +1,6 @@ +OpenTelemetry.BaseExporter.ForceFlush(int timeoutMilliseconds = -1) -> bool OpenTelemetry.Trace.BatchExportActivityProcessorOptions -OpenTelemetry.Trace.BatchExportActivityProcessorOptions.BatchExportActivityProcessorOptions() -> void \ No newline at end of file +OpenTelemetry.Trace.BatchExportActivityProcessorOptions.BatchExportActivityProcessorOptions() -> void +override OpenTelemetry.BaseExportProcessor.OnForceFlush(int timeoutMilliseconds) -> bool +override OpenTelemetry.BatchExportProcessor.Dispose(bool disposing) -> void +virtual OpenTelemetry.BaseExporter.OnForceFlush(int timeoutMilliseconds) -> bool