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