在 ABP VNext 中集成 Serilog：打造可观测、结构化日志系统

🚀 在 ABP VNext 中集成 Serilog：打造可观测、结构化日志系统

---

---

1. 为什么要使用结构化日志？ 🤔

相比于简单的文本日志，结构化日志有以下优势：

• ❌ 传统文本日志无法根据 TraceId、UserId 等字段方便地检索
• ❌ 无法像 SQL 那样对日志字段进行过滤与聚合
• ❌ 不易在可视化平台（如 Kibana、Seq、Grafana Loki）上进行联动分析

而 Serilog 以原生的 JSON 日志形式输出，能够轻松处理上下文、分析调用链，方便与 ELK / Seq / Loki 等平台集成，做到精准定位故障点。

---

2. 核心集成步骤 🛠

步骤	内容
1⃣️	安装 Volo.Abp.AspNetCore.Serilog 包
2⃣️	配置 Serilog Sink（Console、File、Seq、Elasticsearch、Loki）
3⃣️	在 Program.cs 中初始化 Serilog
4⃣️	在 ABP 模块中启用 UseAbpSerilogEnrichers() 插入上下文

2.1 流程图示例

• 通过 “Enrichers” 阶段，可以自动将 TraceId、UserId、MachineName 等信息注入到每条日志。

---

3. NuGet 包安装 📦

在项目根目录下执行以下命令，添加所需依赖包。为了避免版本不一致，建议指定版本号：

dotnet add package Volo.Abp.AspNetCore.Serilog 
dotnet add package Serilog.Sinks.Console          
dotnet add package Serilog.Sinks.File              
dotnet add package Serilog.Sinks.Seq               
dotnet add package Serilog.Sinks.Elasticsearch     # 如想支持 Grafana Loki：
dotnet add package Serilog.Sinks.Grafana.Loki      

---

4. appsettings.json 配置 📝

在 appsettings.json 文件中，添加或修改 Serilog 节点，如下所示：

{"Serilog": {"Using": ["Serilog.Sinks.Console","Serilog.Sinks.File","Serilog.Sinks.Seq","Serilog.Sinks.Elasticsearch","Serilog.Sinks.Grafana.Loki"],"MinimumLevel": {"Default": "Information","Override": {"Microsoft": "Warning","Microsoft.EntityFrameworkCore": "Error","Volo.Abp": "Information"}},"WriteTo": [{"Name": "Console"},{"Name": "File","Args": {"path":                 "Logs/log-.log","rollingInterval":      "Day","retainedFileCountLimit": 14,"fileSizeLimitBytes":   104857600,"buffered":             true,"flushToDiskInterval":  "00:00:05"}},{"Name": "Seq","Args": {"serverUrl": "http://localhost:5341"}},{"Name": "Elasticsearch","Args": {"nodeUris":                  "http://localhost:9200","indexFormat":               "myapp-logs-{0:yyyy.MM.dd}","autoRegisterTemplate":      true,"autoRegisterTemplateVersion": "ESv7","numberOfReplicas":          1,"numberOfShards":            5,"batchPostingLimit":         50,"period":                    "00:00:05","failureCallback":           "e => Console.WriteLine(\"Unable to submit event to Elasticsearch: \" + e.Message)"}},{"Name": "GrafanaLoki","Args": {"uri":                 "http://localhost:3100/loki/api/v1/push","batchPostingLimit":   50,"period":              "00:00:05","labels":              "{\"Application\":\"MyAbpApp\",\"Environment\":\"${env:ASPNETCORE_ENVIRONMENT}\"}"}}],"Enrich": ["FromLogContext","WithMachineName","WithThreadId","WithEnvironmentName"]}
}

• Using：要加载的 Sink 包列表，包括 Console、File、Seq、Elasticsearch、Grafana Loki。
• MinimumLevel：全局最低日志级别及对各命名空间的 Override。
• WriteTo：各个输出通道的配置：
  • 📟 Console：控制台直接输出，适合开发与容器模式下采集标准输出。
  • 📂 File：写入本地文件，rollingInterval: Day 按天滚动；retainedFileCountLimit: 14 最多保留 14 天日志；fileSizeLimitBytes: 100MB，超出则滚动。
  • 📊 Seq：访问地址为 http://localhost:5341 的本地 Seq 服务。
  • 🔍 Elasticsearch：连接到 http://localhost:9200，索引名称按天命名；批量发送 50 条 / 5 秒；失败回调打印到控制台。
  • 📈 GrafanaLoki：连接本地 Loki（端口 3100）并打上标签，一旦在 Grafana 中按标签筛选，方便定位。
• Enrich：注入常见上下文字段（如 TraceId、MachineName、ThreadId、Environment）。

Tip：如需在开发/生产环境区分配置，可分别在 appsettings.Development.json 和 appsettings.Production.json 中覆盖 MinimumLevel 与 WriteTo 节点。例如：

• Development：将 MinimumLevel.Default 设置为 Debug，仅启用 Console Sink；
• Production：将 MinimumLevel.Default 设置为 Information，启用 File、Seq、Elasticsearch、Loki Sink；并关闭 Console 输出以减少 I/O 压力。

---

5. Program.cs 全局日志初始化 💻

在 Program.cs 文件里，使用 Serilog 提供的“Bootstrap Logger”+“配置读取”模版，示例如下：

using System;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Serilog;
using Volo.Abp.Serilog;namespace MyAbpApp
{public class Program{public static async Task Main(string[] args){// 1. 创建 Bootstrap Logger（只输出到 Console，用于捕获最早期的日志）Log.Logger = new LoggerConfiguration().MinimumLevel.Override("Microsoft", Serilog.Events.LogEventLevel.Warning).WriteTo.Console().CreateBootstrapLogger();try{// 2. 构建 Host 并读取 appsettings.json 中的 Serilog 配置var builder = WebApplication.CreateBuilder(args);builder.Host.UseSerilog((ctx, services, config) =>{config.ReadFrom.Configuration(ctx.Configuration)    // 读取 appsettings.json 的 Serilog 设置.ReadFrom.Services(services)                  // 读取 DI 容器中注册的 ILogEventEnricher.Enrich.FromLogContext()                      // 从 LogContext 拉取附加属性.Enrich.WithProperty("Application", "MyAbpApp").Enrich.WithProperty("Environment", ctx.HostingEnvironment.EnvironmentName);});// 3. 添加 ABP 应用及所需模块builder.Services.AddApplication<MyAbpAppModule>();// 4. 构建应用var app = builder.Build();// 5. 注入 Serilog Enrichers（TraceId、UserId、TenantId 等）app.UseAbpSerilogEnrichers();// 6. 初始化 ABP 模块（包括 Routing、Authentication、Authorization 等）await app.InitializeApplicationAsync();// 7. 启动 HTTP 服务并阻塞await app.RunAsync();}catch (Exception ex){// 8. 捕获主机启动时的异常并记录 Fatal 日志Log.Fatal(ex, "Application start-up failed");Environment.ExitCode = 1;}finally{// 9. 应用退出时刷新并关闭日志Log.CloseAndFlush();}}}
}

5.1 代码流程图

• 该图展示了 Program.cs 中从 Main 开始，到最终应用启动并接收请求，日志如何一步步初始化并插入上下文的执行路径。

---

6. ABP 模块注册 🏗

在 MyAbpAppModule.cs 中声明所需的依赖模块，例如：

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Serilog;
using Volo.Abp;
using Volo.Abp.AspNetCore.Mvc;
using Volo.Abp.AspNetCore.Serilog;
using Volo.Abp.BackgroundWorkers;
using Volo.Abp.DistributedEventBus;
using Volo.Abp.Modularity;
using Volo.Abp.TenantManagement;namespace MyAbpApp
{[DependsOn(typeof(AbpAspNetCoreSerilogModule),    // Serilog 集成模块typeof(AbpAspNetCoreMvcModule),        // MVC/Web API 基础模块typeof(AbpBackgroundWorkersModule),    // 后台任务模块（示例）typeof(AbpDistributedEventBusModule),  // 分布式事件总线模块（示例）typeof(AbpTenantManagementModule)      // 多租户管理模块（如需多租户场景）)]public class MyAbpAppModule : AbpModule{public override void OnApplicationInitialization(ApplicationInitializationContext context){var logger = context.ServiceProvider.GetRequiredService<ILogger<MyAbpAppModule>>();logger.LogInformation("🔥 ABP 模块已启动！");}public override void OnApplicationShutdown(ApplicationShutdownContext context){var logger = context.ServiceProvider.GetRequiredService<ILogger<MyAbpAppModule>>();logger.LogInformation("💤 ABP 模块已关闭！");}}
}

• 说明：
  1. AbpAspNetCoreSerilogModule 会将 ABP 框架内部的日志重定向到 Serilog。
  2. 如果您的业务需要后台任务或分布式事件，请在 DependsOn 一并引入对应模块。
  3. 如果项目启用多租户，一定要引入 AbpTenantManagementModule 等租户相关模块。
  4. 在 OnApplicationInitialization 中写一条“ABP 模块已启动”日志方便确认模块加载成功；在 OnApplicationShutdown 中写一条“ABP 模块已关闭”日志方便确认优雅退出。

---

7. 上下文信息添加 🧩

7.1 UseAbpSerilogEnrichers() 自动插入

在 Program.cs 中调用 app.UseAbpSerilogEnrichers(); 后，Serilog 会自动注入以下常见上下文字段到每条日志中：

• 🔗 TraceId：分布式链路追踪 ID（需配合 OpenTelemetry/Jaeger 等链路追踪服务）
• 👤 UserId、UserName：当前登录用户信息（需在请求上下文中有认证信息）
• 🏷️ TenantId：当前多租户系统的租户 ID（如启用了多租户模块）
• 🖥️ MachineName：主机名称（适用于集群调试）
• 🧵 ThreadId：线程 ID（方便定位多线程日志）
• 🌐 Environment：部署环境（如 Development、Production）

注意：UseAbpSerilogEnrichers() 必须放在 UseRouting() 之后、UseAuthentication() 之前；如果您使用 ABP 脚手架模板，则无需手动调用中间件顺序，InitializeApplicationAsync() 已自动处理。

7.2 LogContext.PushProperty 自定义属性

在业务代码里，如果需要在单次请求或某个操作中，对特定实体（如 Order）添加自定义属性，可以使用 LogContext.PushProperty(...)，示例如下：

using Serilog;
using Serilog.Context;
using Microsoft.Extensions.Logging;public class OrderService
{private readonly ILogger<OrderService> _logger;public OrderService(ILogger<OrderService> logger){_logger = logger;}public void ProcessOrder(Order order){// 在这个 using 块内，所有日志都会带上 OrderId 属性using (LogContext.PushProperty("OrderId", order.Id)){_logger.LogInformation("✅ Processing order {@Order}", order);// … 其它业务逻辑_logger.LogWarning("⚠️ Order {@Order} took too long to process", order);}}
}

• 说明：
  1. LogContext.PushProperty("OrderId", order.Id) 会在当前上下文中将 OrderId 写入所有后续日志。
  2. 使用 {@Order} 这种序列化写法，会把 Order 对象的所有字段写到 JSON 中，方便在 ES/Kibana/Loki 中查看结构化数据。
  3. 在控制台或日志平台中，该条日志会像：

     {"Timestamp": "2025-05-31T20:00:00.0000000Z","Level": "Information","MessageTemplate": "✅ Processing order {@Order}","Properties": {"OrderId": 12345,"Order": { "Id": 12345, "Amount": 99.99, "CustomerId": 67890 },"TraceId": "abcdef1234567890","UserId": 42,"TenantId": 1,"MachineName": "server01","ThreadId": 12,"Environment": "Production"}
     }
     

---

8. 对接平台：Seq & ELK & Grafana Loki 🌐

8.1 部署 Seq（推荐开发阶段）

docker run -d \-p 5341:80 \-v seq_data:/data \datalust/seq

• 说明：
  1. -p 5341:80 将容器 80 端口映射到宿主机 5341 端口；访问地址为 http://localhost:5341
  2. -v seq_data:/data 挂载一个 Docker 卷，用于持久化 Seq 数据；容器重启后数据依然保留。
  3. 启动后，可在 Seq Web 界面里创建 Dashboard，使用筛选条件（如 @l = "Error" 或 @t >= "2025-05-01"）进行日志定位。

8.2 部署 ELK（推荐生产环境）

创建一个 docker-compose.yml 文件，内容如下：

version: '3.7'volumes:es_data:kibana_data:services:elasticsearch:image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0container_name: elasticsearchenvironment:- node.name=es-node-1- discovery.type=single-node- xpack.security.enabled=false- ES_JAVA_OPTS=-Xms1g -Xmx1gvolumes:- es_data:/usr/share/elasticsearch/dataports:- 9200:9200kibana:image: docker.elastic.co/kibana/kibana:7.17.0container_name: kibanaenvironment:- ELASTICSEARCH_HOSTS=http://elasticsearch:9200volumes:- kibana_data:/usr/share/kibana/dataports:- 5601:5601depends_on:- elasticsearch

运行：

docker-compose up -d

• 说明：
  1. Elasticsearch
     • 挂载 es_data 卷用以持久化数据；
     • 设置 JVM 堆大小为 1G（ES_JAVA_OPTS=-Xms1g -Xmx1g），生产环境可根据节点内存调整；
     • 关闭 X-Pack 安全认证方便本地测试；
  2. Kibana
     • 指定 ELASTICSEARCH_HOSTS 以连接 Elasticsearch；
     • 挂载 kibana_data 用于持久化 Kibana 配置；
     • 启动后访问 http://localhost:5601 即可登录；

8.2.1 在 Kibana 中创建 Index Pattern 🔍

1. 打开 Kibana → 左侧菜单 “Management” → “Index Patterns” → “Create index pattern”。
2. 在 “Index pattern name” 中输入 myapp-logs-*，点击 “Next step”。
3. 选择时间字段（如 @timestamp）后点击 “Create index pattern”。
4. 在 “Discover” 页面就能看到所有符合 myapp-logs-2025.05.XX 格式的索引，日志字段会以 JSON 形式展示，可以按字段进行过滤、排序、聚合。

提示：为了更直观地展示 Kibana 中的日志分组和聚合效果，可以创建一个简单的 Dashboard，比如“日志级别分布图”、“每小时错误请求数统计”等。这样在生产环境排查问题时，更加快捷。

8.3 对接 Grafana Loki（可选）🔗

如果您使用 Grafana Loki 作为日志收集平台，可参考以下步骤：

1. 部署 Loki

   • 推荐使用 Loki 官方提供的 docker-compose.yml 或者 Helm Chart。
   • 简单示例（仅做测试用）：

     version: '3.7'
     services:loki:image: grafana/loki:2.7.1container_name: lokicommand: -config.file=/etc/loki/local-config.yamlports:- 3100:3100promtail:image: grafana/promtail:2.7.1container_name: promtailvolumes:- /var/log:/var/log- ./promtail-config.yaml:/etc/promtail/config.yamlcommand: -config.file=/etc/promtail/config.yaml
     

   2. 在 promtail-config.yaml 中，配置读取应用输出到标准输出（Console Sink）的日志，并推送到 Loki。
   3. 在 Grafana 中添加 Loki 数据源，创建 Dashboard 时选择 Loki 数据源即可查询 MyAbpApp 相关日志。

2. GrafanaLoki Sink 配置示例
   已在第四节的 appsettings.json 中给出完整配置。再次回顾重点字段：

   {"Name": "GrafanaLoki","Args": {"uri": "http://localhost:3100/loki/api/v1/push","batchPostingLimit": 50,"period": "00:00:05","labels": "{\"Application\":\"MyAbpApp\",\"Environment\":\"Production\"}"}
   }
   

   • uri：Loki 的 Push API 地址；
   • batchPostingLimit、period：控制批量推送频率；
   • labels：为日志打上标签，便于在 Grafana 中按标签筛选。

注意：在容器化环境下，将 uri 指向 Loki Service（如 http://loki:3100/loki/api/v1/push），不要使用 localhost。

---

9. 总结 📋

• 🚀 性能：

  • 支持 buffered 与 flushToDiskInterval 控制文件写入 IO，平衡延迟与吞吐；
  • Elasticsearch Sink 中可配置 batchPostingLimit 和 period，避免过于频繁的小批量请求。

• 📈 规模：

  • 支持日志按天滚动（rollingInterval: Day）和限制单文件大小（fileSizeLimitBytes），通过 retainedFileCountLimit 最多保留 14 天历史，防止磁盘耗尽。

• 🎨 可视化：

  • 结构化 JSON 日志让 Seq/Kibana/Loki 能以字段形式展示，可按字段、日期、级别精准搜索和聚合统计，大幅提升故障排查效率。

• 🔧 可配置：

  • 通过 appsettings.Development.json 与 appsettings.Production.json 差异化配置，可在不同环境灵活切换最小日志级别与输出通道。
  • 支持自定义 Enrichers 和 Sink，能够将任意业务上下文（如 OrderId、ProductId、TraceId 等）注入到日志中。

• 🐳 容器化注意：

  • 如果服务跑在 Docker 或 Kubernetes，推荐保留 Console Sink 输出，通过容器平台日志采集（如 Fluentd、Filebeat、堆栈驱动）统一收集。
  • 若仍需写入日志文件，请确保挂载 Volume 以避免容器磁盘耗尽。
  • 根据目标平台（Seq、Elasticsearch、Loki）是否开启安全认证，需在对应 Sink 的 Args 中添加凭证信息（用户名、密码或 API Key）。

---

📎 推荐阅读 📚

• ABP Serilog 模块文档
• Serilog 官方文档
• Seq 可视化平台
• Grafana Loki 文档

---