From 8ef52af44b953c3c160eedd2583149066e60ac47 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Fri, 10 Oct 2025 13:17:10 +0200 Subject: [PATCH 01/22] doc updates --- docs/core/enrichment/process-log-enricher.md | 67 +++++++++++++++++++ .../snippets/enrichment/Enrichment.csproj | 17 +++++ .../enrichment/snippets/enrichment/Log.cs | 12 ++++ .../enrichment/snippets/enrichment/Program.cs | 38 +++++++++++ 4 files changed, 134 insertions(+) create mode 100644 docs/core/enrichment/process-log-enricher.md create mode 100644 docs/core/enrichment/snippets/enrichment/Enrichment.csproj create mode 100644 docs/core/enrichment/snippets/enrichment/Log.cs create mode 100644 docs/core/enrichment/snippets/enrichment/Program.cs diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md new file mode 100644 index 0000000000000..423a78ac0d00c --- /dev/null +++ b/docs/core/enrichment/process-log-enricher.md @@ -0,0 +1,67 @@ +--- +title: Process enricher +description: Learn how to use the process log enricher in .NET. +ms.date: 10/10/2025 +--- + +# Process enricher + +The process enricher augments telemetry logs or metrics 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. + +The process enricher only affects telemetry logs. + +## Usage + +To be able to use the process log enricher, first you need to enable enrichment like this: +:::code language="json" source="snippets/enrichment/Program.cs" highlight="15"::: + +then you can add the the with default properties, like this: + +:::code language="json" source="snippets/enrichment/Program.cs" highlight="16"::: + +or alternatively: + +```cs +var hostApplicationBuilder = WebApplication.CreateBuilder(); +hostApplicationBuilder.Services.AddProcessLogEnricher(); +``` + +Or, optionally, enable or disable individual options of the enricher: + +```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: + +```cs +serviceCollection.AddProcessLogEnricher(hostBuilder.Configuration.GetSection("ProcessLogEnricherOptions")); +``` + +## Default configuration + +Although default properties are supplied by the process enricher, you can customize them by initializing an instance of and providing it when registering the enricher. + +The default configuration for 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 | diff --git a/docs/core/enrichment/snippets/enrichment/Enrichment.csproj b/docs/core/enrichment/snippets/enrichment/Enrichment.csproj new file mode 100644 index 0000000000000..3b0e57857694e --- /dev/null +++ b/docs/core/enrichment/snippets/enrichment/Enrichment.csproj @@ -0,0 +1,17 @@ + + + + Exe + net9.0 + enable + enable + + + + + + + + + + diff --git a/docs/core/enrichment/snippets/enrichment/Log.cs b/docs/core/enrichment/snippets/enrichment/Log.cs new file mode 100644 index 0000000000000..4ea2cfc82a2a2 --- /dev/null +++ b/docs/core/enrichment/snippets/enrichment/Log.cs @@ -0,0 +1,12 @@ +// Copyright (c) Microsoft Corporation. All Rights Reserved. + +using Microsoft.Extensions.Logging; + +namespace Enrichment +{ + internal static partial class Log + { + [LoggerMessage(LogLevel.Information, "This is a sample log message")] + public static partial void LogSampleMessage(this ILogger logger); + } +} diff --git a/docs/core/enrichment/snippets/enrichment/Program.cs b/docs/core/enrichment/snippets/enrichment/Program.cs new file mode 100644 index 0000000000000..8ccc29d5b394f --- /dev/null +++ b/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() + .CreateLogger(); + + logger.LogSampleMessage(); + + await hostBuilder.RunAsync(); + + } + } +} From efdcba47c5466a540599dcd00e0c3cd943bc9e5d Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Fri, 10 Oct 2025 13:42:40 +0200 Subject: [PATCH 02/22] toc update --- docs/navigate/tools-diagnostics/toc.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index bd5206dcaaf63..a1267b24a938c 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -446,6 +446,10 @@ 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: Process log enricher + href: ../../core/enrichment/process-log-enricher.md - name: Specialized diagnostics items: - name: Overview From 502b1fef1bd381e6031987e808c4f4490f51ac77 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Fri, 10 Oct 2025 13:51:28 +0200 Subject: [PATCH 03/22] fixes --- docs/core/enrichment/process-log-enricher.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index 423a78ac0d00c..fd6f504455d54 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -15,11 +15,11 @@ The process enricher only affects telemetry logs. ## Usage To be able to use the process log enricher, first you need to enable enrichment like this: -:::code language="json" source="snippets/enrichment/Program.cs" highlight="15"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15"::: -then you can add the the with default properties, like this: +then you can add the with default properties, like this: -:::code language="json" source="snippets/enrichment/Program.cs" highlight="16"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="16"::: or alternatively: From 1ffb580b16c0fde59a7ae28986f1a5f358a71186 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Fri, 10 Oct 2025 13:59:55 +0200 Subject: [PATCH 04/22] updates --- docs/core/enrichment/process-log-enricher.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index fd6f504455d54..0a27692f6d1bd 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -1,17 +1,15 @@ --- -title: Process enricher +title: Process log enricher description: Learn how to use the process log enricher in .NET. ms.date: 10/10/2025 --- -# Process enricher +# Process log enricher -The process enricher augments telemetry logs or metrics with process-specific information. +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. -The process enricher only affects telemetry logs. - ## Usage To be able to use the process log enricher, first you need to enable enrichment like this: From f96db7224f2f385d64190438a59539d68e8bb854 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Fri, 10 Oct 2025 14:15:16 +0200 Subject: [PATCH 05/22] fixing reference --- docs/core/enrichment/process-log-enricher.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index 0a27692f6d1bd..003c571fb4363 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -15,7 +15,7 @@ You can register the enrichers in an IoC container. Then, all registered enriche To be able to use the process log enricher, first you need to enable enrichment like this: :::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15"::: -then you can add the with default properties, like this: +then you can add the with default properties, like this: :::code language="csharp" source="snippets/enrichment/Program.cs" highlight="16"::: @@ -26,7 +26,7 @@ var hostApplicationBuilder = WebApplication.CreateBuilder(); hostApplicationBuilder.Services.AddProcessLogEnricher(); ``` -Or, optionally, enable or disable individual options of the enricher: +Or, optionally, enable or disable individual options of the enricher using : ```cs serviceCollection.AddProcessLogEnricher(options => @@ -47,7 +47,7 @@ You may also disable or enable individual options using `appsettings.json` file } ``` -and apply it accordingly: +and apply it accordingly using : ```cs serviceCollection.AddProcessLogEnricher(hostBuilder.Configuration.GetSection("ProcessLogEnricherOptions")); From 817295a53bc022f3498c79c1275cf53633c8ddf9 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Fri, 10 Oct 2025 14:24:12 +0200 Subject: [PATCH 06/22] fix --- docs/core/enrichment/process-log-enricher.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index 003c571fb4363..a61419f05a235 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -26,7 +26,7 @@ var hostApplicationBuilder = WebApplication.CreateBuilder(); hostApplicationBuilder.Services.AddProcessLogEnricher(); ``` -Or, optionally, enable or disable individual options of the enricher using : +Or, optionally, enable or disable individual options of the enricher using : ```cs serviceCollection.AddProcessLogEnricher(options => @@ -47,7 +47,7 @@ You may also disable or enable individual options using `appsettings.json` file } ``` -and apply it accordingly using : +and apply it accordingly using : ```cs serviceCollection.AddProcessLogEnricher(hostBuilder.Configuration.GetSection("ProcessLogEnricherOptions")); From 28f4fb0f4a979658e3cb520cfc6e58aaddd0f57a Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Mon, 13 Oct 2025 12:17:39 +0200 Subject: [PATCH 07/22] fixing --- docs/core/enrichment/process-log-enricher.md | 59 +++++++++++++------ .../enrichment/snippets/enrichment/Log.cs | 12 ---- .../enrichment/snippets/enrichment/Program.cs | 2 +- 3 files changed, 43 insertions(+), 30 deletions(-) delete mode 100644 docs/core/enrichment/snippets/enrichment/Log.cs diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index a61419f05a235..9c361c2c8749b 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -12,21 +12,31 @@ You can register the enrichers in an IoC container. Then, all registered enriche ## Usage -To be able to use the process log enricher, first you need to enable enrichment like this: -:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15"::: +To be able to use the process log enricher, first you need to enable enrichment. Then you can add the with default properties, like this: -then you can add the with default properties, like this: +:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15,16"::: -:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="16"::: +Given this code sample, the output should be like this: -or alternatively: - -```cs -var hostApplicationBuilder = WebApplication.CreateBuilder(); -hostApplicationBuilder.Services.AddProcessLogEnricher(); +```console +{ + "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" + } +} ``` -Or, optionally, enable or disable individual options of the enricher using : +## `ProcessLogEnricherOptions` + +The 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 and providing it when registering the enricher. + +You can enable or disable individual options of the enricher using : ```cs serviceCollection.AddProcessLogEnricher(options => @@ -53,13 +63,28 @@ and apply it accordingly using and providing it when registering the enricher. +```console +{ + "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" + } +} +``` + +## Default configuration -The default configuration for log enrichment is: +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 | +| 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 | diff --git a/docs/core/enrichment/snippets/enrichment/Log.cs b/docs/core/enrichment/snippets/enrichment/Log.cs deleted file mode 100644 index 4ea2cfc82a2a2..0000000000000 --- a/docs/core/enrichment/snippets/enrichment/Log.cs +++ /dev/null @@ -1,12 +0,0 @@ -// Copyright (c) Microsoft Corporation. All Rights Reserved. - -using Microsoft.Extensions.Logging; - -namespace Enrichment -{ - internal static partial class Log - { - [LoggerMessage(LogLevel.Information, "This is a sample log message")] - public static partial void LogSampleMessage(this ILogger logger); - } -} diff --git a/docs/core/enrichment/snippets/enrichment/Program.cs b/docs/core/enrichment/snippets/enrichment/Program.cs index 8ccc29d5b394f..a40f58a1a0a4e 100644 --- a/docs/core/enrichment/snippets/enrichment/Program.cs +++ b/docs/core/enrichment/snippets/enrichment/Program.cs @@ -29,7 +29,7 @@ public static async Task Main() .GetRequiredService() .CreateLogger(); - logger.LogSampleMessage(); + logger.LogInformation("This is a sample log message"); await hostBuilder.RunAsync(); From d7d9112921b2b6abf19fee1b7bbc5cfc6d42dfb9 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Mon, 13 Oct 2025 17:19:38 +0200 Subject: [PATCH 08/22] added overview and custom enricher --- docs/core/enrichment/custom-enricher.md | 72 +++++++++++++++++++++++++ docs/core/enrichment/overview.md | 70 ++++++++++++++++++++++++ docs/navigate/tools-diagnostics/toc.yml | 3 ++ 3 files changed, 145 insertions(+) create mode 100644 docs/core/enrichment/custom-enricher.md create mode 100644 docs/core/enrichment/overview.md diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md new file mode 100644 index 0000000000000..ee9b1d7e8288c --- /dev/null +++ b/docs/core/enrichment/custom-enricher.md @@ -0,0 +1,72 @@ +--- +title: Custom log enricher +description: Learn how to use the custom log enricher in .NET. +ms.date: 13/10/2025 +--- + +# Custom log enricher + +You can easily create a custom enricher by creating a class that implements the interface. +After the class is created, you register it with . +And after it's registered, the enricher is invoked any time enrichment is called for. + +Your custom enricher only needs to implement a single method. +During enrichment, this method is called and given an instance. The enricher then calls one of the overloads of +the method to record any properties it wants. + +> [!Note] +> If your custom log enricher calls , +> 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. + +```cs +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()); + }); +``` + +It's also possible to configure manual instantiation of custom enrichers: + +```cs +public class AnotherEnricher : ILogEnricher() {} + +... + +var hostBuilder = new HostBuilder() + .ConfigureServices((_, serviceCollection) => + { + _ = serviceCollection.AddLogEnricher(new AnotherEnricher())); + }); +``` + +Alternatively: + +```cs +var hostApplicationBuilder = WebApplication.CreateBuilder(); +hostApplicationBuilder.Services.AddLogEnricher(); +``` + +and + +```cs +var hostApplicationBuilder = WebApplication.CreateBuilder(); +hostApplicationBuilder.Services.AddLogEnricher(new AnotherEnricher())); +``` diff --git a/docs/core/enrichment/overview.md b/docs/core/enrichment/overview.md new file mode 100644 index 0000000000000..757c268ce80f3 --- /dev/null +++ b/docs/core/enrichment/overview.md @@ -0,0 +1,70 @@ +--- +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 +--- + +# Log enrichment 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 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: + +```json +{ + "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" + } +} +``` + +## 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). diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index a1267b24a938c..b4a0f9a2b9fb0 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -447,9 +447,12 @@ items: - name: Built-in activities href: ../../core/diagnostics/distributed-tracing-builtin-activities.md - name: Enrichment + href: ../../core/enrichment/overview.md items: - 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 From 94315d91fa1a236456044b7082400a9e8dccad12 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Mon, 13 Oct 2025 17:24:16 +0200 Subject: [PATCH 09/22] fix --- docs/core/enrichment/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/enrichment/overview.md b/docs/core/enrichment/overview.md index 757c268ce80f3..b9f4ac0e6d1c1 100644 --- a/docs/core/enrichment/overview.md +++ b/docs/core/enrichment/overview.md @@ -63,7 +63,7 @@ With enrichment enabled, your log output will automatically include additional c The .NET enrichment framework provides some built-in enrichers, like: -- **[Process enricher](process.log-enricher.md)**: Process and thread information +- **[Process enricher](process-log-enricher.md)**: Process and thread information ## Custom enrichers From 1a436574f4d31e7e221b6283d37ce9b2c2859800 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Mon, 13 Oct 2025 17:31:12 +0200 Subject: [PATCH 10/22] fixes --- docs/core/enrichment/custom-enricher.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index ee9b1d7e8288c..22273732ceb2b 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -1,13 +1,13 @@ --- title: Custom log enricher description: Learn how to use the custom log enricher in .NET. -ms.date: 13/10/2025 +ms.date: 10/13/2025 --- # Custom log enricher You can easily create a custom enricher by creating a class that implements the interface. -After the class is created, you register it with . +After the class is created, you register it with . And after it's registered, the enricher is invoked any time enrichment is called for. Your custom enricher only needs to implement a single method. From 165d6c821e640d8ccad62b9e414753607d626638 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Tue, 14 Oct 2025 10:11:41 +0200 Subject: [PATCH 11/22] fix --- docs/core/enrichment/custom-enricher.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 22273732ceb2b..6604d492759d8 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -7,7 +7,7 @@ ms.date: 10/13/2025 # Custom log enricher You can easily create a custom enricher by creating a class that implements the interface. -After the class is created, you register it with . +After the class is created, you register it with . And after it's registered, the enricher is invoked any time enrichment is called for. Your custom enricher only needs to implement a single method. From e01018686da0d6ef393aa565bc5239d025b3b8a4 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Tue, 14 Oct 2025 10:19:43 +0200 Subject: [PATCH 12/22] fixing --- docs/core/enrichment/custom-enricher.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 6604d492759d8..3d52a09a97df6 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -7,7 +7,7 @@ ms.date: 10/13/2025 # Custom log enricher You can easily create a custom enricher by creating a class that implements the interface. -After the class is created, you register it with . +After the class is created, you register it with . And after it's registered, the enricher is invoked any time enrichment is called for. Your custom enricher only needs to implement a single method. From 26ed855aac08b2d542ee2763cee468a060e38331 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Tue, 14 Oct 2025 10:34:57 +0200 Subject: [PATCH 13/22] fix again --- docs/core/enrichment/custom-enricher.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 3d52a09a97df6..25ec171fd544f 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -7,7 +7,7 @@ ms.date: 10/13/2025 # Custom log enricher You can easily create a custom enricher by creating a class that implements the interface. -After the class is created, you register it with . +After the class is created, you register it with . And after it's registered, the enricher is invoked any time enrichment is called for. Your custom enricher only needs to implement a single method. From 6b003002a8f3c69ad4da1e37edb53fae5081b0b9 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Wed, 15 Oct 2025 09:58:13 +0200 Subject: [PATCH 14/22] adding nuget package reference --- docs/core/enrichment/process-log-enricher.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index 9c361c2c8749b..57c0e150898b1 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -10,6 +10,22 @@ 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 with default properties, like this: From c05bb141e8a441a6544e317f21372d87b2650e62 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Wed, 15 Oct 2025 18:41:00 +0200 Subject: [PATCH 15/22] custom enricher --- docs/core/enrichment/custom-enricher.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 25ec171fd544f..497d62c50fb0c 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -10,6 +10,24 @@ You can easily create a custom enricher by creating a class that implements the After the class is created, you register it with . And after it's registered, the enricher is invoked any time enrichment is called for. +## 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 +``` + +## Implementation + Your custom enricher only needs to implement a single method. During enrichment, this method is called and given an instance. The enricher then calls one of the overloads of the method to record any properties it wants. From 26bcaa829e63480dc1b17c24a9f2c49f53c9bb58 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Wed, 15 Oct 2025 18:56:45 +0200 Subject: [PATCH 16/22] comments --- docs/core/enrichment/custom-enricher.md | 2 +- docs/navigate/tools-diagnostics/toc.yml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 497d62c50fb0c..7c24c436c08cb 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -8,7 +8,7 @@ ms.date: 10/13/2025 You can easily create a custom enricher by creating a class that implements the interface. After the class is created, you register it with . -And after it's registered, the enricher is invoked any time enrichment is called for. +Once registered, the logging infrastructure automatically calls the `Enrich()` method on every registered enricher for each log message produced. ## Install the package diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index b4a0f9a2b9fb0..6074077eebbdf 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -447,8 +447,9 @@ items: - name: Built-in activities href: ../../core/diagnostics/distributed-tracing-builtin-activities.md - name: Enrichment - href: ../../core/enrichment/overview.md items: + - name: Overview + href: ../../core/enrichment/overview.md - name: Process log enricher href: ../../core/enrichment/process-log-enricher.md - name: Custom enricher From 72b4f73dd7b7c6dc22820c45a54543b4757de4f6 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Wed, 15 Oct 2025 18:56:56 +0200 Subject: [PATCH 17/22] rename --- docs/core/enrichment/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/enrichment/overview.md b/docs/core/enrichment/overview.md index b9f4ac0e6d1c1..ffb2a282544e3 100644 --- a/docs/core/enrichment/overview.md +++ b/docs/core/enrichment/overview.md @@ -4,7 +4,7 @@ description: Learn about log enrichment in .NET and how to enhance your logs wit ms.date: 10/13/2025 --- -# Log enrichment overview +# 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. From cc0f599b18481c2eeb3ee7803d773a68a7655e97 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Wed, 15 Oct 2025 19:12:22 +0200 Subject: [PATCH 18/22] fix --- .../enrichment/json-output-all-enabled.json | 12 ++++++++ docs/core/enrichment/json-output.json | 11 +++++++ docs/core/enrichment/overview.md | 14 +-------- docs/core/enrichment/process-log-enricher.md | 29 ++----------------- 4 files changed, 26 insertions(+), 40 deletions(-) create mode 100644 docs/core/enrichment/json-output-all-enabled.json create mode 100644 docs/core/enrichment/json-output.json diff --git a/docs/core/enrichment/json-output-all-enabled.json b/docs/core/enrichment/json-output-all-enabled.json new file mode 100644 index 0000000000000..31cabf3e1e4ce --- /dev/null +++ b/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" + } +} \ No newline at end of file diff --git a/docs/core/enrichment/json-output.json b/docs/core/enrichment/json-output.json new file mode 100644 index 0000000000000..afe2ae1f4b8de --- /dev/null +++ b/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" + } +} \ No newline at end of file diff --git a/docs/core/enrichment/overview.md b/docs/core/enrichment/overview.md index ffb2a282544e3..97beb52bd3fa5 100644 --- a/docs/core/enrichment/overview.md +++ b/docs/core/enrichment/overview.md @@ -45,19 +45,7 @@ This configuration: With enrichment enabled, your log output will automatically include additional contextual information: -```json -{ - "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" - } -} -``` +:::code language="json" source="json-output.json" highlight="8"::: ## Available enrichers diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index 57c0e150898b1..a02f0a178f793 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -34,19 +34,7 @@ To be able to use the process log enricher, first you need to enable enrichment. Given this code sample, the output should be like this: -```console -{ - "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" - } -} -``` +:::code language="json" source="json-output.json" highlight="8"::: ## `ProcessLogEnricherOptions` @@ -81,20 +69,7 @@ serviceCollection.AddProcessLogEnricher(hostBuilder.Configuration.GetSection("Pr The console output after enabling both options should look like this: -```console -{ - "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" - } -} -``` +:::code language="json" source="json-output-all-enabled.json" highlight="8,9"::: ## Default configuration From 0db22cc29017e74bb1055d10c8574eec78d8994a Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 15 Oct 2025 14:24:47 -0500 Subject: [PATCH 19/22] Update custom-enricher.md --- docs/core/enrichment/custom-enricher.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 7c24c436c08cb..4170d01f52b9e 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -26,18 +26,27 @@ Or, if you're using .NET 10+ SDK: dotnet package add Microsoft.Extensions.Telemetry.Abstractions ``` +### [PackageReference](#tab/package-reference) + +```xml +" +``` + +--- + ## Implementation Your custom enricher only needs to implement a single method. During enrichment, this method is called and given an instance. The enricher then calls one of the overloads of the method to record any properties it wants. -> [!Note] +> [!NOTE] > If your custom log enricher calls , > 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. -```cs +```csharp public class CustomEnricher : ILogEnricher { // Your custom code @@ -63,9 +72,8 @@ var hostBuilder = new HostBuilder() It's also possible to configure manual instantiation of custom enrichers: -```cs -public class AnotherEnricher : ILogEnricher() {} - +```csharp +public class AnotherEnricher : ILogEnricher() { } ... var hostBuilder = new HostBuilder() @@ -77,14 +85,14 @@ var hostBuilder = new HostBuilder() Alternatively: -```cs +```csharp var hostApplicationBuilder = WebApplication.CreateBuilder(); hostApplicationBuilder.Services.AddLogEnricher(); ``` and -```cs +```csharp var hostApplicationBuilder = WebApplication.CreateBuilder(); hostApplicationBuilder.Services.AddLogEnricher(new AnotherEnricher())); ``` From 68d667cce8fef7ebb20f3d097eda81f954d1c5b5 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Thu, 16 Oct 2025 23:16:01 +0200 Subject: [PATCH 20/22] updates --- docs/core/enrichment/custom-enricher.md | 4 +-- docs/core/enrichment/process-log-enricher.md | 2 +- .../enrichment/snippets/enrichment/Program.cs | 36 +++++++++---------- 3 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/core/enrichment/custom-enricher.md b/docs/core/enrichment/custom-enricher.md index 4170d01f52b9e..9631936a1b9aa 100644 --- a/docs/core/enrichment/custom-enricher.md +++ b/docs/core/enrichment/custom-enricher.md @@ -29,8 +29,8 @@ dotnet package add Microsoft.Extensions.Telemetry.Abstractions ### [PackageReference](#tab/package-reference) ```xml -" + ``` --- diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index a02f0a178f793..076c55479755a 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -30,7 +30,7 @@ dotnet package add Microsoft.Extensions.Telemetry To be able to use the process log enricher, first you need to enable enrichment. Then you can add the with default properties, like this: -:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="15,16"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="14,15"::: Given this code sample, the output should be like this: diff --git a/docs/core/enrichment/snippets/enrichment/Program.cs b/docs/core/enrichment/snippets/enrichment/Program.cs index a40f58a1a0a4e..04c902e7178c9 100644 --- a/docs/core/enrichment/snippets/enrichment/Program.cs +++ b/docs/core/enrichment/snippets/enrichment/Program.cs @@ -1,4 +1,6 @@ -using System.Text.Json; +#define first +#if first +using System.Text.Json; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; @@ -9,25 +11,19 @@ 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 builder = Host.CreateApplicationBuilder(); + builder.Logging.EnableEnrichment(); + builder.Logging.AddJsonConsole(op => + { + op.JsonWriterOptions = new JsonWriterOptions + { + Indented = true + }; + }); + builder.Services.AddProcessLogEnricher(); + var hostBuilder = builder.Build(); var logger = - hostBuilder.Services - .GetRequiredService() - .CreateLogger(); + hostBuilder.Services.GetRequiredService().CreateLogger(); logger.LogInformation("This is a sample log message"); @@ -36,3 +32,5 @@ public static async Task Main() } } } +#endif + From 1042b3f903ba8bd991c01632c901cd93ef4167e1 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Thu, 16 Oct 2025 23:24:33 +0200 Subject: [PATCH 21/22] fixing code blocks --- docs/core/enrichment/overview.md | 2 +- docs/core/enrichment/process-log-enricher.md | 2 +- docs/core/enrichment/snippets/enrichment/Program.cs | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/core/enrichment/overview.md b/docs/core/enrichment/overview.md index 97beb52bd3fa5..a3c540261e213 100644 --- a/docs/core/enrichment/overview.md +++ b/docs/core/enrichment/overview.md @@ -33,7 +33,7 @@ To use log enrichment in your application, you need to: 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"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" range="3-34" highlight="15,16"::: This configuration: diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index 076c55479755a..cd4e8b56ed8dc 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -30,7 +30,7 @@ dotnet package add Microsoft.Extensions.Telemetry To be able to use the process log enricher, first you need to enable enrichment. Then you can add the with default properties, like this: -:::code language="csharp" source="snippets/enrichment/Program.cs" highlight="14,15"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" range="3-34" highlight="15,16"::: Given this code sample, the output should be like this: diff --git a/docs/core/enrichment/snippets/enrichment/Program.cs b/docs/core/enrichment/snippets/enrichment/Program.cs index 04c902e7178c9..e2c636eea9efc 100644 --- a/docs/core/enrichment/snippets/enrichment/Program.cs +++ b/docs/core/enrichment/snippets/enrichment/Program.cs @@ -13,6 +13,7 @@ public static async Task Main() { var builder = Host.CreateApplicationBuilder(); builder.Logging.EnableEnrichment(); + builder.Services.AddProcessLogEnricher(); builder.Logging.AddJsonConsole(op => { op.JsonWriterOptions = new JsonWriterOptions @@ -20,7 +21,6 @@ public static async Task Main() Indented = true }; }); - builder.Services.AddProcessLogEnricher(); var hostBuilder = builder.Build(); var logger = hostBuilder.Services.GetRequiredService().CreateLogger(); @@ -33,4 +33,3 @@ public static async Task Main() } } #endif - From 7d8a1565e961d169dcb05265336f8892973a9630 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Thu, 16 Oct 2025 23:30:25 +0200 Subject: [PATCH 22/22] fixing highlights --- docs/core/enrichment/overview.md | 2 +- docs/core/enrichment/process-log-enricher.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/enrichment/overview.md b/docs/core/enrichment/overview.md index a3c540261e213..da87a80f56de4 100644 --- a/docs/core/enrichment/overview.md +++ b/docs/core/enrichment/overview.md @@ -33,7 +33,7 @@ To use log enrichment in your application, you need to: Here's a simple example showing how to set up log enrichment with process information: -:::code language="csharp" source="snippets/enrichment/Program.cs" range="3-34" highlight="15,16"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" range="3-34" highlight="13,14"::: This configuration: diff --git a/docs/core/enrichment/process-log-enricher.md b/docs/core/enrichment/process-log-enricher.md index cd4e8b56ed8dc..c2daba92fcc6d 100644 --- a/docs/core/enrichment/process-log-enricher.md +++ b/docs/core/enrichment/process-log-enricher.md @@ -30,7 +30,7 @@ dotnet package add Microsoft.Extensions.Telemetry To be able to use the process log enricher, first you need to enable enrichment. Then you can add the with default properties, like this: -:::code language="csharp" source="snippets/enrichment/Program.cs" range="3-34" highlight="15,16"::: +:::code language="csharp" source="snippets/enrichment/Program.cs" range="3-34" highlight="13,14"::: Given this code sample, the output should be like this: