Add exporter ForceFlush (#2525)

build/Common.prod.props

@@ -6,13 +6,12 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
-  </ItemGroup>
-
-  <!-- Temporarily disable public API check till metrics get close to Release
-  <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="$(MicrosoftCodeAnalysisAnalyzersPkgVer)" Condition=" $(OS) == 'Windows_NT'">
+    <!-- Temporarily disable public API check till metrics get close to Release
+    <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="$(MicrosoftCodeAnalysisAnalyzersPkgVer)" Condition=" $(OS) == 'Windows_NT'">
       <PrivateAssets>All</PrivateAssets>
-  </PackageReference>
-  -->
+    </PackageReference>
+    -->
+  </ItemGroup>
 
   <ItemGroup Condition="'$(MinVerTagPrefix)' == 'core-' AND '$(CheckAPICompatibility)' == 'true'">
     <PackageReference Include="Microsoft.DotNet.ApiCompat" Version="6.0.0-beta.21308.1" PrivateAssets="All" />

docs/logs/extending-the-sdk/README.md

@@ -18,11 +18,12 @@ not covered by the built-in exporters:
 * Exporters should derive from `OpenTelemetry.BaseExporter<LogRecord>` (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

docs/trace/extending-the-sdk/README.md

@@ -22,11 +22,12 @@ not covered by the built-in exporters:
 * Exporters should derive from `OpenTelemetry.BaseExporter<Activity>` (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

src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt

@@ -1,2 +1,6 @@
+OpenTelemetry.BaseExporter<T>.ForceFlush(int timeoutMilliseconds = -1) -> bool
 OpenTelemetry.Trace.BatchExportActivityProcessorOptions
-OpenTelemetry.Trace.BatchExportActivityProcessorOptions.BatchExportActivityProcessorOptions() -> void
+OpenTelemetry.Trace.BatchExportActivityProcessorOptions.BatchExportActivityProcessorOptions() -> void
+override OpenTelemetry.BaseExportProcessor<T>.OnForceFlush(int timeoutMilliseconds) -> bool
+override OpenTelemetry.BatchExportProcessor<T>.Dispose(bool disposing) -> void
+virtual OpenTelemetry.BaseExporter<T>.OnForceFlush(int timeoutMilliseconds) -> bool

src/OpenTelemetry/BaseExportProcessor.cs

@@ -59,6 +59,12 @@ namespace OpenTelemetry
 
         protected abstract void OnExport(T data);
 
+        /// <inheritdoc />
+        protected override bool OnForceFlush(int timeoutMilliseconds)
+        {
+            return this.exporter.ForceFlush(timeoutMilliseconds);
+        }
+
         /// <inheritdoc />
         protected override bool OnShutdown(int timeoutMilliseconds)
         {

src/OpenTelemetry/BaseExporter.cs

@@ -57,6 +57,38 @@ namespace OpenTelemetry
         /// <returns>Result of the export operation.</returns>
         public abstract ExportResult Export(in Batch<T> batch);
 
+        /// <summary>
+        /// Flushes the exporter, blocks the current thread until flush
+        /// completed, shutdown signaled or timed out.
+        /// </summary>
+        /// <param name="timeoutMilliseconds">
+        /// The number (non-negative) of milliseconds to wait, or
+        /// <c>Timeout.Infinite</c> to wait indefinitely.
+        /// </param>
+        /// <returns>
+        /// Returns <c>true</c> when flush succeeded; otherwise, <c>false</c>.
+        /// </returns>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// Thrown when the <c>timeoutMilliseconds</c> is smaller than -1.
+        /// </exception>
+        /// <remarks>
+        /// This function guarantees thread-safety.
+        /// </remarks>
+        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;
+            }
+        }
+
         /// <summary>
         /// Attempts to shutdown the exporter, blocks the current thread until
         /// shutdown completed or timed out.
@@ -102,6 +134,27 @@ namespace OpenTelemetry
             GC.SuppressFinalize(this);
         }
 
+        /// <summary>
+        /// Called by <c>ForceFlush</c>. This function should block the current
+        /// thread until flush completed, shutdown signaled or timed out.
+        /// </summary>
+        /// <param name="timeoutMilliseconds">
+        /// The number (non-negative) of milliseconds to wait, or
+        /// <c>Timeout.Infinite</c> to wait indefinitely.
+        /// </param>
+        /// <returns>
+        /// Returns <c>true</c> when flush succeeded; otherwise, <c>false</c>.
+        /// </returns>
+        /// <remarks>
+        /// This function is called synchronously on the thread which called
+        /// <c>ForceFlush</c>. This function should be thread-safe, and should
+        /// not throw exceptions.
+        /// </remarks>
+        protected virtual bool OnForceFlush(int timeoutMilliseconds)
+        {
+            return true;
+        }
+
         /// <summary>
         /// Called by <c>Shutdown</c>. This function should block the current
         /// thread until shutdown completed or timed out.

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