Serilog.Sinks.File 6.0.0

Serilog.Sinks.File

将 Serilog 事件写入一个或多个文本文件。

入门

从 NuGet 安装 Serilog.Sinks.File 包

dotnet add package Serilog.Sinks.File

要在 C# 代码中配置 sink，请在日志配置期间调用 WriteTo.File()

var log = new LoggerConfiguration()
    .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

这将时间周期追加到文件名中，创建一个如下的文件集

log20180631.txt
log20180701.txt
log20180702.txt

注意：默认情况下，一次只有一个进程可以写入日志文件。有关多进程共享的信息，请参阅下方的 共享日志文件。

限制

为了防止应用因磁盘使用量过大而崩溃，文件 sink 默认将文件大小限制在 1GB。达到限制后，直到下一次滚动点（另见下方的 滚动策略）之前，不会写入更多事件。

可以使用 fileSizeLimitBytes 参数更改或删除此限制。

    .WriteTo.File("log.txt", fileSizeLimitBytes: null)

出于同样的原因，默认情况下只保留最近的 31 个文件（即一个月）。要更改或删除此限制，请传递 retainedFileCountLimit 参数。

    .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day, retainedFileCountLimit: null)

滚动策略

要按每天或其他时间周期创建日志文件，请指定如上例所示的 rollingInterval。

要使文件达到 fileSizeLimitBytes 时滚动，请指定 rollOnFileSizeLimit

    .WriteTo.File("log.txt", rollOnFileSizeLimit: true)

这将创建一个如下的文件集

log.txt
log_001.txt
log_002.txt

同时指定 rollingInterval 和 rollOnFileSizeLimit 会应用两个策略，而指定两者均会导致所有事件写入单个文件。

将根据 retainedFileCountLimit 清理旧文件 - 默认为 31。

XML <appSettings> 配置

若要在代码中使用文件 sink 配置 Serilog.Settings.AppSettings 包，如果尚未这么做，请首先安装该包

Install-Package Serilog.Settings.AppSettings

而不是在代码中配置日志记录器，请调用 ReadFrom.AppSettings()

var log = new LoggerConfiguration()
    .ReadFrom.AppSettings()
    .CreateLogger();

在应用程序的 App.config 或 Web.config 文件中，在 <appSettings> 节下指定文件 sink 的程序集和所需的路径格式

<configuration>
  <appSettings>
    <add key="serilog:using:File" value="Serilog.Sinks.File" />
    <add key="serilog:write-to:File.path" value="log.txt" />

可以通过 serilog:write-to:File 键设置的参数是 WriteTo.File() 配置方法接受的参数。这意味着，例如，可以使用以下方式设置 fileSizeLimitBytes 参数：

    <add key="serilog:write-to:File.fileSizeLimitBytes" value="1234567" />

省略 value 会将参数设置为 null

    <add key="serilog:write-to:File.fileSizeLimitBytes" />

在 XML 和 JSON 配置格式中，可以在设置值时使用环境变量。这意味着，例如，日志文件路径可以基于 TMP 或 APPDATA

    <add key="serilog:write-to:File.path" value="%APPDATA%\MyApp\log.txt" />

JSON appsettings.json 配置

若要使用 Microsoft.Extensions.Configuration（如 ASP.NET Core 或 .NET Core）使用文件 sink，请使用 Serilog.Settings.Configuration 包。如果尚未安装，请先安装该包

Install-Package Serilog.Settings.Configuration

而不是直接在代码中配置文件，请调用 ReadFrom.Configuration()

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

var logger = new LoggerConfiguration()
    .ReadFrom.Configuration(configuration)
    .CreateLogger();

在你的 appsettings.json 文件中，在 Serilog 节下

{
  "Serilog": {
    "WriteTo": [
      { "Name": "File", "Args": { "path": "log.txt", "rollingInterval": "Day" } }
    ]
  }
}

请参阅上方的 XML <appSettings> 示例，讨论了可用的 Args 选项。

控制事件格式化

文件 sink 默认以固定文本格式创建事件

2018-07-06 09:02:17.148 +10:00 [INF] HTTP GET / responded 200 in 1994 ms

格式通过使用 输出模板 控制，该模板是文件配置方法接受的作为 outputTemplate 参数。

上述默认格式对应于类似的输出模板

  .WriteTo.File("log.txt",
    outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")

JSON 事件格式化

要将事件写入到文件中，使用其他格式，如 JSON，请传入 ITextFormatter 作为第一个参数

    // Install-Package Serilog.Formatting.Compact
    .WriteTo.File(new CompactJsonFormatter(), "log.txt")

共享日志文件

要启用多进程共享日志文件，将 shared 设置为 true

    .WriteTo.File("log.txt", shared: true)

审计

文件 sink 可通过 AuditTo 作为审计文件运行

    .AuditTo.File("audit.txt")

当前模式下的配置选项仅限于一个有限子集。

性能

默认情况下，文件目标将刷新通过其写入到磁盘的每个事件。为了提高写入性能，指定 buffered: true 将允许底层流缓冲写入。

可以使用 Serilog.Sinks.Async 包来包装文件目标，并在后台工作线程上执行所有磁盘访问。

扩展性

FileLifecycleHooks 提供了一个扩展点，允许挂钩到日志文件生命周期的不同部分。

您可以通过从 FileLifecycleHooks 扩展并重写 OnFileOpened 和/或 OnFileDeleting 方法来创建钩子。

• OnFileOpened 在 Serilog 开始写入事件之前提供对写入日志事件的底层流的访问。您可以利用此功能将您自己的数据写入流（例如，写入标题行），或将流包装在另一个流中（例如，添加缓冲、压缩或加密）

• OnFileDeleting 提供了一种处理已过时的滚动日志文件的方法，在 Serilog 的保留机制删除它们之前 - 例如，将日志文件存档到另一个位置

可用的钩子

• serilog-sinks-file-header：在每份日志文件的开始处写入标题
• serilog-sinks-file-gzip：使用流式 GZIP 压缩在写入日志时压缩日志
• serilog-sinks-file-archive：在 Serilog 的保留机制删除之前存档过时的滚动日志文件

版权所有 © 2016 Serilog 贡献者 - 在 Apache License, Version 2.0 许可下提供。