日志（Serilog）

概述

silky 框架通过 Silky.Logging.Serilog 模块集成 Serilog 作为结构化日志框架。Serilog 提供了丰富的 Sink（输出目标）生态，支持将日志写入控制台、文件、Elasticsearch、Seq 等多种目标，并与 SkyAPM 链路追踪深度集成（在日志中自动注入 TraceId）。

安装

<PackageReference Include="Silky.Logging.Serilog" Version="3.9.1" />

Silky.Logging.Serilog 已包含在 Silky.Agent.Host 中，使用 Silky.Agent.Host 的项目无需单独安装。

快速启用

在 Program.cs 中通过扩展方法一行启用：

var hostBuilder = Host.CreateDefaultBuilder(args)
    .ConfigureSilkyGeneralHostDefaults()
    .UseSerilogDefault();  // 启用 Serilog（默认：Console + File）

await hostBuilder.Build().RunAsync();

UseSerilogDefault() 的默认行为：

读取配置文件中的 Serilog 配置节点（如果存在）
如果配置文件中未配置 Serilog:WriteTo，则自动启用以下两个输出目标：
- Console：以 [HH:mm:ss LVL] Message {Properties} 格式输出到控制台
- File：滚动写入 logs/application.log，按日分割，保留所有历史文件，编码为 UTF-8

通过配置文件自定义日志

推荐通过 appsettings.yaml（或 appsettings.json）配置 Serilog，实现对日志行为的精细控制：

Serilog:
  MinimumLevel:
    Default: Information
    Override:
      Microsoft: Warning
      Microsoft.Hosting.Lifetime: Information
      System: Warning
  WriteTo:
    - Name: Console
      Args:
        outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}"
    - Name: File
      Args:
        path: logs/application.log
        rollingInterval: Day
        retainedFileCountLimit: 30
        outputTemplate: "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} {Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}"
  Enrich:
    - FromLogContext

当配置文件中存在 Serilog:WriteTo 时，UseSerilogDefault() 不再自动添加 Console 和 File 输出，完全使用配置文件中的设置。

自定义日志配置（代码方式）

UseSerilogDefault() 支持传入自定义 Action<LoggerConfiguration> 进行代码级定制：

.UseSerilogDefault(config =>
{
    config
        .WriteTo.Console()
        .WriteTo.File("logs/app.log", rollingInterval: RollingInterval.Day)
        .WriteTo.Seq("http://localhost:5341");  // 写入 Seq 日志服务器
});

集成 Elasticsearch

安装 Serilog.Sinks.Elasticsearch 包后，可将日志写入 Elasticsearch：

Serilog:
  MinimumLevel:
    Default: Information
  WriteTo:
    - Name: Elasticsearch
      Args:
        nodeUris: http://localhost:9200
        indexFormat: silky-logs-{0:yyyy.MM}
        autoRegisterTemplate: true

与 SkyAPM 链路追踪集成

当同时启用 SkyAPM（链路追踪）时，Serilog 会自动从 SkyAPM 的 DiagnosticContext 中获取 TraceId 和 SpanId，并注入到每条日志记录中。

这意味着在 Elasticsearch、Seq 等日志平台中，可以通过 TraceId 直接关联分布式请求链路和日志记录，大幅提高问题排查效率。

配合 SkyAPM 的日志输出格式示例（使用 Serilog.Expressions）：

Serilog:
  WriteTo:
    - Name: Console
      Args:
        formatter: "Serilog.Templates.ExpressionTemplate, Serilog.Templates"
        template: "[{@t:HH:mm:ss} {@l:u3}{#if @tr is not null} ({substring(@tr,0,4)}:{substring(@sp,0,4)}){#end}] {@m}\n{@x}"

其中 @tr 为 TraceId 的前 4 位，@sp 为 SpanId 的前 4 位。

HTTP 请求日志（网关）

在网关（Web 主机）中，Silky.Logging.Serilog 模块会自动通过 UseSerilogRequestLogging() 中间件记录每个 HTTP 请求的简要日志：

[14:32:01 INF] HTTP GET /api/orders/123 responded 200 in 45.6 ms

此功能通过 SerilogStartup 自动注册，无需手动配置。

日志级别配置建议

环境	建议级别	说明
开发（Development）	`Debug`	输出框架内部调试信息
测试（Staging）	`Information`	记录关键业务流程
生产（Production）	`Warning`	减少无效日志，聚焦异常

# 生产环境推荐配置
Serilog:
  MinimumLevel:
    Default: Warning
    Override:
      Silky: Information   # Silky 框架日志保持 Information 级别
      Microsoft.Hosting.Lifetime: Information