安装

dotnet add package WindPayer.Logging

快速开始

// Program.cs
using WindPayer.Logging;
builder.UseWindpayerLogging();

// 正常的logger调用
// 文本信息推荐使用占位符形式，框架会自动解析出额外的结构化，以下写法会额外输出字段【id】
logger.LogInformation("这是一条日志 {id}", id);
// 不推荐写法
logger.LogInformation($"这是一条日志 {id}");

// 自定义额外信息,单次
_logger.WithData(new { bid = 20251212 }).LogInformation("这是一条日志 {id}", id);

// 范围生效
using(_logger.WithScope(new { userId = 10001 })
{
    // 业务代码
    _logger.WithData(new { bid = 20251212 }).LogInformation("这是一条日志 {id}", id);
    // 业务代码
    _logger.WithData(new { orderId = "123456" }).LogInformation("这是一条日志 {id}", id);
    // 业务代码
}

// 不推荐直接使用 using(_logger.WithScope(new { userId = 10001 }), 因为会在调用后整个请求生命周期内生效

// 使用 Module 做额外信息时，写文件日志时会自动把 Module 的值作为日志文件夹名称，可以使用 Module 来区分不同模块的日志
_logger.WithData(new { Module = "文件夹" }).LogCtxInformation("这是一条日志 {id}", id);

RabbitMQ Trace 传播

当业务代码使用 RabbitMQ 时，可以通过本库提供的扩展方法在消息生产和消费时传播 Trace 上下文，使得整个调用链（HTTP → Queue → Consumer）的 Trace 完整连贯。

安装

业务项目需要添加 WindPayer.Logging 的项目引用：

<ProjectReference Include="..\WindPayer.Logging\WindPayer.Logging.csproj" />

然后确保 appsettings.json 中开启了 Trace（EnableOtlp 或 EnableTrace）：

"WindpayerLogging": {
  "EnableOtlp": true,
  "OtlpEndpoint": "http://localhost:4317",
  ...
}

使用方式

1. 消费者端 — QueueWorker.ConsumerReceived

在消息到达时提取 Trace 上下文并创建 Consumer Activity：

private async Task ConsumerReceived(object? sender, BasicDeliverEventArgs e)
{
    string content = string.Empty;

    // ========== 提取 Trace 上下文 ==========
    using var activity = e.StartConsumerActivity($"rabbitmq consume {QueueName}");
    // ======================================

    try
    {
        // ... 原有处理逻辑不变
        var body = e.Body.ToArray();
        content = Encoding.UTF8.GetString(body);
        // ...
    }
    catch (Exception ex)
    {
        _logger?.LogError(ex, "处理消息异常");
    }
}

2. 生产者端 — QueueService.Publish（首次发布）

发布时注入当前 Trace 上下文到消息 Headers：

public void Publish(string exchange, string routingKey, string messageId, string body)
{
    var bodyArray = Encoding.UTF8.GetBytes(body);
    var properties = Channel.CreateBasicProperties();
    properties.Persistent = true;
    properties.MessageId = messageId;

    // ========== 注入 Trace 上下文 ==========
    properties.InjectTrace();
    // =====================================

    Channel.BasicPublish(exchange, routingKey, properties, bodyArray, mandatory: true);
}

3. 持久化 Trace Headers（重试时保持同一 TraceId）

如需在消息重试时保持原始 TraceId，首次发布后将 Trace Headers 提取为 JSON 存入数据库，重试时恢复。

TMessageQueue 实体新增字段：

public string? TraceHeaders { get; set; }   // JSON 格式 {"traceparent":"00-xxx-xxx-00","tracestate":"..."}

首次发布 — 保存 Headers：

// 在 Publish 后调用，将 Headers 保存到数据库
msg.TraceHeaders = TraceHelper.ExtractTraceHeadersJson();

重试发布 — 恢复 Headers：

// 从数据库读取保存的 Headers
var savedHeaders = TraceHelper.DeserializeTraceHeaders(msg.TraceHeaders);

_queueService.Publish(exchange, routingKey, msgId, body, savedHeaders);

QueueService.Publish 支持可选的 traceHeaders 参数：

public void Publish(string exchange, string routingKey, string messageId, string body,
    IReadOnlyDictionary<string, string>? traceHeaders = null)
{
    var bodyArray = Encoding.UTF8.GetBytes(body);
    var properties = Channel.CreateBasicProperties();
    properties.Persistent = true;
    properties.MessageId = messageId;

    if (traceHeaders != null)
        properties.InjectTrace(traceHeaders);   // 重试：恢复原 TraceId
    else
        properties.InjectTrace();               // 首次：生成新 Trace

    Channel.BasicPublish(exchange, routingKey, properties, bodyArray, mandatory: true);
}

4. Serilog 日志自动附带 TraceId

在 WindPayer.Logging 的 SerilogBootstrapper 中已注册了 TraceEnricher，只要 Activity.Current 存在（通过上述扩展方法已经创建），所有 Serilog 日志事件都会自动附加 trace_id 和 span_id 字段，无需额外配置。

配置

在 appsettings.json 中添加如下配置

  "WindpayerLogging": {
    "LogLevel": "Information",              //日志级别
    "ServiceName": "Notification",          //服务名称  
    "EnableConsole": true,
    "EnableOtlp": false,
    "EnableTracing": false,
    "OtlpEndpoint": "http://localhost:4317",// OTLP 地址，EnableOtlp,EnableTracing为 true 时生效
    "OtlpAuthKey": "dXNlcjE6T20xNWNHRnpjMWQ=",   // OTLP key，base64 编码的 "用户名:密码"
    // 请求日志记录配置
    "RequestLogging": {
      "SlowRequestThresholdMs": 1000,
      "GetRequestSamplingRate": 0.1,
      "LogPostRequestsAll": true,
      "LogUnsampledSlowOrErrorRequests": true,
      "MaxRequestBodyLogLength": 10000,
      "MaxResponseBodyLogLength": 10000,      
      "IgnoredPaths": [
        "/health",
        "/healthz",
        "/ready",
        "/live",
        "/metrics"
      ]
    },
    // OTel 心跳包配置
    "HeartbeatOptions": {
      "Enabled": true,
      "IntervalSeconds": 30,
      "Message": "otel_heartbeat"
    }
  },

配置项说明

RequestLogging 请求日志配置

日志级别覆盖

除了 WindpayerLogging:LogLevel 全局日志级别外，还可以通过标准 ASP.NET Core 的 Logging:LogLevel 配置对各个命名空间分别设置日志级别：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Warning",
      "YourNamespace": "Debug"
    }
  }
}

此配置会覆盖 Serilog 在各命名空间下的最小日志级别，便于控制第三方库的日志输出量。