Yoko.Tool.Serilog 0.1.4

📚 使用组件

📒 获取请求中的追踪id

可以从 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和请求路径，最后是日志消息本身。

📒 自定义日志格式化器

自定义一个格式化器，然后继承 ITextFormatter 实现对应的方法即可

示例：自带的类型判断的格式化器

public class DcLogFormatter : ITextFormatter
{
    public void Format(LogEvent logEvent, TextWriter output)
    {
        var type = 0;
        if (logEvent.Properties.TryGetValue("type", out var typeValue) && typeValue is ScalarValue scalarTypeValue)
        {
            type = scalarTypeValue.Value.ToInt32();
        }
        if (type == 1)
        {
            var json = logEvent.RenderMessage();
            output.Write(json);
        }
    }
}

internal static class StringExtensions
{
    internal static int ToInt32(this object s)
    {
        if (s == null)
        {
            return 0;
        }
        return int.TryParse(s.ToString(), out int result) ? result : 0;
    }
}

📚 已弃用 打包基于Serilog的日志服务

默认集成追踪id 、日志格式化器

 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, 
         // 可选配置
         enableFileLogging: true, 
         logFilePath: "d:/Logs/MyAppLog-.log", 
         headerKey: "my-trace-header", 
         logServiceCenterUrl: "https://logservice.example.com",
         useLogFormatter: true, 
         logFormatter: new JsonFormatter()  //自定义格式化器
    );

    var app = builder.Build();

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

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

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

说明文档：

SerilogLogger

SerilogLogger 类提供了一种便捷的方法来配置 Serilog 日志记录器，支持控制是否启用文件日志记录。

方法

ConfigureLogger

配置并初始化 Serilog 日志记录器。

参数

• hostBuilder (IHostBuilder): 应用程序的主机生成器。
• enableFileLogging (bool): 是否启用文件日志记录。默认为 true。
• logFilePath (string?): 日志文件的路径。默认为 null，会使用默认路径 ${basePath}/Logs/Log-.log。
• headerKey (string): 用于 TraceContext 的请求头键。默认为 "traceparent"。
• logServiceCenterUrl (string): 日志服务中心的 URL。如果为空或空白，则不会配置 HTTP 日志记录。默认为 ""。
• useLogFormatter: 控制是否使用日志格式化器。如果设置为 false，则不使用任何日志格式化器；如果设置为 true，且未提供自定义的 logFormatter，则使用默认的 LogFormatter。
• logFormatter (ITextFormatter?): 自定义日志格式化器。默认为 null，会使用默认的 LogFormatter。

参数详细说明

• hostBuilder: 传入应用程序的主机生成器，用于配置 Serilog。
• enableFileLogging: 控制是否启用文件日志记录。如果设置为 false，将不会配置文件日志记录。
• logFilePath: 指定日志文件的路径。如果未提供，将使用默认路径 ${basePath}/Logs/Log-.log。
• headerKey: 指定用于 TraceContext 的请求头键，默认值为 "traceparent"。
• logServiceCenterUrl: 指定日志服务中心的 URL。如果为空或空白，则不会配置 HTTP 日志记录。
• useLogFormatter 参数允许控制是否使用日志格式化器。如果为 true，且未提供自定义的 logFormatter，则使用默认的 LogFormatter；如果为 false，则不使用任何日志格式化器。
• logFormatter: 自定义日志格式化器。如果未提供，将使用默认的 LogFormatter。

日志配置说明

• 默认情况下，日志会输出到控制台，并记录所有级别为 Debug 及以上的日志。
• 可以通过设置 enableFileLogging 参数来控制是否启用文件日志记录。启用时，日志会按天滚动保存，每个文件最大10M，保留最近的200个日志文件。
• 如果提供了 logServiceCenterUrl，日志也会发送到指定的日志服务中心。
• useLogFormatter 参数允许控制是否使用日志格式化器。如果为 true，且未提供自定义的 logFormatter，则使用默认的 LogFormatter；如果为 false，则不使用任何日志格式化器。
• logFormatter 参数允许指定自定义的日志格式化器，以便自定义日志的输出格式。

更新日志

【新增】可选是否使用日志格式化器