Adding process log enricher documentation

docs/core/enrichment/custom-enricher.md

@@ -0,0 +1,98 @@
+---
+title: Custom log enricher
+description: Learn how to use the custom log enricher in .NET.
+ms.date: 10/13/2025
+---
+
+# Custom log enricher
+
+You can easily create a custom enricher by creating a class that implements the <xref:Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher> interface.
+After the class is created, you register it with <xref:Microsoft.Extensions.DependencyInjection.EnrichmentServiceCollectionExtensions.AddLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher)>.
+Once registered, the logging infrastructure automatically calls the `Enrich()` method on every registered enricher for each log message produced.
+
+## Install the package
+
+To get started, install the [📦 Microsoft.Extensions.Telemetry.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry.Abstractions) NuGet package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Extensions.Telemetry.Abstractions
+```
+
+Or, if you're using .NET 10+ SDK:
+
+```dotnetcli
+dotnet package add Microsoft.Extensions.Telemetry.Abstractions 
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include=" Microsoft.Extensions.Telemetry.Abstractions"
+			      Version="*" />" <!-- Adjust version -->
+```
+
+---
+
+## Implementation
+
+Your custom enricher only needs to implement a single <xref:Microsoft.Extensions.Diagnostics.Enrichment.ILogEnricher.Enrich(Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector)> method.
+During enrichment, this method is called and given an <xref:Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector> instance. The enricher then calls one of the overloads of
+the <xref:Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector.Add(System.String,System.Object)> method to record any properties it wants.
+
+> [!NOTE]
+> If your custom log enricher calls <xref:Microsoft.Extensions.Diagnostics.Enrichment.IEnrichmentTagCollector.Add(System.String,System.Object)>,
+> it is acceptable to send any type of argument to the `value` parameter as is, because it is parsed into the actual type and serialized internally
+> to be sent further down the logging pipeline.
+
+```csharp
+public class CustomEnricher : ILogEnricher
+{
+    // Your custom code
+
+    public void Enrich(IEnrichmentTagCollector collector)
+    {
+        // Call Add to add all required key/value pair to enrich logs with.
+        foreach(var property in propertiesToEnrichWith)
+        {
+            collector.Add(propertyName, propertyValue);
+        }
+    }
+}
+
+...
+
+var hostBuilder = new HostBuilder()
+    .ConfigureServices((_, serviceCollection) =>
+    {
+        _ = serviceCollection.AddLogEnricher<CustomEnricher>());
+    });
+```
+
+It's also possible to configure manual instantiation of custom enrichers:
+
+```csharp
+public class AnotherEnricher : ILogEnricher() { }
+...
+
+var hostBuilder = new HostBuilder()
+    .ConfigureServices((_, serviceCollection) =>
+    {
+        _ = serviceCollection.AddLogEnricher(new AnotherEnricher()));
+    });
+```
+
+Alternatively:
+
+```csharp
+var hostApplicationBuilder = WebApplication.CreateBuilder();
+hostApplicationBuilder.Services.AddLogEnricher<CustomEnricher>();
+```
+
+and
+
+```csharp
+var hostApplicationBuilder = WebApplication.CreateBuilder();
+hostApplicationBuilder.Services.AddLogEnricher(new AnotherEnricher()));
+```

docs/core/enrichment/json-output-all-enabled.json

@@ -0,0 +1,12 @@
+{
+  "EventId": 0,
+  "LogLevel": "Information",
+  "Category": "Enrichment.Program",
+  "Message": "This is a sample log message",
+  "State": {
+    "Message": "This is a sample log message",
+    "process.pid": "12924",
+    "thread.id": "2",
+    "{OriginalFormat}": "This is a sample log message"
+  }
+}

docs/core/enrichment/json-output.json

@@ -0,0 +1,11 @@
+{
+  "EventId": 0,
+  "LogLevel": "Information",
+  "Category": "Enrichment.Program",
+  "Message": "This is a sample log message",
+  "State": {
+    "Message": "This is a sample log message",
+    "process.pid": "10696",
+    "{OriginalFormat}": "This is a sample log message"
+  }
+}

docs/core/enrichment/overview.md

@@ -0,0 +1,58 @@
+---
+title: Log enrichment overview
+description: Learn about log enrichment in .NET and how to enhance your logs with contextual information.
+ms.date: 10/13/2025
+---
+
+# Overview
+
+Log enrichment is a powerful feature that automatically attaches contextual information to your application's logs. Instead of manually adding metadata to each log, enrichment provides a systematic way to inject relevant context automatically across your entire application.
+
+## What is enrichment?
+
+Enrichment augments telemetry objects with additional information that provides valuable context about the environment, application state, and execution context when the telemetry was generated. This contextual data helps with debugging, monitoring, performance analysis, and understanding application behavior in production environments.
+
+## How enrichment works
+
+The enrichment framework operates through a collection of enrichers that are registered with the dependency injection container. When telemetry is generated, all registered enrichers automatically contribute their contextual information to the telemetry payload. You just register the specific set of enrichers you want into
+an <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> instance. The enrichers run automatically without requiring changes to your application code. You simply configure which enrichers you want to use during application startup.
+
+## Dimension names and tags
+
+Enrichers add information to telemetry using standardized dimension names (also called tags or keys).
+
+## Setting up enrichment
+
+To use log enrichment in your application, you need to:
+
+1. **Enable enrichment** for logging
+2. **Register specific enrichers** you want to use
+3. **Configure options** for each enricher (optional)
+
+### Basic setup example
+
+Here's a simple example showing how to set up log enrichment with process information:
+
+:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15,16":::
+
+This configuration:
+
+- Enables enrichment for logging via `EnableEnrichment()`
+- Registers the process log enricher via `AddProcessLogEnricher()`
+- Configures JSON console output to display the enriched data
+
+### Output example
+
+With enrichment enabled, your log output will automatically include additional contextual information:
+
+:::code language="json" source="json-output.json" highlight="8":::
+
+## Available enrichers
+
+The .NET enrichment framework provides some built-in enrichers, like:
+
+- **[Process enricher](process-log-enricher.md)**: Process and thread information
+
+## Custom enrichers
+
+If the built-in enrichers don't meet your specific needs, you can create custom enrichers to add application-specific context. For more information, check [custom enrichment](custom-enricher.md).

docs/core/enrichment/process-log-enricher.md

@@ -0,0 +1,81 @@
+---
+title: Process log enricher
+description: Learn how to use the process log enricher in .NET.
+ms.date: 10/10/2025
+---
+
+# Process log enricher
+
+The process enricher augments telemetry logs with process-specific information.
+
+You can register the enrichers in an IoC container. Then, all registered enrichers are picked up automatically by the respective telemetry instances, such as logs or metrics, where they enrich the telemetry information.
+
+## Install the package
+
+To get started, install the [📦 Microsoft.Extensions.Telemetry](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry) NuGet package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Extensions.Telemetry
+```
+
+Or, if you're using .NET 10+ SDK:
+
+```dotnetcli
+dotnet package add Microsoft.Extensions.Telemetry
+```
+
+## Usage
+
+To be able to use the process log enricher, first you need to enable enrichment. Then you can add the <xref:Microsoft.Extensions.DependencyInjection.ProcessEnricherServiceCollectionExtensions.AddProcessLogEnricher*> with default properties, like this:
+
+:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15,16":::
+
+Given this code sample, the output should be like this:
+
+:::code language="json" source="json-output.json" highlight="8":::
+
+## `ProcessLogEnricherOptions`
+
+The <xref:Microsoft.Extensions.Diagnostics.Enrichment.ProcessLogEnricherOptions> class provides fine-grained control over which process-related properties are included in your log enrichment. This options class allows you to selectively enable or disable specific enrichment features such as process ID and thread ID information. Although default properties are supplied by the process enricher, you can customize them by initializing an instance of <xref:Microsoft.Extensions.Diagnostics.Enrichment.ProcessLogEnricherOptions> and providing it when registering the enricher.
+
+You can enable or disable individual options of the enricher using <xref:Microsoft.Extensions.DependencyInjection.ProcessEnricherServiceCollectionExtensions.AddProcessLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Action{Microsoft.Extensions.Diagnostics.Enrichment.ProcessLogEnricherOptions})>:
+
+```cs
+serviceCollection.AddProcessLogEnricher(options =>
+{
+    options.ThreadId = true;
+    options.ProcessId = true;
+});
+```
+
+You may also disable or enable individual options using `appsettings.json` file configuration, for example:
+
+```json
+{
+    "ProcessLogEnricherOptions": {
+        "ThreadId": true,
+        "ProcessId": true
+    }
+}
+```
+
+and apply it accordingly using <xref:Microsoft.Extensions.DependencyInjection.ProcessEnricherServiceCollectionExtensions.AddProcessLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Configuration.IConfigurationSection)>:
+
+```cs
+serviceCollection.AddProcessLogEnricher(hostBuilder.Configuration.GetSection("ProcessLogEnricherOptions"));
+```
+
+The console output after enabling both options should look like this:
+
+:::code language="json" source="json-output-all-enabled.json" highlight="8,9":::
+
+## Default configuration
+
+The default configuration for process log enrichment is:
+
+| Property   | Default Value   | Description                                                  |
+| -----------| ----------------|--------------------------------------------------------------|
+| `ProcessId`     | true            | If true, logs are enriched with the current process ID. |
+| `ThreadId`      | false           | If true, logs are enriched with the current thread ID   |

docs/core/enrichment/snippets/enrichment/Enrichment.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Telemetry" Version="9.9.0" />
+  </ItemGroup>
+
+</Project>

docs/core/enrichment/snippets/enrichment/Program.cs

@@ -0,0 +1,38 @@
+using System.Text.Json;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace Enrichment
+{
+    internal class Program
+    {
+        public static async Task Main()
+        {
+            var host = new HostBuilder()
+               .ConfigureLogging((hostingContext, loggingBuilder) =>
+               {
+                   loggingBuilder.EnableEnrichment();
+                   loggingBuilder.Services.AddProcessLogEnricher();
+                   loggingBuilder.AddJsonConsole(op =>
+                   {
+                       op.JsonWriterOptions = new JsonWriterOptions
+                       {
+                           Indented = true
+                       };
+                   });
+               });
+
+            var hostBuilder = host.Build();
+            var logger =
+               hostBuilder.Services
+                   .GetRequiredService<ILoggerFactory>()
+                   .CreateLogger<Program>();
+
+            logger.LogInformation("This is a sample log message");
+
+            await hostBuilder.RunAsync();
+
+        }
+    }
+}

docs/navigate/tools-diagnostics/toc.yml

@@ -446,6 +446,14 @@ items:
             href: ../../core/diagnostics/distributed-tracing-collection-walkthroughs.md
           - name: Built-in activities
             href: ../../core/diagnostics/distributed-tracing-builtin-activities.md
+      - name: Enrichment
+        items:
+          - name: Overview
+            href: ../../core/enrichment/overview.md
+          - name: Process log enricher
+            href: ../../core/enrichment/process-log-enricher.md
+          - name: Custom enricher
+            href: ../../core/enrichment/custom-enricher.md
       - name: Specialized diagnostics
         items:
           - name: Overview