Util应用框架基础(六) - 日志记录(三) - 写入 Seq

本文是Util应用框架日志记录的第三篇,介绍安装和写入 Seq 日志系统的配置方法.

安装 Seq

Seq是一个日志管理系统,对结构化日志数据拥有强大的模糊搜索能力.

Util应用框架目前主要使用 Seq 和 Exceptionless 管理日志.

你可以从中选择一个合适的.

本节介绍使用 Docker 简单安装 Seq,用于开发测试,部署到生产环境请参考官方文档.

安装 Seq

创建 seq-data 卷, 运行命令.

docker volume create seq-data

创建 Seq 容器, 运行命令.

docker run --name seq -d --restart=always -e ACCEPT_EULA=Y -v seq-data:/data -p 5380:80 datalust/seq:2023.3

容器名称: seq

连接端口: 5380

未设置用户密码

安装成功后,Docker容器列表出现 seq 容器.

运行 Seq

打开 http://localhost:5380 ,可以看到 Seq 管理界面.

写入 Seq

日志配置

引用Nuget包

Nuget包名: Util.Logging.Serilog
AddSerilog

使用 AddSerilog 扩展方法启用 Serilog 日志操作.
- 默认配置不带参数.
```
var builder = WebApplication.CreateBuilder( args );
builder.AsBuild().AddSerilog();
```
- 如果要清除默认设置的日志提供程序,传入 true.
  
  Asp.Net Core 默认日志提供程序会把消息输出到控制台,你可以清除它们.
```
builder.AsBuild().AddSerilog( true );
```
- 设置应用程序名称.
  
  对于微服务应用,记录产生日志的应用名称,能方便排查问题.
```
builder.AsBuild().AddSerilog( "权限服务" );
```
- 你也可以使用委托设置参数.
  - 清除默认设置的日志提供程序
```
builder.AsBuild().AddSerilog( t => t.IsClearProviders = true );
```
添加 appsettings 配置节

在 appsettings.json 配置文件添加 Serilog 配置节.
```
{
  "Logging": {
    "LogLevel": {
      "Default": "Trace"
    }
  },
  "Serilog": {
    "WriteTo": [      
      {
        "Name": "Seq",
        "Args": {
          "serverUrl": "http://localhost:5380"
        }
      }
    ]
  }
}
```
WriteTo 指定日志接收器为 Seq.

最简化配置仅需设置 Seq 的服务地址.

本教程 Seq 安装示例使用 5380 端口.

其它参数请参考 Serilog 和 Seq 文档.

查看 Seq

配置完成后,可以启动你的项目,查看 Seq 日志界面.

可以看到由 Asp.Net Core 写入的系统日志.

结构化日志支持

下面的示例比较结构化日志与普通日志的差别.

范例使用 ILog 接口写入日志,你也可以使用 ILogger 替代.

先记录普通日志消息,方便后续比较.

_log.Message( "用户admin已删除" ).LogInformation();

结构化日志语法

{}
- {} 用来定义日志属性.
- 范例:
```
_log.Message( "用户{User}已删除", "admin" ).LogInformation();
```
  {User} 定义了名为 User 的字符串属性.
  
  查看 Seq 操作界面, 可以看到已经添加了 User 属性.
  
  识别出了 User 属性,就可以使用它进行搜索.
  
  点击 User 属性左侧的勾,弹出菜单选择 Find 进行查找.
  
  搜索框设置 User = 'admin' 表达式,表示搜索 User 属性为 admin 的日志.
  
  Seq 不仅能使用 = 进行精确匹配,还支持类似Sql like 的模糊匹配方式.
  
  范例:
```
User like '%dm%'
```
  注意: 不要将结构化日志 {} 与 .Net 字符串语法 $"{}" 混淆.
```
var user = "admin";
_log.Message( $"用户{user}已删除" ).LogInformation();
```
  $"" 中的 {user} 将被 user 变量值 'admin' 替换, 等效于.
```
_log.Message( "用户admin已删除" ).LogInformation();
```
  它仅是普通日志消息,不是结构化日志.
- {@} 用来定义日志属性,并强制序列化对象.
  
  前面的示例使用简单的字符串参数,如果传入对象参数是什么结果?
- 范例:
  
  定义 User 对象.
```
namespace Demo;

public class User {
  public int Id { get; set; }
  public string Name { get; set; }
}
```
  现在传入 User 对象.
```
var user = new User { Id = 1, Name = "a" };
_log.Message( "用户{User}已删除", user ).LogInformation();
```
  {User} 被替换为字符串 "Demo.User" ,这是通过调用 User 对象的 ToString() 方法得到的.
  
  这与我们的预期不符合,我们希望序列化 User 对象,从而获取对象的结构进行搜索.
  
  Serilog 对 {} 参数的处理有一套内置规则,如果传入对象,有些结构能序列化,比如字典 Dictionary<string,int> ,有些则不能.
  
  不应该依赖 Serilog 自动序列化的能力,而是应明确指定是否序列化.
  
  {@} 强制序列化对象,从而保留对象结构,以方便日志系统展示和搜索.
```
var user = new User { Id = 1, Name = "a" };
_log.Message( "用户{@User}已删除", user ).LogInformation();
```
  可以进一步展开对象结构,点击 {Id: 1, Name: 'a'} 左侧的小灯泡,选择 Expand all 展开.
  
  现在可以通过对象属性进行搜索了.
- {$} 用来定义日志属性,并强制字符串化.
  
  {$} 让 Serilog 以明确的方式显示对象的字符串表示.
```
var user = new User { Id = 1, Name = "a" };
_log.Message( "用户{$User}已删除", user ).LogInformation();
```
  {$User} 调用user对象的 ToString() 方法显示为字符串.