C#.NET serilog 详解

唐青枫2025-07-10 8:50

简介

Serilog 是 .NET 平台中非常流行且强大的结构化日志库，其最大特点是"结构化日志记录（Structured Logging）"，支持通过键值对记录丰富的上下文信息，并且拥有强大的 Sink 插件系统，支持写入控制台、文件、数据库、Elasticsearch、Seq 等。

Serilog 核心概念

概念 说明
Logger 日志记录器实例
Sink 日志的输出目标，如 Console、File、Elasticsearch 等
Enrichment 日志信息的丰富，比如自动记录线程ID、机器名等上下文信息
Filter 日志的筛选器
Structured Logging 日志以键值对形式记录，便于搜索和分析

安装 Serilog（NuGet 包）

shell 复制代码 
dotnet add package Serilog.AspNetCore
dotnet add package Serilog.Sinks.Console
dotnet add package Serilog.Sinks.File
dotnet add package Serilog.Sinks.Async

基础配置示例

csharp 复制代码 
using Serilog;

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("Logs/log.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

try
{
    Log.Information("Starting up");
    // 启动主程序或 ASP.NET Core 应用
}
catch (Exception ex)
{
    Log.Fatal(ex, "Application start-up failed");
}
finally
{
    Log.CloseAndFlush();
}

ASP.NET Core 集成方式

csharp 复制代码 
using Serilog;

var builder = WebApplication.CreateBuilder(args);

// 配置 Serilog 替换默认日志
Log.Logger = new LoggerConfiguration()
    .ReadFrom.Configuration(builder.Configuration)
    .Enrich.FromLogContext()
    .WriteTo.Console()
    .WriteTo.File("Logs/log-.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

builder.Host.UseSerilog(); // 使用 Serilog

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

appsettings.json 配置方式

json 复制代码 
"Serilog": {
  "Using": [ "Serilog.Sinks.Console", "Serilog.Sinks.File" ],
  "MinimumLevel": {
    "Default": "Information",
    "Override": {
      "Microsoft": "Warning",
      "System": "Warning"
    }
  },
  "Enrich": [ "FromLogContext", "WithThreadId" ],
  "WriteTo": [
    {
      "Name": "Console"
    },
    {
      "Name": "File",
      "Args": {
        "path": "Logs/log-.txt",
        "rollingInterval": "Day",
        "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}"
      }
    }
  ]
}

配合 NuGet 包：

shell 复制代码 
dotnet add package Serilog.Settings.Configuration

Serilog Sink 示例

Sink 名称 说明
Serilog.Sinks.Console 输出到控制台
Serilog.Sinks.File 输出到文件
Serilog.Sinks.Seq 输出到 Seq 可视化平台
Serilog.Sinks.Elasticsearch 输出到 Elasticsearch
Serilog.Sinks.Async 异步包装器
Serilog.Sinks.MSSqlServer 写入 SQL Server

基本用法

基本结构化日志

csharp 复制代码 
var orderId = 123;
var customerId = 456;

// 结构化日志记录
Log.Information("处理订单 {OrderId} 来自客户 {CustomerId}", orderId, customerId);

// 输出示例（JSON 格式）：
// {
//   "OrderId": 123,
//   "CustomerId": 456,
//   "Message": "处理订单 123 来自客户 456",
//   "Level": "Information"
// }

复杂对象序列化

csharp 复制代码 
var order = new Order { Id = 123, Products = new List<string> { "Book", "Pen" } };
Log.Information("创建订单 {@Order}", order);
// 输出: 创建订单 {"Id": 123, "Products": ["Book", "Pen"]}

上下文丰富（Enrichers）

csharp 复制代码 
// 为当前作用域添加属性
using (LogContext.PushProperty("RequestId", Guid.NewGuid()))
{
    Log.Information("处理请求");
    // 所有日志自动附加 RequestId 属性
}
csharp 复制代码 
// 添加全局属性
Log.Logger = new LoggerConfiguration()
    .Enrich.WithMachineName()
    .Enrich.WithEnvironmentUserName()
    .CreateLogger();

// 添加临时上下文
using (LogContext.PushProperty("RequestId", Guid.NewGuid())) {
    Log.Information("处理请求");
}

常用 Enrichers

csharp 复制代码 
.Enrich.WithProperty("AppVersion", "1.0.0")
.Enrich.FromLogContext()
.Enrich.WithThreadId()

文件滚动

按日期或大小滚动日志文件：

csharp 复制代码 
.WriteTo.File("logs/app-.log",
    rollingInterval: RollingInterval.Day,
    fileSizeLimitBytes: 10_000_000,
    retainedFileCountLimit: 30)

  • rollingInterval：按天滚动。

  • fileSizeLimitBytes：限制文件大小（10MB）。

  • retainedFileCountLimit：保留 30 个文件。

数据库 Sink

shell 复制代码 
dotnet add package Serilog.Sinks.MSSqlServer
csharp 复制代码 
.WriteTo.MSSqlServer(
    connectionString: "Server=.;Database=Logs;Trusted_Connection=True;",
    sinkOptions: new MSSqlServerSinkOptions { TableName = "Logs" })

过滤日志

通过过滤器控制日志：

csharp 复制代码 
.Filter.ByExcluding(logEvent => logEvent.Properties.ContainsKey("SensitiveData"))

JSON 配置

json 复制代码 
"Filter": [
  {
    "Name": "ByExcluding",
    "Args": {
      "expression": "SourceContext = 'Microsoft.*'"
    }
  }
]

配置 HTTP 上下文：

高级用法

动态日志级别

csharp 复制代码 
var levelSwitch = new LoggingLevelSwitch(LogEventLevel.Information);

Log.Logger = new LoggerConfiguration()
    .MinimumLevel.ControlledBy(levelSwitch)
    .WriteTo.Console()
    .CreateLogger();

// 运行时调整级别
levelSwitch.MinimumLevel = LogEventLevel.Debug;

自定义输出模板

csharp 复制代码 
.WriteTo.Console(outputTemplate:
    "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} {Properties}{NewLine}{Exception}")

错误日志特殊处理

csharp 复制代码 
.WriteTo.Logger(lc => lc
    .Filter.ByIncludingOnly(e => e.Level == LogEventLevel.Error)
    .WriteTo.File("logs/errors.txt"))

请求日志中间件

csharp 复制代码 
app.UseSerilogRequestLogging(options => 
{
    options.EnrichDiagnosticContext = (diagnosticContext, httpContext) =>
    {
        diagnosticContext.Set("User", httpContext.User.Identity.Name);
        diagnosticContext.Set("ClientIP", httpContext.Connection.RemoteIpAddress);
    };
});

异步日志

csharp 复制代码 
.WriteTo.Async(a => a.File("logs/async.log"))

批量写入

csharp 复制代码 
// 使用 PeriodicBatchingSink 实现批处理
Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.PeriodicBatchingSink(
        new HttpSink("https://logserver/api/logs"),
        batchSizeLimit: 100,
        period: TimeSpan.FromSeconds(2))
    .CreateLogger();

使用配置文件初始化

csharp 复制代码 
using Serilog;
using Serilog.Settings.Configuration;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

Log.Logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration)
    .CreateLogger();

条件性日志记录

csharp 复制代码 
Log.Logger = new LoggerConfiguration()
    .WriteTo.Logger(lc => lc
        .Filter.ByIncludingOnly(e => e.Level == LogEventLevel.Error)
        .WriteTo.File("logs/errors.log"))
    .WriteTo.Logger(lc => lc
        .Filter.ByIncludingOnly(e => e.Level == LogEventLevel.Information)
        .WriteTo.Console())
    .CreateLogger();

级别动态控制

csharp 复制代码 
.MinimumLevel.Override("Microsoft", LogEventLevel.Warning)  // 抑制第三方库日志

轻量级序列化

csharp 复制代码 
.WriteTo.File(new CompactJsonFormatter(), "logs/compact.json")  // 节省存储

异步批处理配置

csharp 复制代码 
.WriteTo.Async(a => a.Elasticsearch(), batchSize: 1000)

参数调优：

  • batchSize：根据网络延迟调整（建议 500-5000）

  • blockWhenFull：队列满时阻塞而非丢弃

零分配渲染（ZeroAllocation）

csharp 复制代码 
var log = new LoggerConfiguration()
    .Destructure.ByTransforming<User>(u => new { u.Id, u.Name })
    .CreateLogger();

// 避免 ToString() 分配
Log.Information("用户 {@User} 登录", user);

自定义 Sink 开发

csharp 复制代码 
public class CustomSink : ILogEventSink {
    public void Emit(LogEvent logEvent) {
        var json = JsonConvert.SerializeObject(logEvent.Properties);
        SendToQueue(queue, json); // 写入消息队列
    }
}
// 注册
.WriteTo.Sink(new CustomSink())

故障转移机制

csharp 复制代码 
.WriteTo.Conditional(
    e => IsElasticAlive(), 
    wt => wt.Elasticsearch(), 
    wt => wt.File("fallback.log")
)

过滤日志

通过过滤器控制日志

csharp 复制代码 
.Filter.ByExcluding(logEvent => logEvent.Properties.ContainsKey("SensitiveData"))

JSON 配置

json 复制代码 
"Filter": [
  {
    "Name": "ByExcluding",
    "Args": {
      "expression": "SourceContext = 'Microsoft.*'"
    }
  }
]
相关推荐
吃一碗粉只付一碗钱9 小时前
16-SqlSugar多库ConfigId与按实体选连接
sqlserver·c#
rockey62711 小时前
AScript之字符串模板
c#·.net·script·expression·动态脚本
will_net12 小时前
Redis集群部署+Redis 链接地址放入Aollo +c#项目接入Redis
redis·c#·bootstrap
BuHuaX19 小时前
Lua 与 ToLua：运行机制及热更新原理
开发语言·unity·junit·c#·lua
asdzx6719 小时前
C# 操作 PDF 元数据：从属性写入到字段提取的完整流程
前端·pdf·c#
玩泥巴的20 小时前
源生成与 AOT 就绪的微信生态 .NET SDK：结构、能力边界与 API 定位方法
ai·微信·.net·agent·aot·roslyn
氷凌公子21 小时前
算法与UI拆分中遇到的问题及解决方式
c#·onnx·yolov26
1-1=021 小时前
C# 泛型
c#·.net·.netcore
有志冬瓜1 天前
.NET Framework全部版本离线下载安装教程
安全·.net·软件需求
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03历年考研数学一、数学二、数学三真题试卷及答案PDF04几个好用的ip纯净度检测网站05苹果iPA游戏软件资源下载网站06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07如何新建文件夹？ 电脑新建文件夹的4种方法08昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战09Dify：一站式AI应用开发平台全解析与Windows部署指南10Android 屏幕适配系列开篇：核心概念、官方机制与主流方案