Custom log enricher

You can easily create a custom enricher by creating a class that implements the ILogEnricher interface. After the class is created, you register it with AddLogEnricher(IServiceCollection, ILogEnricher). Once registered, the logging infrastructure automatically calls the Enrich() method exactly once on every registered enricher for each log message produced.

Install the package

To get started, install the 📦 Microsoft.Extensions.Telemetry.Abstractions NuGet package:

.NET CLI

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Or, if you're using .NET 10+ SDK:

dotnet package add Microsoft.Extensions.Telemetry.Abstractions 

PackageReference

<PackageReference Include="Microsoft.Extensions.Telemetry.Abstractions"
                  Version="*" /> <!-- Adjust version -->

ILogEnricher implementation

Your custom enricher only needs to implement a single Enrich(IEnrichmentTagCollector) method. During enrichment, this method is called and given an IEnrichmentTagCollector instance. The enricher then calls one of the overloads of the Add(String, Object) method to record any properties it wants.

Note

If your custom log enricher calls Add(String, 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.

public class CustomEnricher : ILogEnricher
{
    public void Enrich(IEnrichmentTagCollector collector)
    {
        collector.Add("customKey", "customValue");
    }
}

And you register it as shown in the following code using AddLogEnricher<T>(IServiceCollection):

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.EnableEnrichment();
builder.Services.AddLogEnricher<CustomEnricher>();

It's also possible to configure manual instantiation of custom enrichers:

public class AnotherEnricher : ILogEnricher
{
    private readonly string _key;
    private readonly object _value;
    public CustomEnricher(string key, object value)
    {
        _key = key;
        _value = value;
    }
    public void Enrich(IEnrichmentTagCollector collector)
    {
        collector.Add(_key, _value);
    }
}

And you register it as shown in the following code AddLogEnricher(IServiceCollection, ILogEnricher):

var builder = Host.CreateApplicationBuilder();
builder.Logging.EnableEnrichment();
builder.Services.AddLogEnricher(new AnotherEnricher("anotherKey", "anotherValue"));

Static log enrichers

.NET provides IStaticLogEnricher to enrich logs with immutable properties throughout the application lifecycle. Static enrichers execute once during startup initialization, delivering significant performance benefits over standard enrichers that execute for each log record. This approach is particularly advantageous in high-throughput logging scenarios, as it eliminates the overhead of redundant enrichment operations for data that remains constant throughout the service's lifetime. Although executed only once at startup, the enrichment results are attached to every single log message produced by your application.

public class StaticEnricher : IStaticLogEnricher
{
    public void Enrich(IEnrichmentTagCollector collector)
    {
        collector.Add("app.version", "1.0.0");
        collector.Add("environment", "production");
    }
}

And you register it as shown in the following code AddStaticLogEnricher<T>(IServiceCollection):

var builder = Host.CreateApplicationBuilder(args);
builder.Logging.EnableEnrichment();
builder.Services.AddStaticLogEnricher<StaticEnricher>();