+semver:minor - feat: add Activity tracing for OpenTelemetry support (thomhurst#4844)

* feat: add System.Diagnostics.Activity tracing for OpenTelemetry-compatible instrumentation

Add first-party trace spans at every level of the test lifecycle (session,
assembly, class, test) using System.Diagnostics.ActivitySource. Users get
OpenTelemetry-compatible tracing automatically when they configure an exporter.
Zero cost when no listener is attached.

- Add TUnitActivitySource singleton with StartActivity/RecordException/StopActivity helpers
- Add Activity property to Context base class (inherited by all context types)
- Start/stop session, assembly, class spans in HookExecutor
- Start/stop test spans in TestExecutor with result/skip/retry tags
- Stop failed attempt Activity on retry in RetryHelper
- All Activity code behind #if NET (ActivitySource requires .NET 5+)
- Explicit ActivityContext parenting for parallel safety

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: align activity tracing with OpenTelemetry semantic conventions

- Span names: use verb+object pattern (test session, test assembly, test suite, test case)
- Use OTel test.* namespace: test.case.name, test.case.result.status, test.suite.name
- Result values: lowercase per OTel (pass/fail/skipped instead of Passed/Failed/Skipped)
- Status codes: leave Unset on success (not Ok) per instrumentation library conventions
- Add error.type tag alongside exception events per OTel recording-errors spec
- Categories: pass as string[] array instead of comma-joined string
- Remove redundant HasListeners() guard (StartActivity returns null natively)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add OpenTelemetry tracing integration guide

Covers ActivitySource subscription, span hierarchy, attribute reference
tables, status conventions, retry behavior, and exporter setup examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* perf: guard StartActivity call sites with HasListeners() check

Wrap all 4 StartActivity call sites with TUnitActivitySource.Source.HasListeners()
so that tag collection expressions, string.Join, and ToArray allocations are
never evaluated when no listener is attached. This ensures true zero-cost
when tracing is disabled, per CLAUDE.md Rule 4 (Performance First).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: thomhurst

TUnit.Core/Context.cs

@@ -58,6 +58,7 @@ internal Context(Context? parent)
     }
 
 #if NET
+    internal System.Diagnostics.Activity? Activity { get; set; }
     internal ExecutionContext? ExecutionContext { get; private set; }
 #endif
 
@@ -133,6 +134,8 @@ public DefaultLogger GetDefaultLogger()
     public void Dispose()
     {
 #if NET
+        TUnitActivitySource.StopActivity(Activity);
+        Activity = null;
         ExecutionContext?.Dispose();
 #endif
         _outputLock?.Dispose();

TUnit.Core/TUnitActivitySource.cs

@@ -0,0 +1,56 @@
+#if NET
+
+using System.Diagnostics;
+
+namespace TUnit.Core;
+
+internal static class TUnitActivitySource
+{
+    private static readonly string Version =
+        typeof(TUnitActivitySource).Assembly.GetName().Version?.ToString() ?? "0.0.0";
+
+    internal static readonly ActivitySource Source = new("TUnit", Version);
+
+    internal static Activity? StartActivity(
+        string name,
+        ActivityKind kind = ActivityKind.Internal,
+        ActivityContext parentContext = default,
+        IEnumerable<KeyValuePair<string, object?>>? tags = null)
+    {
+        // StartActivity returns null when no listener is sampling this source,
+        // so the HasListeners() check is implicit. We rely on the framework behavior.
+        return Source.StartActivity(name, kind, parentContext, tags);
+    }
+
+    internal static void RecordException(Activity? activity, Exception exception)
+    {
+        if (activity is null)
+        {
+            return;
+        }
+
+        var tagsCollection = new ActivityTagsCollection
+        {
+            { "exception.type", exception.GetType().FullName },
+            { "exception.message", exception.Message },
+            { "exception.stacktrace", exception.ToString() }
+        };
+
+        activity.AddEvent(new ActivityEvent("exception", tags: tagsCollection));
+        activity.SetTag("error.type", exception.GetType().FullName);
+        activity.SetStatus(ActivityStatusCode.Error, exception.Message);
+    }
+
+    internal static void StopActivity(Activity? activity)
+    {
+        if (activity is null)
+        {
+            return;
+        }
+
+        activity.Stop();
+        activity.Dispose();
+    }
+}
+
+#endif

TUnit.Engine/Services/HookExecutor.cs

@@ -31,6 +31,22 @@ public HookExecutor(
 
     public async ValueTask ExecuteBeforeTestSessionHooksAsync(CancellationToken cancellationToken)
     {
+        var sessionContext = _contextProvider.TestSessionContext;
+
+#if NET
+        if (TUnitActivitySource.Source.HasListeners())
+        {
+            sessionContext.Activity = TUnitActivitySource.StartActivity(
+                "test session",
+                System.Diagnostics.ActivityKind.Internal,
+                default,
+                [
+                    new("tunit.session.id", sessionContext.Id),
+                    new("tunit.filter", sessionContext.TestFilter)
+                ]);
+        }
+#endif
+
         var hooks = await _hookCollectionService.CollectBeforeTestSessionHooksAsync().ConfigureAwait(false);
 
         if (hooks.Count == 0)
@@ -68,6 +84,9 @@ public async ValueTask<List<Exception>> ExecuteAfterTestSessionHooksAsync(Cancel
 
         if (hooks.Count == 0)
         {
+#if NET
+            FinishSessionActivity(hasErrors: false);
+#endif
             return [];
         }
 
@@ -90,11 +109,54 @@ public async ValueTask<List<Exception>> ExecuteAfterTestSessionHooksAsync(Cancel
             }
         }
 
+#if NET
+        FinishSessionActivity(hasErrors: exceptions is { Count: > 0 });
+#endif
+
         return exceptions ?? [];
     }
 
+#if NET
+    private void FinishSessionActivity(bool hasErrors)
+    {
+        var sessionContext = _contextProvider.TestSessionContext;
+        var activity = sessionContext.Activity;
+
+        if (activity is null)
+        {
+            return;
+        }
+
+        activity.SetTag("tunit.test.count", sessionContext.AllTests.Count);
+
+        if (hasErrors)
+        {
+            activity.SetStatus(System.Diagnostics.ActivityStatusCode.Error);
+        }
+
+        TUnitActivitySource.StopActivity(activity);
+        sessionContext.Activity = null;
+    }
+#endif
+
     public async ValueTask ExecuteBeforeAssemblyHooksAsync(Assembly assembly, CancellationToken cancellationToken)
     {
+        var assemblyContext = _contextProvider.GetOrCreateAssemblyContext(assembly);
+
+#if NET
+        if (TUnitActivitySource.Source.HasListeners())
+        {
+            var sessionActivity = _contextProvider.TestSessionContext.Activity;
+            assemblyContext.Activity = TUnitActivitySource.StartActivity(
+                "test assembly",
+                System.Diagnostics.ActivityKind.Internal,
+                sessionActivity?.Context ?? default,
+                [
+                    new("tunit.assembly.name", assembly.GetName().Name)
+                ]);
+        }
+#endif
+
         var hooks = await _hookCollectionService.CollectBeforeAssemblyHooksAsync(assembly).ConfigureAwait(false);
 
         if (hooks.Count == 0)
@@ -133,6 +195,9 @@ public async ValueTask<List<Exception>> ExecuteAfterAssemblyHooksAsync(Assembly
 
         if (hooks.Count == 0)
         {
+#if NET
+            FinishAssemblyActivity(assembly, hasErrors: false);
+#endif
             return [];
         }
 
@@ -156,13 +221,57 @@ public async ValueTask<List<Exception>> ExecuteAfterAssemblyHooksAsync(Assembly
             }
         }
 
+#if NET
+        FinishAssemblyActivity(assembly, hasErrors: exceptions is { Count: > 0 });
+#endif
+
         return exceptions ?? [];
     }
 
+#if NET
+    private void FinishAssemblyActivity(Assembly assembly, bool hasErrors)
+    {
+        var assemblyContext = _contextProvider.GetOrCreateAssemblyContext(assembly);
+        var activity = assemblyContext.Activity;
+
+        if (activity is null)
+        {
+            return;
+        }
+
+        activity.SetTag("tunit.test.count", assemblyContext.TestCount);
+
+        if (hasErrors)
+        {
+            activity.SetStatus(System.Diagnostics.ActivityStatusCode.Error);
+        }
+
+        TUnitActivitySource.StopActivity(activity);
+        assemblyContext.Activity = null;
+    }
+#endif
+
     public async ValueTask ExecuteBeforeClassHooksAsync(
         [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.PublicMethods)]
         Type testClass, CancellationToken cancellationToken)
     {
+        var classContext = _contextProvider.GetOrCreateClassContext(testClass);
+
+#if NET
+        if (TUnitActivitySource.Source.HasListeners())
+        {
+            var assemblyActivity = classContext.AssemblyContext.Activity;
+            classContext.Activity = TUnitActivitySource.StartActivity(
+                "test suite",
+                System.Diagnostics.ActivityKind.Internal,
+                assemblyActivity?.Context ?? default,
+                [
+                    new("test.suite.name", testClass.Name),
+                    new("tunit.class.namespace", testClass.Namespace)
+                ]);
+        }
+#endif
+
         var hooks = await _hookCollectionService.CollectBeforeClassHooksAsync(testClass).ConfigureAwait(false);
 
         if (hooks.Count == 0)
@@ -203,6 +312,9 @@ public async ValueTask<List<Exception>> ExecuteAfterClassHooksAsync(
 
         if (hooks.Count == 0)
         {
+#if NET
+            FinishClassActivity(testClass, hasErrors: false);
+#endif
             return [];
         }
 
@@ -226,9 +338,38 @@ public async ValueTask<List<Exception>> ExecuteAfterClassHooksAsync(
             }
         }
 
+#if NET
+        FinishClassActivity(testClass, hasErrors: exceptions is { Count: > 0 });
+#endif
+
         return exceptions ?? [];
     }
 
+#if NET
+    private void FinishClassActivity(
+        [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.PublicProperties | DynamicallyAccessedMemberTypes.PublicMethods)]
+        Type testClass, bool hasErrors)
+    {
+        var classContext = _contextProvider.GetOrCreateClassContext(testClass);
+        var activity = classContext.Activity;
+
+        if (activity is null)
+        {
+            return;
+        }
+
+        activity.SetTag("tunit.test.count", classContext.TestCount);
+
+        if (hasErrors)
+        {
+            activity.SetStatus(System.Diagnostics.ActivityStatusCode.Error);
+        }
+
+        TUnitActivitySource.StopActivity(activity);
+        classContext.Activity = null;
+    }
+#endif
+
     public async ValueTask ExecuteBeforeTestHooksAsync(AbstractExecutableTest test, CancellationToken cancellationToken)
     {
         var testClassType = test.Metadata.TestClassType;

TUnit.Engine/Services/TestExecution/RetryHelper.cs

@@ -26,6 +26,19 @@ public static async Task ExecuteWithRetry(TestContext testContext, Func<Task> ac
 
                 if (await ShouldRetry(testContext, ex, attempt))
                 {
+#if NET
+                    // Stop the failed attempt's activity before retrying
+                    var activity = testContext.Activity;
+                    if (activity is not null)
+                    {
+                        activity.SetTag("test.case.result.status", "fail");
+                        activity.SetTag("tunit.test.retry_attempt", attempt);
+                        TUnitActivitySource.RecordException(activity, ex);
+                        TUnitActivitySource.StopActivity(activity);
+                        testContext.Activity = null;
+                    }
+#endif
+
                     // Clear the previous result before retrying
                     testContext.Execution.Result = null;
                     testContext.TestStart = null;

TUnit.Engine/TestExecutor.cs

@@ -8,6 +8,9 @@
 using TUnit.Core.Services;
 using TUnit.Engine.Helpers;
 using TUnit.Engine.Services;
+#if NET
+using System.Diagnostics;
+#endif
 
 namespace TUnit.Engine;
 
@@ -113,6 +116,25 @@ await _eventReceiverOrchestrator.InvokeFirstTestInClassEventReceiversAsync(
 
             executableTest.Context.ClassContext.RestoreExecutionContext();
 
+#if NET
+            if (TUnitActivitySource.Source.HasListeners())
+            {
+                var classActivity = executableTest.Context.ClassContext.Activity;
+                var testDetails = executableTest.Context.Metadata.TestDetails;
+                executableTest.Context.Activity = TUnitActivitySource.StartActivity(
+                    "test case",
+                    ActivityKind.Internal,
+                    classActivity?.Context ?? default,
+                    [
+                        new("test.case.name", testDetails.TestName),
+                        new("tunit.test.class", testDetails.ClassType.FullName),
+                        new("tunit.test.method", testDetails.MethodName),
+                        new("tunit.test.id", executableTest.Context.Id),
+                        new("tunit.test.categories", testDetails.Categories.ToArray())
+                    ]);
+            }
+#endif
+
             // Initialize test objects (IAsyncInitializer) AFTER BeforeClass hooks
             // This ensures resources like Docker containers are not started until needed
             await testInitializer.InitializeTestObjectsAsync(executableTest, cancellationToken).ConfigureAwait(false);
@@ -189,6 +211,10 @@ await Timings.Record("AfterTest", executableTest.Context, (Func<Task>)(async ()
             {
                 hookException = new TestExecutionException(null, hookExceptions, eventReceiverExceptions);
             }
+
+#if NET
+            FinishTestActivity(executableTest, capturedException);
+#endif
         }
 
         if (capturedException is SkipTestException)
@@ -216,6 +242,50 @@ await Timings.Record("AfterTest", executableTest.Context, (Func<Task>)(async ()
         }
     }
 
+#if NET
+    private static void FinishTestActivity(AbstractExecutableTest executableTest, Exception? capturedException)
+    {
+        var activity = executableTest.Context.Activity;
+
+        if (activity is null)
+        {
+            return;
+        }
+
+        var result = executableTest.Context.Execution.Result;
+
+        // Use OTel test semantic convention values: pass, fail, skipped
+        var statusValue = result?.State switch
+        {
+            TestState.Passed => "pass",
+            TestState.Failed => "fail",
+            TestState.Skipped => "skipped",
+            _ => "unknown"
+        };
+        activity.SetTag("test.case.result.status", statusValue);
+
+        if (executableTest.Context.CurrentRetryAttempt > 0)
+        {
+            activity.SetTag("tunit.test.retry_attempt", executableTest.Context.CurrentRetryAttempt);
+        }
+
+        if (capturedException is SkipTestException skipEx)
+        {
+            // Skipped tests are not errors — leave status as Unset
+            activity.SetTag("tunit.test.skip_reason", skipEx.Reason);
+        }
+        else if (capturedException is not null)
+        {
+            // RecordException sets Error status and error.type tag
+            TUnitActivitySource.RecordException(activity, capturedException);
+        }
+        // Success: leave status as Unset per OTel instrumentation library conventions
+
+        TUnitActivitySource.StopActivity(activity);
+        executableTest.Context.Activity = null;
+    }
+#endif
+
     private static async ValueTask ExecuteTestAsync(AbstractExecutableTest executableTest, CancellationToken cancellationToken)
     {
         // Skip the actual test invocation for skipped tests