feat: Update README to enhance configuration instructions and add new features for Activity enrichment

Author: hangy

README.md

@@ -1,28 +1,38 @@
-# Serilog.Sinks.ApplicationInsights [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.ApplicationInsights.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.ApplicationInsights/)
+# Serilog.Sinks.ApplicationInsights [![Build status](https://github.com/serilog-contrib/serilog-sinks-applicationinsights/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/serilog-contrib/serilog-sinks-applicationinsights/actions) [![NuGet Version](https://img.shields.io/nuget/v/Serilog.Sinks.ApplicationInsights.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.ApplicationInsights/) [![NuGet Downloads](https://img.shields.io/nuget/dt/Serilog.Sinks.ApplicationInsights.svg)](https://www.nuget.org/packages/Serilog.Sinks.ApplicationInsights/)
 
 A sink for Serilog that writes events to Microsoft Application Insights. This sink comes with several defaults that send
 Serilog `LogEvent` messages to Application Insights as either `EventTelemetry` or `TraceTelemetry`.
 
+## Install
+
+```powershell
+dotnet add package Serilog.Sinks.ApplicationInsights
+```
+
 ## Configuring
 
-The simplest way to configure Serilog to send data to a Application Insights dashboard via instrumentation key is to use
-current active *telemetry configuration* which is already initialised in most application types like ASP.NET Core, Azure
-Functions etc.:
+The recommended way to configure the sink is to reuse the `TelemetryConfiguration` (or `TelemetryClient`) already configured by your application (for example via dependency injection in ASP.NET Core, Azure Functions, Worker Services).
 
 ```csharp
-var log = new LoggerConfiguration()
-    .WriteTo.ApplicationInsights(TelemetryConfiguration.Active, TelemetryConverter.Traces)
+Log.Logger = new LoggerConfiguration()
+    .WriteTo.ApplicationInsights(
+        telemetryConfiguration, // from DI (recommended)
+        TelemetryConverter.Traces)
     .CreateLogger();
 ```
 
-.. or as `EventTelemetry`:
+If you don't have an existing `TelemetryConfiguration` (uncommon), you can use the connection string overload:
 
 ```csharp
-var log = new LoggerConfiguration()
-    .WriteTo.ApplicationInsights(TelemetryConfiguration.Active, TelemetryConverter.Events)
+Log.Logger = new LoggerConfiguration()
+    .WriteTo.ApplicationInsights(
+        "<your Application Insights connection string>",
+        TelemetryConverter.Traces)
     .CreateLogger();
 ```
 
+Legacy: some older application types used `TelemetryConfiguration.Active`. This is not recommended on modern .NET and may be deprecated depending on the Application Insights SDK version.
+
 > You can also pass an *instrumentation key* and this sink will create a new `TelemetryConfiguration` based on it,
 > however it's actively discouraged compared to using already initialised telemetry configuration, as your telemetry
 > won't
@@ -48,7 +58,7 @@ in `ConfigureServices`.
 Log.Logger = new LoggerConfiguration()
     .WriteTo.ApplicationInsights(
         serviceProvider.GetRequiredService<TelemetryConfiguration>(),
-	TelemetryConverter.Traces)
+        TelemetryConverter.Traces)
     .CreateLogger();
 ```
 
@@ -57,10 +67,10 @@ startup errors can be caught and properly logged. The problem is that now we're
 to setup the logger early, but we need the `TelemetryConfiguration` which still haven't been added to our DI container.
 
 Luckily [from version 4.0.x of the `Serilog.Extensions.Hosting` we have the possibility to configure a bootstrap logger](https://nblumhardt.com/2020/10/bootstrap-logger/)
-to capture early errors, and then change it using DI dependant services once they are configured.
+to capture early errors, and then change it using DI-dependent services once they are configured.
 
 ```csharp
-// dotnet add package serilog.extensions.hosting -v 4.0.0-*
+// dotnet add package Serilog.Extensions.Hosting
 
 public static class Program
 {
@@ -88,8 +98,8 @@ public static class Program
         Host.CreateDefaultBuilder(args)
             .UseSerilog((context, services, loggerConfiguration) => loggerConfiguration
                 .WriteTo.ApplicationInsights(
-		    services.GetRequiredService<TelemetryConfiguration>(),
-		    TelemetryConverter.Traces))
+                    services.GetRequiredService<TelemetryConfiguration>(),
+                    TelemetryConverter.Traces))
             .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); });
 }
 ```
@@ -120,7 +130,7 @@ with [ReadFrom.Configuration(configuration)](https://github.com/serilog/serilog-
         "Args": {
           "connectionString": "[your connection string here]",
           "telemetryConverter":
-	    "Serilog.Sinks.ApplicationInsights.TelemetryConverters.TraceTelemetryConverter, Serilog.Sinks.ApplicationInsights"
+                        "Serilog.Sinks.ApplicationInsights.TelemetryConverters.TraceTelemetryConverter, Serilog.Sinks.ApplicationInsights"
         }
       }
     ],
@@ -311,18 +321,17 @@ You can control when AI shall flush its messages, for example when your applicat
 // private TelemetryClient _telemetryClient;
 
 // ...
-_telemetryClient = new TelemetryClient()
-            {
-                InstrumentationKey = "<My AI Instrumentation Key>"
-            };
+var telemetryConfiguration = TelemetryConfiguration.CreateDefault();
+telemetryConfiguration.ConnectionString = "<your Application Insights connection string>";
+
+_telemetryClient = new TelemetryClient(telemetryConfiguration);
 ```
 
 2) Use that custom `TelemetryClient` to initialize the Sink:
 
 ```csharp
 var log = new LoggerConfiguration()
-    .WriteTo
-	.ApplicationInsights(_telemetryClient, TelemetryConverter.Events)
+    .WriteTo.ApplicationInsights(_telemetryClient, TelemetryConverter.Events)
     .CreateLogger();
 ```
 
@@ -375,7 +384,7 @@ present, AI's operation version will include the value from this property.
 
 [SerilogTracing](https://github.com/serilog-tracing/serilog-tracing) provides tracing primitives that integrate with Serilog's structured logging. When used with this sink, tracing context is automatically included in Application Insights telemetry.
 
-The following LogEvent properties are mapped to Application Insights telemetry:
+The following `LogEvent` properties are mapped to Application Insights telemetry:
 
 | LogEvent Property | Application Insights Telemetry | Notes |
 |-------------------|---------------------------------|-------|
@@ -386,13 +395,55 @@ The following LogEvent properties are mapped to Application Insights telemetry:
 | `operationId` | `Context.Operation.Id` | Overrides TraceId |
 | `version` | `Context.Component.Version` | |
 
+If present, `Baggage` is forwarded to Application Insights custom dimensions (`telemetry.Properties`).
+
 Precedence for `Context.Operation.Id`: `operationId` property > `TraceId` property (when both `operationId` and `TraceId` properties are absent).
 
+### Enriching from `Activity` (explicit opt-in)
+
+This sink is designed to work well with Serilog's asynchronous/batched processing. To keep telemetry deterministic, adding `OperationName` and `Baggage` from the ambient `Activity` is an explicit opt-in: copy the values onto the `LogEvent` before it reaches the sink.
+
+Two built-in enrichers are included:
+
+- `ActivityOperationNameEnricher` — copies `Activity.OperationName` into the `OperationName` log event property.
+- `ActivityBaggageEnricher` — copies baggage items from the current `Activity` into the `Baggage` log event property as a `StructureValue`.
+
+Enable them using the provided `Enrich` extension methods:
+
+```csharp
+Log.Logger = new LoggerConfiguration()
+    .Enrich.WithOperationName()
+    .Enrich.WithBaggage()
+    .WriteTo.ApplicationInsights(telemetryConfiguration, TelemetryConverter.Traces)
+    .CreateLogger();
+```
+
+## Upgrading to 5.0 (from 4.x)
+
+This is a new major release (5.0). Notable changes:
+
+- **OperationName and Baggage are opt-in:** they are only forwarded when present as `LogEvent` properties (use the built-in enrichers above or your own enricher).
+- **Less redundancy in custom dimensions by default:** operation-related values are set on `ITelemetry.Context` and are not duplicated into `telemetry.Properties` unless enabled.
+
+### `TelemetryConverterBase` constructor flags
+
+Converters derived from `TelemetryConverterBase` can be configured to also include selected operation-related values in `telemetry.Properties` (custom dimensions):
+
+```csharp
+public TelemetryConverterBase(
+    bool includeOperationIdPropertyAsTelemetryProperty,
+    bool includeParentSpanIdPropertyAsTelemetryProperty,
+    bool includeOperationNamePropertyAsTelemetryProperty,
+    bool includeVersionPropertyAsTelemetryProperty)
+```
+
+If you previously relied on these values being present in `telemetry.Properties`, enable the relevant flags when constructing your converter, or post-process telemetry in a custom converter.
+
 ## Using with Azure Functions
 
 Azure functions has out of the box integration with Application Insights, which automatically logs functions execution
 start, end, and any exception. Please refer to
-the [original documenation](https://docs.microsoft.com/en-us/azure/azure-functions/functions-monitoring) on how to
+the [original documentation](https://docs.microsoft.com/en-us/azure/azure-functions/functions-monitoring) on how to
 enable it.
 
 This sink can enrich AI messages, preserving *operation_Id* and other context information which is *already provided by