Merge branch 'main' into chore/provide-new-az-msg-handler-interface

Author: stijnmoreels

docs/preview/02-getting-started.md

@@ -80,4 +80,4 @@ Host.CreateDefaultBuilder()
 
 The way *'message handlers'* are registered determines when the received message will be routed to them.
 
-> 🔗 See the [Azure Service Bus messaging feature documentation](./03-Features/01-Azure/01-service-bus.md) for more information on providing additional routing filters to your message handlers.
+> 🔗 See the [Azure Service Bus messaging feature documentation](./03-Features/01-Azure/01-service-bus.mdx) for more information on providing additional routing filters to your message handlers.

docs/preview/03-Features/01-Azure/01-service-bus.md renamed to docs/preview/03-Features/01-Azure/01-service-bus.mdx

@@ -2,6 +2,9 @@
 sidebar_label: Service Bus
 ---
 
+import Tabs from '@theme/Tabs'; 
+import TabItem from '@theme/TabItem';
+
 # Azure Service Bus messaging
 The `Arcus.Messaging.Pumps.ServiceBus` library provides a way to process Azure Service Bus messages on queues/topic subscriptions via custom routed *message handlers*, instead of interacting with the [`ServiceBusReceiver`](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.servicebus.servicebusreceiver) yourself. 
 
@@ -134,6 +137,10 @@ services.AddServiceBus[Topic/Queue]MessagePump(..., options =>
     // this job instance in a multi-instance deployment (default: generated GUID).
     options.JobId = Guid.NewGuid().ToString();
 
+    // The name for the request operation which will be used in the chosen message correlation system.
+    // (default: Azure Service Bus message processing)
+    options.Telemetry.OperationName = "ReceiveOrder";
+    
     // Indicate whether or not messages should be automatically marked as completed when the handler succeeded (no exceptions thrown) (default: true)
     // ⚠️ Setting this property to false means you are responsible for completing the message yourself.
     options.Routing.AutoComplete = false;
@@ -163,6 +170,30 @@ services.AddServiceBus[Topic/Queue]MessagePump(..., options =>
 });
 ```
 
+#### Service Bus request tracking
+Arcus Messaging makes it possible to make it visible in a logging system like Azure Application Insights, what happens when a message is received from a Service Bus topic or queue.
+Below, you will find the different options that are supported to enable Service Bus request tracking. When this is enabled, Arcus.Messaging will log a request operation for every message that is received from Service Bus and all traces and interactions to dependent systems that happen during the processing of that message, will be logged as children of this request operation.
+
+<Tabs groupId="correlation-systems">
+<TabItem value="serilog" label="Serilog">
+
+```powershell
+PS> Install-Package -Name Arcus.Messaging.ServiceBus.Telemetry.Serilog
+```
+
+Make sure to include the following line to your message pump registration:
+```diff
+services.AddServiceBusTopicMessagePump(...)
++       .UseServiceBusSerilogRequestTracking()           
+        .WithServiceBusMessageHandler<...>()
+        .WithServiceBusMessageHandler<...>();
+```
+
+Now Arcus will use the Serilog approach to track Azure Service Bus messages. Make sure that Microsoft's  `TelemetryClient` is registered in the application services. (See [Microsoft documentation](https://learn.microsoft.com/en-us/azure/azure-monitor/app/dot-net?tabs=net%2Cnet-1%2Cserver%2Cportal%2Ccsharp%2Cenqueue) for more information.)
+
+</TabItem>
+</Tabs>
+
 ### Message handler routing customization
 The following routing options are available when registering an Azure Service Bus message handler on a message pump.
 

docs/preview/03-Guides/migration-guide-v3.0.md

@@ -158,10 +158,11 @@ To still benefit from the original W3C message correlation tracking with **Arcus
 * 🔨 Register Serilog as the message correlation system by adding this line:
   ```diff
   services.AddServiceBusTopicMessagePump(...)
-  +       .WithServiceBusSerilogRequestTracking()           
+  +       .UseServiceBusSerilogRequestTracking()           
           .WithServiceBusMessageHandler<...>()
           .WithServiceBusMessageHandler<...>();
   ```
+* 👀 Check that the `TelemetryClient` is registered in the application services (registering Azure Application Insights services is not done automatically anymore).
 * 🎉 The original (< v3.0) message correlation is now restored.
 
 We expect other kinds of message correlation registrations in the future. Switching between them would be a matter of choosing the correct `.WithServiceBus...RequestTracking()`.

src/Arcus.Messaging.Abstractions.ServiceBus/MessageHandling/AzureServiceBusMessageRouter.cs

@@ -4,11 +4,9 @@
 using System.Threading;
 using System.Threading.Tasks;
 using Arcus.Messaging.Abstractions.MessageHandling;
-using Arcus.Messaging.Abstractions.Telemetry;
 using Azure.Messaging.ServiceBus;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
-using Serilog.Context;
 using static Arcus.Messaging.Abstractions.MessageHandling.MessageProcessingError;
 
 #pragma warning disable S1133
@@ -103,10 +101,6 @@ protected async Task<MessageProcessingResult> RouteMessageWithPotentialFallbackA
             }
 
             using IServiceScope serviceScope = ServiceProvider.CreateScope();
-#pragma warning disable CS0618 // Type or member is obsolete: will be refactored when moving towards v3.0.
-            using IDisposable _ = LogContext.Push(new MessageCorrelationInfoEnricher(correlationInfo, Options.CorrelationEnricher));
-#pragma warning restore CS0618 // Type or member is obsolete
-
             return await TryRouteMessageWithPotentialFallbackAsync(serviceScope.ServiceProvider, messageReceiver, message, messageContext, correlationInfo, cancellationToken);
         }
 

src/Arcus.Messaging.Abstractions.ServiceBus/Telemetry/IServiceBusMessageCorrelationScope.cs

@@ -0,0 +1,19 @@
+using Arcus.Messaging.Abstractions.MessageHandling;
+using Arcus.Messaging.Abstractions.Telemetry;
+
+namespace Arcus.Messaging.Abstractions.ServiceBus.Telemetry
+{
+    /// <summary>
+    /// Represents the way how incoming Azure Service bus request messages
+    /// within a service-to-service correlation operation are tracked in a custom telemetry system,.
+    /// </summary>
+    public interface IServiceBusMessageCorrelationScope
+    {
+        /// <summary>
+        /// Starts a new Azure Service bus request operation on the telemetry system.
+        /// </summary>
+        /// <param name="messageContext">The message context for the currently received Azure Service bus message.</param>
+        /// <param name="options">The user-configurable options to manipulate the telemetry.</param>
+        MessageOperationResult StartOperation(ServiceBusMessageContext messageContext, MessageTelemetryOptions options);
+    }
+}

src/Arcus.Messaging.Abstractions/Arcus.Messaging.Abstractions.csproj

@@ -26,16 +26,8 @@
     <None Include="..\..\docs\static\img\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
-
     <ItemGroup>
         <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" Version="[8.*,10.0.0)" />
     </ItemGroup>
 
-  <ItemGroup>
-    <!-- TODO: will be removed in v3.0 -->
-    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.21.0" />
-    <PackageReference Include="Serilog" Version="4.3.0" />
-    <!-- TODO: will be removed in v3.0 -->
-  </ItemGroup>
-
 </Project>

src/Arcus.Messaging.Abstractions/MessageCorrelationInfo.cs

@@ -14,7 +14,7 @@ public class MessageCorrelationInfo
         /// <param name="transactionId">The unique identifier that spans one or more operations and are considered a transaction/session.</param>
         /// <exception cref="ArgumentException">Thrown when the <paramref name="operationId"/> or <paramref name="transactionId"/> is blank.</exception>
         public MessageCorrelationInfo(string operationId, string transactionId)
-            : this(operationId, transactionId, null)
+            : this(operationId, transactionId, operationParentId: null)
         {
         }
 

src/Arcus.Messaging.Abstractions/MessageCorrelationResult.cs

@@ -1,7 +1,4 @@
-using System;
-using Arcus.Messaging.Abstractions.Telemetry;
-
-namespace Arcus.Messaging.Abstractions.MessageHandling
+namespace Arcus.Messaging.Abstractions.MessageHandling
 {
     /// <summary>
     /// Represents the consumer-configurable options to change the behavior of the <see cref="MessageRouter"/>.
@@ -12,17 +9,5 @@ public class MessageRouterOptions
         /// Gets the consumer-configurable options to change the deserialization behavior of the message router.
         /// </summary>
         public MessageDeserializationOptions Deserialization { get; } = new();
-
-        /// <summary>
-        /// Gets the consumer configurable options model to change the behavior of the tracked telemetry.
-        /// </summary>
-        [Obsolete("Will be removed in v3.0 as the correlation is handled outside the core message routing")]
-        public MessageTelemetryOptions Telemetry { get; } = new();
-
-        /// <summary>
-        /// Gets the options to control the Serilog <see cref="MessageCorrelationInfoEnricher"/> when the incoming message is routed via the message router.
-        /// </summary>
-        [Obsolete("Will be removed in v3.0 as the correlation is handled outside the core message routing")]
-        public MessageCorrelationEnricherOptions CorrelationEnricher { get; } = new();
     }
 }