feat: Add Task support for BatchExportProcessor and PeriodicExportingMetricReader for single-threaded WebAssembly

[jeromelaban]

Fixes #2816
Design discussion issue: Partially based on #5778 and #5838

Changes

The change introduces updates to BatchExportProcessor and PeriodicExportingMetricReader in order to switch between Thread and Task implementations to support .NET's WebAssembly single threaded mode (used by Blazor, Uno Platform and others).

Based on #5838 (review), the threads mode is automatically enabled when multi-threading is available. Tasks are enabled when WebAssembly is detected, based on the ThreadingHelper class.

Note that there is no public API to change between thread and tasks.

Merge requirement checklist

• CONTRIBUTING guidelines followed (license requirements, nullable enabled, static analysis, etc.)
• Unit tests added/updated
• Appropriate CHANGELOG.md files updated for non-trivial changes
• Changes in public API reviewed (if applicable)

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jeromelaban / name: Jerome Laban (004ecd4, 01a6403, 0dab4cb, 178c2b5, 1c4e2f7, 1e5e3d9, 315c9ac, 4441038, 5bc225e, 6853a9b, 6eee22d, 769a418, 813032f, 85e58a8, a005155, a1189b9, a230a8a, a35a788, a46e7cd, ab55147, b67cd98, be871f9, d3b31af, e20d160, f1a131f, f768a62)
• ✅ login: rajkumar-rangaraj / name: Rajkumar Rangaraj (1eb4768, f8e1335)

[codecov]

Codecov Report

❌ Patch coverage is 71.82448% with 122 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.39%. Comparing base (ec00c87) to head (1eb4768).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...rc/OpenTelemetry/Internal/BatchExportTaskWorker.cs	37.86%	64 Missing ⚠️
...nternal/PeriodicExportingMetricReaderTaskWorker.cs	65.67%	23 Missing ⚠️
.../OpenTelemetry/Internal/BatchExportThreadWorker.cs	82.92%	14 Missing ⚠️
...ernal/PeriodicExportingMetricReaderThreadWorker.cs	75.47%	13 Missing ⚠️
src/OpenTelemetry/Internal/BatchExportWorker.cs	91.66%	3 Missing ⚠️
src/OpenTelemetry/BatchExportProcessor.cs	93.93%	2 Missing ⚠️
...ry/Internal/PeriodicExportingMetricReaderWorker.cs	88.23%	2 Missing ⚠️
...ry/Metrics/Reader/PeriodicExportingMetricReader.cs	96.29%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6379      +/-   ##
==========================================
- Coverage   88.90%   88.39%   -0.51%     
==========================================
  Files         263      270       +7     
  Lines       12424    12731     +307     
==========================================
+ Hits        11045    11253     +208     
- Misses       1379     1478      +99     

Flag	Coverage Δ
unittests-Project-Experimental	88.30% <71.82%> (-0.49%)	⬇️
unittests-Project-Stable	88.18% <71.82%> (-0.59%)	⬇️
unittests-Solution	88.33% <71.82%> (-0.42%)	⬇️
unittests-UnstableCoreLibraries-Experimental	41.38% <16.62%> (-1.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/OpenTelemetry/Internal/ThreadingHelper.cs	100.00% <100.00%> (ø)
...ry/Trace/Processor/BatchActivityExportProcessor.cs	100.00% <ø> (ø)
...ry/Metrics/Reader/PeriodicExportingMetricReader.cs	95.12% <96.29%> (+10.91%)	⬆️
src/OpenTelemetry/BatchExportProcessor.cs	94.82% <93.93%> (+10.56%)	⬆️
...ry/Internal/PeriodicExportingMetricReaderWorker.cs	88.23% <88.23%> (ø)
src/OpenTelemetry/Internal/BatchExportWorker.cs	91.66% <91.66%> (ø)
...ernal/PeriodicExportingMetricReaderThreadWorker.cs	75.47% <75.47%> (ø)
.../OpenTelemetry/Internal/BatchExportThreadWorker.cs	82.92% <82.92%> (ø)
...nternal/PeriodicExportingMetricReaderTaskWorker.cs	65.67% <65.67%> (ø)
...rc/OpenTelemetry/Internal/BatchExportTaskWorker.cs	37.86% <37.86%> (ø)

... and 1 file with indirect coverage changes

[jeromelaban]

To whoever approved the workflows run, thank you :)

I've made adjustments to avoid parameters reordering breaking changes which should get the build go further.

[jeromelaban]

The tests revealed a possible race condition in the disposing/shutdown ordering of the processor resulting in missing exports, for the task implementation.

[jeromelaban]

Fixed an additional race condition for slower machines where the exporter may not have fully started while being shut down, preventing it to still export what was in queue.

[jeromelaban]

Thanks for the run, again!

Looks like there's a reported test failure, but without any failed tests. Feels like a fluke, but it may be something known to this project. Would a rerun help? Thanks!

[jeromelaban]

Thanks @cijothomas, it helped :)

[Copilot]

Pull Request Overview

This PR adds optional Task support for BatchExportProcessor and PeriodicExportingMetricReader to enable OpenTelemetry to work in .NET's WebAssembly single-threaded mode (Blazor, Uno Platform, etc.). The implementation maintains backward compatibility by defaulting to the existing Thread-based approach while allowing configuration to use Task-based workers.

Key changes:

• Added new UseThreads parameter to control whether to use Thread or Task-based implementations
• Refactored existing code to use abstract worker classes with Thread and Task implementations
• WebAssembly runtime automatically uses Task-based workers when detected

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
BatchExportProcessor.cs	Refactored to use configurable worker pattern with Thread/Task implementations
PeriodicExportingMetricReader.cs	Added options-based constructor and worker abstraction
BatchExportProcessorOptions.cs	Added UseThreads property
PeriodicExportingMetricReaderOptions.cs	Added UseThreads property
BatchActivityExportProcessor.cs	Added options-based constructor overload
BatchLogRecordExportProcessor.cs	Added options-based constructor overload
Multiple worker classes	New abstract base classes and Thread/Task implementations
Test files	Updated tests to cover both Thread and Task scenarios

Comments suppressed due to low confidence (4)

test/OpenTelemetry.Tests/Logs/BatchLogRecordExportProcessorTests.cs:16

• Parameter name 'useThread' should be 'useThreads' to be consistent with the property name 'UseThreads' used throughout the codebase.

    public void StateValuesAndScopeBufferingTest(bool useThread)

test/OpenTelemetry.Tests/Logs/BatchLogRecordExportProcessorTests.cs:33

• Variable name 'useThread' should be 'useThreads' to match the property name and maintain consistency.

                UseThreads = useThread,

test/OpenTelemetry.Tests/Logs/BatchLogRecordExportProcessorTests.cs:165

• Parameter name 'useThread' should be 'useThreads' for consistency with the property name used throughout the codebase.

    public void DisposeWithoutShutdown(bool useThread)

test/OpenTelemetry.Tests/Logs/BatchLogRecordExportProcessorTests.cs:182

• Variable name 'useThread' should be 'useThreads' to match the property name and maintain consistency.

                UseThreads = useThread,

[jeromelaban]

Thanks for the reviews @martincostello!

[verdie-g]

This option means creating a dedicated thread, defeating the purpose of this implementation. Though, since ExporterProcAsync can yield the execution, the continuation will be schedule on the thread pool and the thread will probably die.

A simple Task.Run would be safer here.

[rajkumar-rangaraj]

TaskCreationOptions.LongRunning hints the scheduler to create a dedicated thread, which is exactly what this PR is trying to avoid on WebAssembly. As @verdie-g pointed out in the PR comments, a simple Task.Run(this.ExporterProcAsync) would be safer. On WASM where threads aren't available, LongRunning may either be ignored or throw.

[verdie-g]

Since the Task.Delay is used as a timeout mechanism, the delay result will be discarded most of the time since the other would already have completed. Yet, we let the timer fire every time here which can cause important contention (see dotnet/runtime#83890 (comment)). The fix would be to cancel the Task.Delay when it did not complete.

[rajkumar-rangaraj]

While combinedTokenSource exists, it only cancels on overall shutdown/timeout, not when dataExportedNotification completes. Each loop iteration leaks a live timer until it fires. This was also flagged by @verdie-g. The fix: cancel the CancellationTokenSource after WhenAny returns, or restructure to reuse a single timer.

Same issue exists in ExporterProcAsync:

await Task.WhenAny(
    this.exportTrigger.WaitAsync(cancellationToken),
    Task.Delay(this.ScheduledDelayMilliseconds, cancellationToken)).ConfigureAwait(false);

The Task.Delay is only cancelled on full shutdown (cancellationToken), not when the semaphore fires, so timers accumulate.