C#日志的上下文传递（实现跨线程、异步操作中的结构化日志追踪）

为什么需要日志上下文传递？

想象一下：你的 API 接收到一个用户请求，内部又调用了多个服务、数据库、甚至触发了后台任务。如果每个日志都是孤立的，当出现错误时，你将很难知道哪些日志属于同一个请求。

通过为每个请求分配一个唯一的 TraceId 或 CorrelationId，并在整个调用链中传递它，就能实现 日志追踪ID 的统一管理。这就是 C#日志上下文传递 的核心价值。

使用 Serilog + AsyncLocal 实现上下文传递

我们以流行的日志库 Serilog 为例，结合 .NET 提供的 AsyncLocal<T> 来实现跨异步操作的上下文传递。

第 1 步：安装必要 NuGet 包

dotnet add package Serilogdotnet add package Serilog.AspNetCoredotnet add package Serilog.Sinks.Console

第 2 步：创建日志上下文管理器

我们使用 AsyncLocal<string> 来存储当前请求的 TraceId，它能在 async/await 调用链中自动传递。

public static class LogContextManager{    private static readonly AsyncLocal<string> _traceId = new();    public static string TraceId    {        get => _traceId.Value;        set => _traceId.Value = value;    }    public static void SetTraceIdIfNotExists()    {        if (string.IsNullOrEmpty(_traceId.Value))        {            _traceId.Value = Guid.NewGuid().ToString("N")[..8]; // 简短 ID        }    }}

第 3 步：配置 Serilog 并启用 Enricher

Serilog 的 Enricher 可以在每条日志输出前动态添加属性。

public class TraceIdEnricher : ILogEventEnricher{    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)    {        var traceId = LogContextManager.TraceId;        if (!string.IsNullOrEmpty(traceId))        {            logEvent.AddPropertyIfAbsent(propertyFactory.CreateProperty("TraceId", traceId));        }    }}

第 4 步：在 Program.cs 中注册服务

var builder = WebApplication.CreateBuilder(args);// 配置 SerilogLog.Logger = new LoggerConfiguration()    .Enrich.FromLogContext()    .Enrich.With(new TraceIdEnricher()) // 添加自定义 enricher    .WriteTo.Console(outputTemplate:         "{Timestamp:yyyy-MM-dd HH:mm:ss} [{Level:u3}] {TraceId} {Message:lj}{NewLine}{Exception}")    .CreateLogger();builder.Host.UseSerilog();var app = builder.Build();// 中间件：为每个请求设置 TraceIdapp.Use(async (context, next) =>{    LogContextManager.SetTraceIdIfNotExists();    await next();});app.MapGet("/test", async () =>{    var logger = app.Services.GetRequiredService<ILogger<Program>>();    logger.LogInformation("处理请求开始");    await Task.Delay(100); // 模拟异步操作    logger.LogInformation("处理请求结束");    return "OK";});app.Run();

效果演示

当你访问 /test 接口时，控制台将输出类似以下内容：

2024-06-15 10:30:45 [INF] a1b2c3d4 处理请求开始2024-06-15 10:30:45 [INF] a1b2c3d4 处理请求结束

可以看到，即使中间有 await Task.Delay，TraceId 依然保持一致！这正是 异步日志上下文 传递的成功体现。

进阶建议

• 将 TraceId 通过 HTTP Header（如 X-Trace-Id）传给下游服务，实现全链路追踪。
• 结合 OpenTelemetry 或 Application Insights，实现可视化追踪。
• 避免在 AsyncLocal 中存储大对象，防止内存泄漏。

总结

通过本文，你学会了如何在 C# 中利用 AsyncLocal 和 Serilog 实现 日志的上下文传递。无论是在同步、异步还是多线程场景下，都能确保每条日志携带正确的 日志追踪ID，大幅提升排查效率。

掌握 结构化日志 和 异步日志上下文 技术，是构建可观测性系统的基石。赶紧在你的项目中试试吧！