Serilog.Formatting.Compact 3.0.0

Serilog.Formatting.Compact

为 Serilog 提供一个简单、紧凑的基于 JSON 的事件格式。与 Serilog 的默认 JsonFormatter 相比，CompactJsonFormatter 显著减少了小型日志事件的字节数，同时仍然可读。它通过较短的内置属性名称、更精简的格式以及排除冗余信息来实现这一点。

示例

一个简单的 Hello, {User} 事件。

{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {User}","User":"nblumhardt"}

入门

从 NuGet 安装

dotnet add package Serilog.Formatting.Compact

该格式化器与接受 ITextFormatter 的接收器一起使用。例如，文件 接收器

Log.Logger = new LoggerConfiguration()
  .WriteTo.File(new CompactJsonFormatter(), "./logs/myapp.json")
  .CreateLogger();

XML <appSettings> 配置

要在 XML <appSettings> 中指定格式化器，提供其程序集限定类型名

<appSettings>
  <add key="serilog:using:File" value="Serilog.Sinks.File" />
  <add key="serilog:write-to:File.path" value="./logs/myapp.json" />
  <add key="serilog:write-to:File.formatter"
       value="Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact" />

JSON appsettings.json 配置

要在 appsettings.json 中指定格式化器，提供其程序集限定类型名

{
  "Serilog": {
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "./logs/myapp.json",
          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
        }
      }
    ]
  }
}

渲染的事件

CompactJsonFormatter 保留消息模板、属性和格式化信息，以便稍后创建渲染的消息。当 JSON 专为在无法渲染消息模板的环境中消费而设计时，可以使用 RenderedCompactJsonFormatter。

与消息模板不同，RenderedCompactJsonFormatter 会将完全渲染的消息以及从消息模板生成的 事件 ID 写入事件中，该事件 ID 可在 此处生成。

{"@t":"2016-06-07T03:44:57.8532799Z","@m":"Hello, \"nblumhardt\"","@i":"7a8b9c0d","User":"nblumhardt"}

格式细节

紧凑格式化器写入的格式是通用的，以便在需要的情况下实现其他日志记录库的实现，包括 Microsoft.Extensions.Logging。

有效负载

每个事件都是一个包含事件数据的顶级 JSON 对象。有效负载对象上的任何 JSON 属性都假定为事件的常规属性，除了下面的具体属性之外。

具体属性

该格式定义了几个具有特殊意义的具体属性

要使用户属性名称的开头具有转义符号 `@`，请重复它，例如 @@name 表示名为 @name 的属性。

批量格式

当事件批量到一个单个的有效负载时，需要一个以换行符分隔的 JSON 文档流。可以使用 \n 或 \r\n 分隔符。使用新行分隔的紧凑 JSON 事件批可以使用的（非官方）MIME 类型是 application/vnd.serilog.clef。

版本化

版本化只能是增量版本，没有版本标识符；实现应将任何未识别的具体属性视为用户数据。

比较

下面的输出和基准比较紧凑 JSON 格式化器与 Serilog 内置的 JsonFormatter。

事件

Log.Information("Hello, {@User}, {N:x8} at {Now}",
  new
  {
    Name = "nblumhardt",
    Tags = new[] { 1, 2, 3 }
  },
  123,
  DateTime.Now);

默认 JsonFormatter 292 字节

{"Timestamp":"2016-06-07T13:44:57.8532799+10:00","Level":"Information","MessageT
emplate":"Hello, {@User}, {N:x8} at {Now}","Properties":{"User":{"Name":"nblumha
rdt","Tags":[1,2,3]},"N":123,"Now":"2016-06-07T13:44:57.8532799+10:00"},"Renderi
ngs":{"N":[{"Format":"x8","Rendering":"0000007b"}]}}

CompactJsonFormatter 187 字节（0.64）

{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {@User}, {N:x8} at {Now}","@r
":["0000007b"],"User":{"Name":"nblumhardt","Tags":[1,2,3]},"N":123,"Now":2016-06
-07T13:44:57.8532799+10:00}

格式化基准

请参阅 test/Serilog.Formatting.Compact.Tests/FormattingBenchmarks.cs。

工具

有几种工具可用于处理CLEF格式。

• Analogy.LogViewer.Serilog - 用于Analogy Log Viewer的CLEF解析器
• clef-tool - 用于处理CLEF文件的命令行应用程序
• 紧凑型日志格式查看器 - CLEF文件的跨平台查看器
• seqcli - 在命令行中格式化CLEF文件，或将CLEF文件导入Seq进行搜索和分析
• Serilog.Formatting.Compact.Reader - 将CLEF文档转换回Serilog LogEvent

自定义输出

Serilog.Formatting.Compact 不打算提供可自定义的格式化工具。请参阅此博客文章以获取全面的Serilog JSON输出自定义示例。