Serilog 是一款面向 .NET 生态、以结构化日志事件为核心模型、基于插件化 Sink 架构的高性能日志采集与分发组件，采用模板解析 + 属性提取实现语义化日志，支持多输出目标、动态上下文与运行时配置。
Serilog 基于日志事件模型重构整个日志链路，以实现结构化、扩展性、上下文传递、多环境配置等能力，从而适配现代 .NET 桌面、Web、微服务全场景。
能力场景
| 核心能力 | 适用场景 |
|---|---|
| 结构化日志事件 + 消息模板解析 | 业务日志分析、日志检索、ELK/Graylog 日志栈、WPF / 桌面客户端审计 |
| 插件化 Sink 多输出分发 | 同时输出控制台、本地文件、数据库、第三方日志服务 |
| LogContext 动态上下文传递 | WPF 多窗口、多线程任务、ASP.NET 请求链路追踪 |
| Enricher 全局属性注入 | 统一附加机器名、进程 ID、环境标识等元数据 |
| 代码 / 配置文件双模式配置 | 多环境部署、CI/CD 流水线、生产环境动态调参 |
架构与流程
架构图
| 模块名称 | 核心职责 | 输入输出 |
|---|---|---|
| Logger | 全局日志入口，校验级别、初始化链路 | 日志级别、模板、参数、异常； 输出 LogEvent |
| LogEvent | 日志核心数据模型，承载全量日志元数据 | 时间戳、级别、消息、属性、异常； 结构化实体 |
| Enricher | 批量追加全局 / 上下文属性 | LogEvent； 附加属性后的 LogEvent |
| Filter | 按级别 / 属性过滤日志事件 | LogEvent； 通过 / 拦截的 LogEvent |
| Sink | 日志最终输出实现，各类目标适配器 | LogEvent； 落地至对应存储 / 终端 |
核心执行时序
原理与设计
关键抽象
- LogEvent 结构化数据模型——Serilog 最核心的抽象，摒弃传统字符串日志，使用强类型实体承载所有日志信息：
- 包含
Timestamp（时间戳）、LogEventLevel（日志级别）、MessageTemplate（消息模板）、Properties（键值对属性字典）、Exception（异常堆栈）。 - 所有链路均围绕该实体流转，是结构化分析的基础。
- 属性字典采用哈希表实现，读写时间复杂度 O(1)，保证高并发下属性存取性能。
- 包含
- 消息模板解析机制——内置专用模板解析器，区分普通占位符
{Key}、深度序列化{@Key}、字符串化{$Key}。- 解析阶段在日志事件构建时完成，而非输出阶段，避免多 Sink 重复解析；
- 解析过程采用词法扫描，无正则表达式开销，降低 CPU 占用。
- Sink 插件架构 + 分发模型——基于
ILogEventSink单一接口实现插件化，所有输出目标均实现该接口，遵循接口隔离原则。- 核心调度器采用广播分发：一条 LogEvent 会分发给所有注册的 Sink，各 Sink 独立处理。
- 主流 Sink（文件、控制台）内置异步缓冲队列，采用生产者 - 消费者模型，实现 IO 操作解耦业务线程，避免磁盘 / 网络 IO 阻塞主线程（WPF UI 线程尤为关键）。
- LogContext 上下文栈机制与异步分发机制——采用栈结构存储临时属性，
PushProperty入栈，using语句结束自动出栈，天然适配代码作用域。- 栈结构保证上下文作用域的层级隔离，多线程下使用线程本地存储（TLS）隔离栈数据，避免线程间上下文串扰，完美适配 WPF 多窗口、后台线程场景。
- 日志级别覆盖机制——支持全局默认级别 + 命名空间级别重写，内部使用前缀匹配规则树，快速匹配日志来源命名空间，实现精细化日志过滤，减少无效日志流转。
源码地图
基于 Serilog 主仓库（serilog/serilog）精简目录与核心文件：
Serilog/ ├── Core/ │ ├── LogEvent.cs # 核心数据模型，承载所有日志字段与属性 │ ├── LogEventLevel.cs # 日志级别枚举定义 │ ├── ILogEventSink.cs # Sink 统一扩展接口，插件体系根基 │ └── LogContext.cs # 线程上下文栈实现，作用域属性管理 ├── Configuration/ │ └── LoggerConfiguration.cs # 日志构建器，所有配置、链路组装入口 ├── Events/ │ └── MessageTemplate.cs # 消息模板解析、属性提取核心实现 └── Log.cs # 全局静态入口类，对外暴露所有日志 APILogEvent.cs：整个组件的数据基石，定义日志的标准形态，所有流转数据均为此类型；LoggerConfiguration.cs：建造者模式实现配置链路，串联 Enricher、Filter、Sink，是初始化核心；MessageTemplate.cs：实现模板解析与对象序列化，决定结构化能力的底层逻辑；ILogEventSink.cs：扩展体系的接口规范，所有自定义输出、UI 日志均基于此接口；LogContext.cs：上下文传递核心，解决多线程、多作用域日志追踪问题。
API 介绍
常用 API
| API 名称 | 核心参数 | 功能说明 |
|---|---|---|
LoggerConfiguration() | 无 | 建造者入口，开始组装日志链路 |
MinimumLevel() | LogEventLevel | 设置全局最低日志级别，低于级别直接丢弃 |
Enrich.FromLogContext() | 无 | 启用线程上下文属性自动注入 |
Enrich.WithXXX() | 静态属性值 | 注入机器名、进程 ID 等全局元数据 |
WriteTo.Sink() | ILogEventSink 实例 | 注册自定义 / 官方输出 Sink |
Log.XXX(string template, params object[] props) | 模板字符串、动态参数< |
