feat: TUnit.OpenTelemetry zero-config tracing package

[thomhurst]

Summary

• New TUnit.OpenTelemetry NuGet package auto-wires a TracerProvider at [Before(TestDiscovery)] and disposes at [After(TestSession)]. Install the package + set OTEL_EXPORTER_OTLP_ENDPOINT — zero boilerplate required.
• Includes TUnitTestCorrelationProcessor (resolves Ship opt-in OpenTelemetry ActivityProcessor that tags spans with tunit.test.id #5591's tag-propagation workaround) so spans from broken-parent-chain libraries still carry tunit.test.id.
• TUnit.Aspire refactored to delegate provider construction via TUnitOpenTelemetry.Configure, removing its own TracerProvider singleton.
• Coexists cleanly with hand-rolled setups: [Before(TestDiscovery, Order = int.MaxValue)] runs last, probes ActivitySource("TUnit").HasListeners(), and steps aside if a listener is already attached. TUNIT_OTEL_AUTOSTART=0 opts out; =1 force-enables.

Resolves #5593. Bundles fix for #5591.

Architecture notes

• Public surface: TUnitOpenTelemetry.Configure(Action<TracerProviderBuilder>), AutoStart (hooks + AutoStartOrder const), TUnitTestCorrelationProcessor.
• Gate logic: if TUNIT_OTEL_AUTOSTART != "1" and OTEL_EXPORTER_OTLP_ENDPOINT is unset and no user Configure callbacks are registered, the package stays dormant (no provider built, no listener attached).
• Default service.name resource: OTEL_SERVICE_NAME > entry assembly name > "TUnit.Tests".
• builder.Build() and user callbacks execute outside the AutoStart lock to avoid holding a static lock across SDK initialization.
• OTLP exporter is hard-dep'd so the zero-config path doesn't require a second dotnet add package.

Docs

• docs/docs/examples/opentelemetry.md gains Option A: Zero-config; existing manual setup demoted to Option B / Option C.
• docs/docs/guides/distributed-tracing.md gains a zero-config callout pointing to the new option.
• Manual TUnitTagProcessor snippet in troubleshooting now points at the pre-registered package processor.

Test plan

• dotnet build TUnit.slnx -c Release — 0 errors
• TUnit.OpenTelemetry.Tests — 13/13 pass (Configure, AutoStart coexistence, opt-out env var, correlation processor baggage-to-tag, default service.name, end-to-end InMemory exporter smoke test)
• TUnit.Aspire.Tests — 101/101 pass (no regression from the refactor)
• TUnit.PublicAPI — new OpenTelemetry snapshot tests pass across net8/net9/net10
• TUnit.Engine.Tests hook filter — 17 pass, 16 skip, 0 fail (no regression from the new Order = int.MaxValue hook)
• dotnet pack TUnit.OpenTelemetry produces a valid nupkg
• docs && npm run build — clean build, no broken links
• Manual: end-to-end trace verification against a local Jaeger/Tempo instance with OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Pipeline

• TUnit.Pipeline/Modules/GetPackageProjectsModule.cs adds the new package to the pack/publish list.
• New RunOpenTelemetryTestsModule mirrors the Aspire test module (no OS gate — nothing platform-specific).
• All three slnx files (TUnit.slnx, TUnit.Dev.slnx, TUnit.CI.slnx) updated.

Plan

Full implementation plan: docs/plans/2026-04-17-tunit-opentelemetry-package.md (14 tasks, each committed separately).

[claude]

Code Review: feat: TUnit.OpenTelemetry zero-config tracing package

Overall this is a well-conceived feature. The architecture cleanly separates lifecycle hooks (AutoStart), user configuration (TUnitOpenTelemetry), and span correlation (TUnitTestCorrelationProcessor). The refactor of TUnit.Aspire to delegate to TUnitOpenTelemetry.Configure rather than owning its own singleton is the right call — single owner, multiple contributors.

---

Issue 1 (Architecture) — Hard-coded TUnit.AspNetCore.Http source in AutoStart

AutoStart.cs subscribes to TUnit.AspNetCore.Http by default:

.AddSource("TUnit")
.AddSource("TUnit.Lifecycle")
.AddSource("TUnit.AspNetCore.Http")   // ← cross-package coupling

This couples TUnit.OpenTelemetry to TUnit.AspNetCore's internal source name. If more integration packages ship their own activity sources (database, message bus, etc.), AutoStart becomes a growing list of magic strings it shouldn't know about.

Better approach: a registration mechanism that lets each package self-describe:

// TUnit.OpenTelemetry public API
public static class TUnitOpenTelemetry
{
    public static void RegisterActivitySource(string sourceName) { ... }
}

// In TUnit.AspNetCore (its own static init or [Before(TestDiscovery)] hook):
TUnitOpenTelemetry.RegisterActivitySource("TUnit.AspNetCore.Http");

AutoStart then calls .AddSource() for every registered name. Each package owns its own registration rather than the core package accumulating knowledge of all integrations.

---

Issue 2 (Correctness) — TOCTOU gap between the listener check and the provider lock

In AutoStart.Start() the HasListeners() probe and the _provider lock are two separate critical sections with a gap between them:

// Check outside any lock — another thread could add a listener here
if (ProbeSource.HasListeners())
    return;

// Separate lock — doesn't cover the check above
lock (_lock)
{
    if (_provider is not null)
        return;
}

// Build happens here, after both locks released
var provider = builder.Build();

Two concurrent callers can both pass the HasListeners() guard. The second lock-then-set handles the double-build correctly (the loser disposes its provider), so data integrity is preserved. But the HasListeners() check is still semantically racy — a user listener attached between the check and Build() won't be detected.

The comment in the PR description ("builder.Build() and user callbacks execute outside the AutoStart lock to avoid holding a static lock across SDK initialization") is the right rationale for not locking around Build. An alternative that avoids the race without holding a long lock:

// Inside the lock, snapshot the decision
bool shouldBuild;
lock (_lock)
{
    shouldBuild = _provider is null && !ProbeSource.HasListeners() && (force || ...);
}
if (!shouldBuild) return;

// Build outside lock (long operation)
var provider = builder.Build();

// Set under lock, dispose if we lost the race
lock (_lock)
{
    if (_provider is not null) { provider.Dispose(); return; }
    _provider = provider;
}

The lock is still not held during Build, but the listener check is now inside the first lock, eliminating the TOCTOU gap.

---

Issue 3 (Minor) — Spurious null-conditional on a non-nullable local

After builder.Build() returns, the local is known non-null. The null-conditional on the disposal is misleading:

var provider = builder.Build();   // non-null
// ...
provider?.Dispose();               // the ?. implies it could be null — it can't

This should just be provider.Dispose() to signal intent clearly. If Build() can throw mid-way and leave provider in an uncertain state, wrap it in a try/finally instead.

---

Issue 4 (Minor) — CreateTracerProvider stranded in production code for test use only

TestTraceExporter.CreateTracerProvider is documented as "used by test-only code paths" but lives in production code:

/// Used by test-only code paths that need an owned provider; production uses AddToBuilder.
internal static TracerProvider CreateTracerProvider(...)

This leaks a test concern into the library. TUnit.Aspire.Tests should build the provider directly using Sdk.CreateTracerProviderBuilder() + AddToBuilder(...) rather than relying on a convenience wrapper in the library under test. That would allow the library to drop the method entirely.

---

What's working well

• Double-checked locking for the provider itself is correctly implemented — the race-to-build is detected and the loser disposes cleanly.
• TUnitTestCorrelationProcessor is simple and correct. The early-return on existing tunit.test.id tag avoids redundant work.
• The Aspire refactor (RegisterAspireExporter delegating via Configure) is architecturally sound — single provider owner, multiple contributors.
• Test isolation via [NotInParallel("TUnitOpenTelemetryGlobalState")] with proper finally cleanup is well-structured.
• Environment variable design (TUNIT_OTEL_AUTOSTART, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME) follows OTel conventions and is clearly documented.
• Public API snapshots committed across net8/net9/net10 and the pipeline module for CI are all present.

The hard-coded source name (Issue 1) is the most significant architectural concern as it sets a precedent that doesn't scale as the integration ecosystem grows. Issues 2–4 are lower priority but worth addressing before the package ships publicly.

[codacy-production]

Not up to standards ⛔

🔴 Issues 1 minor

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category	Results
Comprehensibility	1 minor

View in Codacy

🟢 Metrics 32 complexity

Metric	Results
Complexity	32

View in Codacy

_{TIP This summary will be updated as you push new changes. Give us feedback}

[thomhurst]

Thanks for the review. Addressed issues 2–4 in 532a583; pushing back on issue 1 with rationale below.

Issue 2 (TOCTOU) — moved the HasListeners/endpoint/HasConfiguration checks inside the existing _lock block so they sit adjacent to the _provider is null guard. Build() still runs outside the lock; the post-Build re-check disposes the loser on a race. The race the reviewer flagged (listener attached between check and Build completion) is narrowed but not eliminated — holding the lock across Build() would serialize SDK init, which the original design intentionally avoids.

Issue 3 (null-conditional) — provider?.Dispose() → provider.Dispose() after Build(). Build() throwing is propagated out of Start (no half-initialized provider to leak).

Issue 4 (test wrapper in production) — TestTraceExporter.CreateTracerProvider deleted. The sole consumer, CreateTracerProvider_ExportsTracesForRegisteredSource, was a near-duplicate of AddToBuilder_ExportsTracesForRegisteredSource — kept the latter since it exercises the production wiring path directly.

Issue 1 (hard-coded TUnit.AspNetCore.Http source) — not acting on this. The proposed fix (self-registration via TUnitOpenTelemetry.RegisterActivitySource(...) from TUnit.AspNetCore) would force TUnit.AspNetCore to take a dep on TUnit.OpenTelemetry, which the implementation plan explicitly rules out:

TUnit.AspNetCore not modified — it must remain OTel-agnostic.

The three default sources are an intentional "known TUnit sources" list, not an extensibility hook. Users who want to add or swap sources can already do so via TUnitOpenTelemetry.Configure(b => b.AddSource("...")). If the list grows past ~3–4 entries or a third-party package wants its own auto-wired source, the self-registration pattern is a sensible follow-up — just not worth the API surface expansion for one current integration.

Rerun results:

• TUnit.OpenTelemetry.Tests — 13/13
• TUnit.Aspire.Tests — 100/100 (was 101; CreateTracerProvider_* removed)
• TUnit.PublicAPI OpenTelemetry snapshots — pass across net8/net9/net10

[claude]

Follow-up Review — addressing previous comments

The author pushed a follow-up commit (532a583a7529) that addressed three of the four issues from the previous review. Here's the updated status:

---

✅ Issue 2 (TOCTOU) — Addressed

HasListeners() is now checked inside the first lock (_lock) block in AutoStart.Start(), eliminating the race window between the listener probe and the provider guard. The double-build race (loser disposes its provider) is still correctly handled in the second lock. Well done.

✅ Issue 3 (Null-conditional) — Addressed

provider.Dispose() replaces provider?.Dispose() — the intent is now clear and the spurious nullable hint is gone.

✅ Issue 4 (Test-only wrapper) — Addressed

TestTraceExporter.CreateTracerProvider has been removed. TUnit.Aspire.Tests now builds the provider directly via Sdk.CreateTracerProviderBuilder() + AddToBuilder(...), keeping production code free of test-only conveniences. The AddToBuilder_ExportsTracesForRegisteredSource test is cleaner for it.

---

⚠️ Issue 1 (Hard-coded cross-package source) — Still outstanding

AutoStart.cs still hard-codes TUnit.AspNetCore.Http:

var builder = Sdk.CreateTracerProviderBuilder()
    .AddSource("TUnit")
    .AddSource("TUnit.Lifecycle")
    .AddSource("TUnit.AspNetCore.Http")   // ← coupling to a sibling package's internals
    .AddProcessor(new TUnitTestCorrelationProcessor());

This is the only remaining architectural concern from the first review. As the integration package ecosystem grows (ASP.NET Core, database, messaging, etc.), AutoStart becomes an ever-growing list of magic strings it shouldn't need to know about. A registration hook in TUnitOpenTelemetry would let each package self-describe:

// Public API addition to TUnit.OpenTelemetry
public static void RegisterActivitySource(string sourceName) { ... }

// In TUnit.AspNetCore (its own [Before(TestDiscovery)] or static initializer):
TUnitOpenTelemetry.RegisterActivitySource("TUnit.AspNetCore.Http");

AutoStart then calls .AddSource() for every registered name. This is a judgment call for the author — shipping with the fixed list is acceptable for v1 if there's a plan to add self-registration later, but it's worth noting the pattern now before more sources get added.

---

Summary

Three of four issues addressed; the follow-up commit was exactly the right scope. The remaining item (Issue 1) is an architectural preference rather than a correctness bug. Code quality is good and the PR is mergeable as-is if the author accepts the coupling trade-off.