Serilog.Sinks.TraceContext 1.1.0-beta.2

Suggested Alternatives

Yoko.Tool.Serilog

Additional Details

Serilog.Sinks.TraceContext不再维护,请转移到Yoko.Tool.Serilog

This is a prerelease version of Serilog.Sinks.TraceContext.
dotnet add package Serilog.Sinks.TraceContext --version 1.1.0-beta.2                
NuGet\Install-Package Serilog.Sinks.TraceContext -Version 1.1.0-beta.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Serilog.Sinks.TraceContext" Version="1.1.0-beta.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Sinks.TraceContext --version 1.1.0-beta.2                
#r "nuget: Serilog.Sinks.TraceContext, 1.1.0-beta.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Serilog.Sinks.TraceContext as a Cake Addin
#addin nuget:?package=Serilog.Sinks.TraceContext&version=1.1.0-beta.2&prerelease

// Install Serilog.Sinks.TraceContext as a Cake Tool
#tool nuget:?package=Serilog.Sinks.TraceContext&version=1.1.0-beta.2&prerelease                

🌴 打包基于Serilog的日志服务

 SerilogLogger.ConfigureLogger(builder.Host);

使用示例:

try
{
    var builder = WebApplication.CreateBuilder(args);

    // 读取日志服务中心URL
    var logServiceCenterUrl = builder.Configuration["LogServiceCenterUrl"] ?? "";

    
    // 调整Quartz的日志级别并启动日志服务
    SerilogLogger.MinimumLevel.Override("Quartz", LogEventLevel.Warning);
    // 启动日志服务
    SerilogLogger.ConfigureLogger(builder.Host);

    var app = builder.Build();

    app.MapGet("/ok", () => "日志服务运行正常!").WithTags("健康检查");

    Log.Information("服务启动成功");

    app.Run();
}
catch (Exception e)
{
    Log.Fatal("服务意外终止!{msg}", e.Message);
}
finally
{
    Log.CloseAndFlush();
}

🌴 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 来记录日志。

每个日志事件都会包含两个额外的属性:TraceIdSpanId

这些属性的值来自 “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和请求路径,最后是日志消息本身。

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.