Serilog.Sinks.Async 2.0.0

Serilog.Sinks.Async

其他 Serilog 日志输出的异步包装器。使用此输出支持通过将工作委托给后台线程来减少日志调用开销。这对于受 I/O 瓶颈影响的非批量输出支持，如 File 和 RollingFile 输出非常适用。

注意：许多基于网络的输出支持（如 CouchDB、Elasticsearch、MongoDB、Seq、Splunk 等）已经本地实现了异步批量处理，并从这个包装器中获得了益处。

入门指南

从 NuGet 安装

Install-Package Serilog.Sinks.Async

假设您已经安装了目标输出支持，例如文件输出支持，将包装输出支持的配置移动到 WriteTo.Async() 语句中

Log.Logger = new LoggerConfiguration()
    .WriteTo.Async(a => a.File("logs/myapp.log"))
    // Other logger configuration
    .CreateLogger()

Log.Information("This will be written to disk on the worker thread");

// At application shutdown (results in monitors getting StopMonitoring calls)
Log.CloseAndFlush();

在此情况下，包装输出支持（File）将在工作线程上调用，同时您的应用程序线程忙于其他更重要的任务。

由于内存缓冲区可能包含尚未写入目标输出支持的事件，因此当应用程序退出时，重要要调用 Log.CloseAndFlush() 或 Logger.Dispose()。

缓冲和丢弃

默认情况下，向工作线程提供养的内存缓冲区限制为 10,000 个项目，然后到达的事件将被丢弃。要增加或减少此限制，请在配置异步输出支持时指定。可以通过 Serilog.Async.IAsyncLogEventSinkInspector.DroppedMessagesCount（请参阅下方的输出状态检查接口）确定是否已丢弃事件。

// Reduce the buffer to 500 events
.WriteTo.Async(a => a.File("logs/myapp.log"), bufferSize: 500)

通过 Monitor 和 Inspector 接口进行健康监控

Async 包装器主要目的是始终允许以最小的日志延迟进行操作，即使写入的输出支持在处理过程中可能暂时阻塞（例如，File 输出支持可能在刷新时阻塞数毫秒）。丢弃行为是一个重要的安全措施；它避免了在日志吞吐量超过输出支持或输出支持摄取吞吐量下降时出现无限制的缓冲行为。

实际上，此配置（假设为一个适当的 bufferSize 提供资源）实现了一个高效且具有弹性的日志配置，可以安全地处理负载而不影响处理吞吐量。当然，风险是缓冲阈值被超过时事件可能被丢弃。通过配置 Async 输出支持时提供的 IAsyncLogEventSinkMonitor 获取的检查接口 IAsyncLogEventSinkInspector，能够激活验证实际缓冲分配是否未超出。

// Example check: log message to an out of band alarm channel if logging is showing signs of getting overwhelmed
void ExecuteAsyncBufferCheck(IAsyncLogEventSinkInspector inspector)
{
    var usagePct = inspector.Count * 100 / inspector.BufferSize;
    if (usagePct > 50) SelfLog.WriteLine("Log buffer exceeded {0:p0} usage (limit: {1})", usagePct, inspector.BufferSize);
}

class MonitorConfiguration : IAsyncLogEventSinkMonitor
{
    public void StartMonitoring(IAsyncLogEventSinkInspector inspector) =>
        HealthMonitor.AddPeriodicCheck(() => ExecuteAsyncBufferCheck(inspector));

    public void StopMonitoring(IAsyncLogEventSinkInspector inspector) 
    { /* reverse of StartMonitoring */ }
}

// Provide monitor so we can wire the health check to the inspector
var monitor = new MonitorConfiguration();
// Use default config (drop events if >10,000 backlog)
.WriteTo.Async(a => a.File("logs/myapp.log"), monitor: monitor) ...

阻塞

警告：由于通常不希望日志异常泄漏到执行路径中，通常也不希望日志记录器具有中断应用程序处理的副作用，直到日志传播被取消阻塞。

当缓冲区大小达到限制时，默认行为是在队列减轻之前丢弃任何进一步的尝试写入，并将每次此类失败报告给 Serilog.Debugging.SelfLog。要将此替换为阻塞行为，请将 blockWhenFull 设置为 true。

// Wait for any queued event to be accepted by the `File` log before allowing the calling thread to resume its
// application work after a logging call when there are 10,000 LogEvents awaiting ingestion by the pipeline
.WriteTo.Async(a => a.File("logs/myapp.log"), blockWhenFull: true)

XML <appSettings> 和 JSON 配置

使用 Serilog.Settings.Configuration JSON

{
  "Serilog": {
    "WriteTo": [{
      "Name": "Async",
      "Args": {
        "configure": [{
          "Name": "Console"
        }]
      }
    }]
  }
}

尚未为此包装器添加 XML 配置支持。

关于此输出支持

此容器是在以下对话线程中创建的：https://github.com/serilog/serilog/issues/809。