Merge pull request #235 from Vulthil/feature/outbox-telemetry-rename

Outbox telemetry: rename ActivitySource + auto-register when tracing is enabled

Author: Vulthil

docs/articles/outbox-pattern.md

@@ -66,6 +66,12 @@ public sealed class AppDbContext(DbContextOptions<AppDbContext> options)
 | `MaxDelaySeconds` | 60 | Maximum back-off delay when no messages are found |
 | `EnableTracing` | `true` | Carry the originating trace identifier when publishing |
 
+## Observability
+
+The relay emits an `ActivitySource` named `"Vulthil.SharedKernel.Outbox"` (exposed as `Telemetry.ActivitySourceName`). When `EnableTracing` is on (the default), each relayed message starts an `OutboxPublishing` span parented on the trace that captured the row — the originating trace is carried forward through the `OutboxMessage.TraceParent`/`TraceState` columns stamped at capture — so the relay, which runs later on its own background service, still correlates back to the request that produced the message.
+
+`AddOutboxEngine` (called by `EnableOutboxProcessing`) registers the source with OpenTelemetry automatically when `EnableTracing` is on (the default), so the spans reach whatever tracer the application has configured without extra wiring. If you build a `TracerProviderBuilder` yourself, the same registration is available as `tracing.AddVulthilOutboxInstrumentation()` — sugar for `AddSource(Telemetry.ActivitySourceName)`.
+
 ## Custom Outbox Store
 
 The relay engine talks to the database through an EF-free `IOutboxStore` (in `Vulthil.SharedKernel.Outbox`). The EF

docs/articles/packages/vulthil-sharedkernel-outbox.md

@@ -20,6 +20,8 @@ seam. It has **no EF Core dependency**; the EF implementation lives in
 - The engine relies on `IOutboxStore` for both capture (`AddOutboxMessage`/`SaveChangesAsync`/`IsInTransaction`) and
   the relay batch unit (`ProcessBatchAsync`); the EF implementation and provider stores supply the transaction and
   row-locking. `AddOutboxEngine` registers the engine's own internals.
+- Relay spans are emitted on the `ActivitySource` `"Vulthil.SharedKernel.Outbox"` (`Telemetry.ActivitySourceName`),
+  auto-registered with OpenTelemetry by `AddOutboxEngine` (manual: `tracing.AddVulthilOutboxInstrumentation()`).
 
 See the [Outbox Pattern](https://github.com/Vulthil/Vulthil.SharedKernel/tree/main/docs/articles/outbox-pattern.md)
 article for the design, the pluggable-sink model, and the commit-time trigger.

src/Vulthil.SharedKernel.Outbox/OutboxEngineServiceCollectionExtensions.cs

@@ -36,6 +36,13 @@ public static IServiceCollection AddOutboxEngine(
             .ValidateDataAnnotations()
             .ValidateOnStart();
 
+        if (IsTracingEnabled(configureOptions))
+        {
+            services
+                .AddOpenTelemetry()
+                .WithTracing(tracing => tracing.AddVulthilOutboxInstrumentation());
+        }
+
         services.TryAddSingleton(TimeProvider.System);
         services.TryAddSingleton<IOutboxSignal, OutboxSignal>();
 
@@ -46,4 +53,11 @@ public static IServiceCollection AddOutboxEngine(
 
         return services;
     }
+
+    private static bool IsTracingEnabled(Action<OutboxProcessingOptions>? configureOptions)
+    {
+        var options = new OutboxProcessingOptions();
+        configureOptions?.Invoke(options);
+        return options.EnableTracing;
+    }
 }

src/Vulthil.SharedKernel.Outbox/OutboxProcessingOptions.cs

@@ -41,12 +41,12 @@ public sealed class OutboxProcessingOptions
     public int MaxDegreeOfParallelism { get; init; } = 4;
 
     /// <summary>
-    /// Gets a value indicating whether Trace Identifiers should be included when publishing outbox messages.
+    /// Gets or sets a value indicating whether Trace Identifiers should be included when publishing outbox messages.
     /// <br />
     /// This allows the originating action that persisted the outbox message to act as an owner for the resulting scope,
     /// even after the outbox delay
     /// <br/>
     /// Default: <see langword="true"/>
     /// </summary>
-    public bool EnableTracing { get; init; } = true;
+    public bool EnableTracing { get; set; } = true;
 }

src/Vulthil.SharedKernel.Outbox/OutboxProcessor.cs

@@ -68,7 +68,7 @@ public static class Telemetry
     /// <summary>
     /// ActivitySourceName for all outbox processing operations, allowing correlation of events across the capture, processing, and publishing stages.
     /// </summary>
-    public static readonly string ActivitySourceName = "Vulthil.SharedKernel.Infrastructure";
+    public static readonly string ActivitySourceName = "Vulthil.SharedKernel.Outbox";
     /// <summary>
     /// ActivitySource for all outbox processing operations, allowing correlation of events across the capture, processing, and publishing stages.
     /// </summary>

src/Vulthil.SharedKernel.Outbox/PublicAPI.Unshipped.txt

@@ -7,6 +7,7 @@ static Vulthil.SharedKernel.Outbox.OutboxMessageData.operator !=(Vulthil.SharedK
 static Vulthil.SharedKernel.Outbox.OutboxMessageData.operator ==(Vulthil.SharedKernel.Outbox.OutboxMessageData left, Vulthil.SharedKernel.Outbox.OutboxMessageData right) -> bool
 static Vulthil.SharedKernel.Outbox.OutboxMessageFailure.operator !=(Vulthil.SharedKernel.Outbox.OutboxMessageFailure left, Vulthil.SharedKernel.Outbox.OutboxMessageFailure right) -> bool
 static Vulthil.SharedKernel.Outbox.OutboxMessageFailure.operator ==(Vulthil.SharedKernel.Outbox.OutboxMessageFailure left, Vulthil.SharedKernel.Outbox.OutboxMessageFailure right) -> bool
+static Vulthil.SharedKernel.Outbox.TracerProviderBuilderExtensions.AddVulthilOutboxInstrumentation(this OpenTelemetry.Trace.TracerProviderBuilder! builder) -> OpenTelemetry.Trace.TracerProviderBuilder!
 Vulthil.SharedKernel.Outbox.IOutboxDispatcher
 Vulthil.SharedKernel.Outbox.IOutboxDispatcher.DispatchAsync(Vulthil.SharedKernel.Outbox.OutboxMessageData message, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.Task!
 Vulthil.SharedKernel.Outbox.IOutboxDispatcher.Handles(Vulthil.SharedKernel.Outbox.OutboxDestination destination) -> bool
@@ -87,7 +88,7 @@ Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.BatchSize.init -> void
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.EnableParallelPublishing.get -> bool
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.EnableParallelPublishing.init -> void
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.EnableTracing.get -> bool
-Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.EnableTracing.init -> void
+Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.EnableTracing.set -> void
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.MaxDegreeOfParallelism.get -> int
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.MaxDegreeOfParallelism.init -> void
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.MaxDelaySeconds.get -> int
@@ -98,6 +99,7 @@ Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.OutboxProcessingDelayInSecon
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.OutboxProcessingDelayInSeconds.init -> void
 Vulthil.SharedKernel.Outbox.OutboxProcessingOptions.OutboxProcessingOptions() -> void
 Vulthil.SharedKernel.Outbox.Telemetry
+Vulthil.SharedKernel.Outbox.TracerProviderBuilderExtensions
 ~override Vulthil.SharedKernel.Outbox.OutboxMessageData.Equals(object obj) -> bool
 ~override Vulthil.SharedKernel.Outbox.OutboxMessageData.ToString() -> string
 ~override Vulthil.SharedKernel.Outbox.OutboxMessageFailure.Equals(object obj) -> bool

src/Vulthil.SharedKernel.Outbox/TracerProviderBuilderExtensions.cs

@@ -0,0 +1,21 @@
+using OpenTelemetry.Trace;
+
+namespace Vulthil.SharedKernel.Outbox;
+
+/// <summary>
+/// OpenTelemetry registration helpers for the Vulthil outbox processing telemetry.
+/// </summary>
+public static class TracerProviderBuilderExtensions
+{
+    /// <summary>
+    /// Subscribes the tracer provider to the <see cref="System.Diagnostics.ActivitySource"/> emitted by the outbox
+    /// relay (the <c>OutboxPublishing</c> spans), so outbox processing is collected without hard-coding the source name.
+    /// </summary>
+    /// <param name="builder">The tracer provider builder.</param>
+    /// <returns>The same builder, for chaining.</returns>
+    public static TracerProviderBuilder AddVulthilOutboxInstrumentation(this TracerProviderBuilder builder)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        return builder.AddSource(Telemetry.ActivitySourceName);
+    }
+}

src/Vulthil.SharedKernel.Outbox/Vulthil.SharedKernel.Outbox.csproj

@@ -7,6 +7,8 @@
 	<ItemGroup>
 		<PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
 		<PackageReference Include="Microsoft.Extensions.Options.DataAnnotations" />
+		<PackageReference Include="OpenTelemetry.Api" />
+		<PackageReference Include="OpenTelemetry.Extensions.Hosting" />
 	</ItemGroup>
 
 	<ItemGroup>