Serilog Structured Logging in .NET: A Complete Guide

Imagine you're debugging a production outage. A user reports an error, but your logs only show: "Error processing request." No context, no user ID, no stack trace. You're blind. This is the reality of traditional text-based logging. Enter Serilog and structured logging.

Structured logging treats log events as data, not just strings. Each log entry is a structured object with named properties like {UserId}, {OrderId}, {Duration}. This transforms your logs from a firehose of text into a queryable database. You can ask: "Show me all errors for user 42 in the last hour" or "What's the average response time for /api/orders?"

In this tutorial, you'll learn how to integrate Serilog into your .NET applications, configure sinks (destinations) like console, files, and Seq, enrich logs with contextual data, and avoid common pitfalls. We'll cover real-world scenarios including production debugging, performance considerations, and security best practices. By the end, you'll be able to implement structured logging that makes debugging a breeze.

What is Structured Logging and Why Serilog?

Structured logging is the practice of emitting log events as structured data (e.g., JSON) rather than plain text. Each log event contains named properties that can be queried, filtered, and aggregated. Serilog is the most popular structured logging library for .NET, offering a simple API, extensive sink support, and high performance.

Traditional logging: log.Info("User {0} logged in from {1}", userId, ip) produces a string like "User 42 logged in from 192.168.1.1". To find all logins from a specific IP, you'd need to parse strings. With Serilog: log.Information("User {UserId} logged in from {ClientIP}", userId, ip) produces a JSON object with UserId and ClientIP properties. You can then query: "Show me all events where ClientIP = 192.168.1.1".

Let's start by installing Serilog and configuring a basic logger.

using Serilog;

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .WriteTo.Console()
    .WriteTo.File("logs/myapp.log", rollingInterval: RollingInterval.Day)
    .CreateLogger();

Log.Information("Application starting up");
Log.Warning("This is a warning with {Property}", 42);
Log.Error(new Exception("Something broke"), "Error occurred");

Log.CloseAndFlush();

Configuring Serilog in ASP.NET Core

In ASP.NET Core, Serilog integrates seamlessly with the built-in logging abstraction. You can configure Serilog in Program.cs or via appsettings.json. The recommended approach is to use the UseSerilog extension method.

First, install the package: dotnet add package Serilog.AspNetCore.

Then, in Program.cs, call UseSerilog() on the host builder. You can configure the logger before building the host to capture early startup logs.

Configuration via appsettings.json is powerful: you can define sinks, minimum levels, overrides per namespace, and enrichers without recompiling. The Serilog.Settings.Configuration package reads the configuration.

Here's a complete example:

using Serilog;

Log.Logger = new LoggerConfiguration()
    .ReadFrom.Configuration(builder.Configuration)
    .CreateLogger();

builder.Host.UseSerilog();

var app = builder.Build();

app.MapGet("/", () =>
{
    Log.Information("Handling request");
    return "Hello World!";
});

app.Run();

Serilog Sinks: Where Your Logs Go

Serilog sinks are destinations for log events. The most common sinks include: - Console: Great for development and Docker containers. - File: Writes to rolling files by day, size, or both. - Seq: A structured log server that provides a web UI for querying. - Elasticsearch: Indexes logs into Elasticsearch for Kibana dashboards. - Application Insights: Sends logs to Azure. - MongoDB: Stores logs in MongoDB collections.

Each sink has its own configuration options. For example, the file sink supports rollingInterval, retainedFileCountLimit, and buffered. The Seq sink requires a server URL and optional API key.

Here's how to configure multiple sinks:

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console()
    .WriteTo.File("logs/log.txt", rollingInterval: RollingInterval.Day)
    .WriteTo.Seq("http://localhost:5341", apiKey: "myApiKey")
    .WriteTo.ApplicationInsights(telemetryClient, TelemetryConverter.Traces)
    .CreateLogger();

Enriching Logs with Context

Enrichers add additional properties to every log event automatically. Common enrichers include: - WithMachineName(): Adds the machine name. - WithThreadId(): Adds the managed thread ID. - WithEnvironmentName(): Adds the environment (Development, Production). - FromLogContext(): Allows you to push properties dynamically using LogContext.PushProperty.

You can also create custom enrichers by implementing ILogEventEnricher.

Dynamic enrichment is powerful for adding correlation IDs, user IDs, or request-specific data. In ASP.NET Core, you can use middleware to push properties into the log context.

// Static enrichment
Log.Logger = new LoggerConfiguration()
    .Enrich.WithMachineName()
    .Enrich.WithThreadId()
    .Enrich.WithEnvironmentName()
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .CreateLogger();

// Dynamic enrichment using LogContext
using (LogContext.PushProperty("UserId", 42))
{
    Log.Information("Processing order");
    // This log event will have UserId=42
}

// In ASP.NET Core middleware
app.Use(async (context, next) =>
{
    using (LogContext.PushProperty("CorrelationId", context.TraceIdentifier))
    {
        await next();
    }
});

Filtering and Controlling Log Output

Serilog provides powerful filtering capabilities to control which events are written. You can filter by level, by source context, or by custom criteria.

• Minimum Level: Set a global minimum level (e.g., Information).
• Override: Increase or decrease level for specific namespaces (e.g., Microsoft.AspNetCore to Warning).
• Filters: Use lambda expressions or Serilog.Filters.Expressions to include/exclude events based on properties.

Example: Suppress health check logs.

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Information()
    .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
    .MinimumLevel.Override("System", LogEventLevel.Error)
    .Filter.ByExcluding(e => e.Properties.ContainsKey("HealthCheck"))
    .WriteTo.Console()
    .CreateLogger();

// Or using expression filter (requires Serilog.Filters.Expressions)
.Filter.ByExcluding("HealthCheck = true")

Destructuring Complex Objects

By default, Serilog calls ToString() on objects. For complex objects, you may want to destructure them into their properties. Use the @ operator to force destructuring.

You can also create custom destructuring policies to control how specific types are serialized. This is useful for security (e.g., masking credit card numbers) or for reducing log size.

Example: Destructure an order object.

public class Order
{
    public int Id { get; set; }
    public decimal Amount { get; set; }
    public string CreditCard { get; set; }
}

// In logger configuration
Log.Logger = new LoggerConfiguration()
    .Destructure.ToMaximumDepth(4)
    .Destructure.ToMaximumStringLength(100)
    .Destructure.ToMaximumCollectionCount(10)
    .Destructure.With<MaskCreditCardPolicy>()
    .WriteTo.Console()
    .CreateLogger();

// Custom destructuring policy
public class MaskCreditCardPolicy : IDestructuringPolicy
{
    public bool TryDestructure(object value, ILogEventPropertyValueFactory factory, out LogEventPropertyValue result)
    {
        if (value is string s && s.Length == 16 && s.All(char.IsDigit))
        {
            result = new ScalarValue("****-****-****-" + s[^4..]);
            return true;
        }
        result = null;
        return false;
    }
}

// Usage
var order = new Order { Id = 1, Amount = 100, CreditCard = "1234567812345678" };
Log.Information("Order processed: {@Order}", order);

Best Practices and Common Pitfalls

1. Use named loggers: Inject ILogger<T> in ASP.NET Core to get a logger with the category name. This helps filtering.
2. Avoid string interpolation: Always use message templates with placeholders. Log.Information("User {UserId}", id) not Log.Information($"User {id}").
3. Don't log in tight loops: Logging is I/O-bound. Use counters or sample logs instead.
4. Use structured exceptions: Log exceptions with Log.Error(ex, "Message") to capture stack trace and exception properties.
5. Set up alerts: Use tools like Seq to create alerts on error patterns.
6. Test your logging: Write unit tests that verify log events are emitted correctly using Serilog.Sinks.TestCorrelator or Serilog.Sinks.XUnit.

// Good: named logger
public class OrderService
{
    private readonly ILogger<OrderService> _logger;
    public OrderService(ILogger<OrderService> logger) => _logger = logger;
    
    public void Process(Order order)
    {
        _logger.LogInformation("Processing order {OrderId}", order.Id);
    }
}

// Bad: string interpolation
Log.Information($"Processing order {order.Id}"); // This loses the property

// Good: structured exception
Log.Error(ex, "Failed to process order {OrderId}", order.Id);