Merge pull request #247 from Vulthil/feature/messaging-observability

Messaging metrics (outbox + inbox) and a clear no-transport startup error

Author: Vulthil

docs/articles/inbox-pattern.md

@@ -84,6 +84,10 @@ builder.Services.AddRelationalInbox<AppDbContext>(o =>
 
 The sweep is registered only when `Retention.Enabled` is set. Choose `RetentionPeriod` comfortably longer than the broker's maximum redelivery delay — a marker removed while a duplicate could still arrive would let that duplicate through. The sweep runs through the registered `IIdempotencyStore` when it implements `IInboxRetentionStore` (the relational and Cosmos EF Core stores do); the relational store deletes set-based with `ExecuteDelete`.
 
+### Metrics
+
+The guard emits metrics on a `Meter` named `"Vulthil.Messaging.Inbox"` (`InboxTelemetry.MeterName`): the counters `vulthil.inbox.processed`, `vulthil.inbox.duplicate_skipped`, and `vulthil.inbox.missing_key`. `AddRelationalInbox`/`AddCosmosInbox` auto-register the meter when `EnableMetrics` is on (the default); for a hand-built `MeterProviderBuilder`, use `metrics.AddVulthilInboxInstrumentation()`.
+
 ### Relational store
 
 Expose the inbox set on your `DbContext`, apply the entity configuration, and register the store:

docs/articles/outbox-pattern.md

@@ -72,6 +72,8 @@ The relay emits an `ActivitySource` named `"Vulthil.SharedKernel.Outbox"` (expos
 
 `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)`.
 
+The relay also emits **metrics** on a `Meter` named `Telemetry.MeterName` (`"Vulthil.SharedKernel.Outbox"`): the counters `vulthil.outbox.relayed` and `vulthil.outbox.failed`. `AddOutboxEngine` auto-registers the meter with OpenTelemetry when `EnableMetrics` is on (the default); for a hand-built `MeterProviderBuilder`, use `metrics.AddVulthilOutboxInstrumentation()`.
+
 ## Retention
 
 Processed and dead-lettered rows remain in the `OutboxMessages` table after relay, so the table grows unbounded unless they are pruned. Opt into a retention sweep — a background service that periodically deletes terminal rows older than a window — by enabling `Retention` on the outbox options:

docs/articles/packages/vulthil-messaging-inbox.md

@@ -20,6 +20,7 @@ Persistence-agnostic: it defines the `IIdempotencyStore` contract and the filter
 - The store owns the transactional unit (the filter hands it the consumer invocation); the consumer keeps calling `SaveChanges` as usual
 - Deliveries with no resolvable key are rejected (`MissingIdempotencyKeyException`) unless you opt out
 - Prune markers with an opt-in background sweep — enable it on the store registration via `AddRelationalInbox<T>(o => o.Retention.Enabled = true)` (or `AddCosmosInbox<T>`)
+- Emits metrics (counters `vulthil.inbox.processed`/`duplicate_skipped`/`missing_key`) on a `Meter` (`InboxTelemetry.MeterName`), auto-registered by `AddRelationalInbox`/`AddCosmosInbox` when `EnableMetrics` is on (manual: `metrics.AddVulthilInboxInstrumentation()`)
 
 ## Usage
 

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

@@ -22,6 +22,8 @@ seam. It has **no EF Core dependency**; the EF implementation lives in
   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()`).
+- Relay metrics (counters `vulthil.outbox.relayed`/`vulthil.outbox.failed`) are emitted on a `Meter` (`Telemetry.MeterName`),
+  auto-registered by `AddOutboxEngine` when `EnableMetrics` is on (manual: `metrics.AddVulthilOutboxInstrumentation()`).
 - Opt into a retention sweep via `EnableOutboxProcessing(o => o.Retention.Enabled = true)` to periodically delete processed and dead-lettered rows
   older than a window (relational set-based `ExecuteDelete`; the same sweep covers Cosmos).
 

src/Vulthil.Messaging.Inbox.Cosmos/CosmosInboxExtensions.cs

@@ -34,6 +34,13 @@ public static IServiceCollection AddCosmosInbox<TContext>(
         services.TryAddScoped<IIdempotencyStore, CosmosIdempotencyStore<TContext>>();
         services.AddInboxRetention(configure);
 
+        var options = new InboxOptions();
+        configure?.Invoke(options);
+        if (options.EnableMetrics)
+        {
+            services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddVulthilInboxInstrumentation());
+        }
+
         return services;
     }
 }

src/Vulthil.Messaging.Inbox.Cosmos/Vulthil.Messaging.Inbox.Cosmos.csproj

@@ -11,6 +11,7 @@
 
 	<ItemGroup>
 	  <PackageReference Include="Microsoft.EntityFrameworkCore.Cosmos" />
+	  <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
 	</ItemGroup>
 
 </Project>

src/Vulthil.Messaging.Inbox.Relational/RelationalInboxExtensions.cs

@@ -34,6 +34,13 @@ public static IServiceCollection AddRelationalInbox<TContext>(
         services.TryAddScoped<IIdempotencyStore, RelationalIdempotencyStore<TContext>>();
         services.AddInboxRetention(configure);
 
+        var options = new InboxOptions();
+        configure?.Invoke(options);
+        if (options.EnableMetrics)
+        {
+            services.AddOpenTelemetry().WithMetrics(metrics => metrics.AddVulthilInboxInstrumentation());
+        }
+
         return services;
     }
 }

src/Vulthil.Messaging.Inbox.Relational/Vulthil.Messaging.Inbox.Relational.csproj

@@ -11,6 +11,7 @@
 
 	<ItemGroup>
 	  <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" />
+	  <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
 	</ItemGroup>
 
 </Project>

src/Vulthil.Messaging.Inbox/IdempotentConsumeFilter.cs

@@ -42,15 +42,21 @@ public async Task ConsumeAsync(IMessageContext<TMessage> context, ConsumeDelegat
             }
 
             InboxLog.MissingKeyAllowed(_logger, messageType);
+            InboxTelemetry.MissingKey.Add(1);
             await next(context);
             return;
         }
 
         var processed = await _store.ProcessAsync(key, context, _ => next(context), context.CancellationToken);
 
-        if (!processed)
+        if (processed)
+        {
+            InboxTelemetry.Processed.Add(1);
+        }
+        else
         {
             InboxLog.DuplicateSkipped(_logger, messageType, key);
+            InboxTelemetry.DuplicateSkipped.Add(1);
         }
     }
 }

src/Vulthil.Messaging.Inbox/InboxOptions.cs

@@ -13,6 +13,12 @@ public sealed class InboxOptions
     /// </summary>
     public bool RejectMessagesWithoutKey { get; set; } = true;
 
+    /// <summary>
+    /// Gets or sets a value indicating whether inbox metrics (the <c>vulthil.inbox.*</c> counters on the
+    /// <see cref="InboxTelemetry.MeterName"/> meter) are auto-registered with OpenTelemetry. Default: <see langword="true"/>.
+    /// </summary>
+    public bool EnableMetrics { get; set; } = true;
+
     /// <summary>
     /// Gets the retention sweep configuration. Set <see cref="InboxRetentionOptions.Enabled"/> to periodically
     /// delete idempotency markers older than <see cref="InboxRetentionOptions.RetentionPeriod"/>.