Serilog.Sinks.TraceContext 1.0.0

🌴 Serilog.Sinks.TraceContext

这个 Serilog 插件可以从 HTTP 请求头部的 “traceparent” 字段中提取追踪上下文，并将其添加到 Serilog 的日志事件中。

它遵循 W3C Trace Context 规范

按W3C Trace Context 规范， “traceparent” 头部的值应遵循 00-{traceId}-{spanId}-{traceFlags} 的格式

其中：

• traceId 是一个 32 个十六进制数字的字符串，表示追踪操作的唯一标识符。
• spanId 是一个 16 个十六进制数字的字符串，表示单个操作的唯一标识符 （例如，一个 HTTP 请求）。
• traceFlags 是一个 2 个十六进制数字的字符串，表示追踪选项。目前，唯一定义的选项是 “01”，表示记录追踪数据

示例值：

00-83efd447300bf4dfa660e807869e78f0-3f977cb3083d2ac6-01

🍀使用方法

首先，你需要在你的 Serilog 配置中使用 WithTraceContextHeader 方法：

Log.Logger = new LoggerConfiguration()
    .Enrich.WithTraceContextHeader()
    // 其他配置...
    .CreateLogger();

默认情况下，这个插件会从 “traceparent” 头部提取追踪上下文。

如果你的应用程序使用了不同的头部名称，你可以将其作为参数传递给 WithTraceContextHeader 方法：

Log.Logger = new LoggerConfiguration()
    .Enrich.WithTraceContextHeader("your-header-name")
    // 其他配置...
    .CreateLogger();

然后，你就可以像平常一样使用 Serilog 来记录日志。

每个日志事件都会包含两个额外的属性：TraceId 和 SpanId。

这些属性的值来自 “traceparent” 头部。

🌴 自定义日志格式化器

插件还包含一个自定义的日志格式化器，它可以输出两种不同的日志格式：JSON格式和文件格式。

🍀使用方法

首先，创建一个 LogFormatter 实例。你可以选择是否使用文件日志格式：

var formatter = new LogFormatter(isFileLog: true);  // 使用文件日志格式

或者：

var formatter = new LogFormatter();  // 使用JSON日志格式

然后，你可以在你的日志配置中使用这个格式化器：

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .MinimumLevel.Debug()
    .Enrich.FromLogContext()
    .WriteTo.Http(requestUri: $"{AppSettings.LogServiceCenterUrl}/api/log/insert"
        , queueLimitBytes: null
        , textFormatter: new LogFormatter() // 使用JSON格式化器
    )
    .WriteTo.File(
        formatter: new LogFormatter(true), // 使用文件格式化器
        path: $"{AppDomain.CurrentDomain.BaseDirectory}/Logs/Service-.log",
        rollingInterval: RollingInterval.Day,
        rollOnFileSizeLimit: true,
        fileSizeLimitBytes: 10485760,
        encoding: System.Text.Encoding.UTF8,
        retainedFileCountLimit: 200,
        shared: true
    )
    .CreateLogger();

🍀特性

• 两种日志格式：这个格式化器可以输出JSON格式的日志，也可以输出文件格式的日志。
• 灵活的配置：你可以在创建格式化器的时候选择使用哪种日志格式。
• 包含版本信息：日志中包含了程序集的版本信息。

🍀格式说明

🔎 JSON日志格式

JSON日志格式是一种结构化的日志格式，它使用JSON（JavaScript Object Notation）数据交换格式来表示日志事件。这种格式的优点是易于机器处理和查询，特别是在大数据和日志分析环境中。

以下是一个JSON日志格式的示例：

{
    "TimeStamp": "2024-04-29 10:35:34.576",
    "Level": "Information",
    "Message": "服务启动成功",
    "TrackingId": "1234567890",
    "Path": "/api/start",
    "Source": "MyApp",
    "Version": "1.0.0"
}

🔎 文件日志格式

文件日志格式是一种非结构化的日志格式，它将日志事件表示为简单的文本消息。这种格式的优点是易于人类阅读和理解，特别是在进行故障排查和调试时。

以下是一个文件日志格式的示例：

[2024-04-29 10:35:34.576] [Information] [1234567890] [/api/start] 服务启动成功

在这个示例中，每个方括号内的字段分别代表时间戳、日志级别、跟踪ID和请求路径，最后是日志消息本身。