.NET 中的日志记录提供程序

项目
06/23/2023

日志提供程序会保留日志，但 Console 提供程序除外，后者仅将日志显示为标准输出。例如，Azure Application Insights 提供程序将日志存储在 Azure Application Insights 中。可以启用多个提供程序。

默认的 .NET 辅助角色应用模板：

使用通用主机。
调用 CreateApplicationBuilder，这将添加以下日志记录提供程序：
- 控制台
- 调试
- EventSource
- EventLog（仅限 Windows）

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

上面的代码显示了使用 .NET 辅助角色应用模板创建的 Program 类。接下来的几个部分提供了一些示例，它们基于使用通用主机的 .NET 辅助角色应用模板。

若要替代 Host.CreateApplicationBuilder 添加的默认日志记录提供程序集，请调用 ClearProviders 并添加所需的日志记录提供程序。例如，以下代码：

调用 ClearProviders 以从生成器中删除所有 ILoggerProvider 实例。
添加控制台日志记录提供程序。

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

有关其他提供程序，请参阅：

内置日志记录提供程序。
第三方日志记录提供程序。

配置依赖于 ILogger 的服务

若要配置依赖于 ILogger<T> 的服务，请使用构造函数注入或提供工厂方法。只有在没有其他选择的情况下，才建议使用工厂方法。例如，假设某个服务需要由 DI 提供的 ILogger<T> 实例：

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExampleService>(
    container => new DefaultExampleService
    {
        Logger = container.GetRequiredService<ILogger<IExampleService>>()
    });

上述代码是 Func<IServiceProvider, IExampleService>，它在 DI 容器首次需要构造 IExampleService 实例时运行。可以用这种方式访问任何已注册的服务。

内置日志记录提供程序

Microsoft 扩展包含以下日志记录提供程序作为运行时库的一部分：

控制台
调试
EventSource
EventLog

以下日志记录提供程序由 Microsoft 提供，但不是运行时库的一部分。它们必须作为附加 NuGet 包安装。

AzureAppServicesFile 和 AzureAppServicesBlob
ApplicationInsights

控制台

Console 提供程序将输出记录到控制台。

调试

Debug 提供程序使用 System.Diagnostics.Debug 类（特别是通过 Debug.WriteLine 方法并且仅在附加调试器时）写入日志输出。 DebugLoggerProvider 创建实现 ILogger 接口的记录器类的实例。

事件来源

EventSource 提供程序写入名称为 Microsoft-Extensions-Logging 的跨平台事件源。在 Windows 上，提供程序使用的是 ETW。

dotnet 跟踪工具

dotnet-trace 工具是一种跨平台 CLI 全局工具，可用于收集正在运行的进程的 .NET Core 跟踪。该工具会使用 LoggingEventSource 收集 Microsoft.Extensions.Logging.EventSource 提供程序数据。

有关安装说明，请参阅 dotnet-trace。有关使用 dotnet-trace 的诊断教程，请查看在 .NET Core 中调试 CPU 使用率高的问题。

Windows 事件日志

EventLog 提供程序将日志输出发送到 Windows 事件日志。与其他提供程序不同，EventLog 提供程序不继承默认的非提供程序设置。如果未指定 EventLog 日志设置，则它们默认为 LogLevel.Warning。

若要记录低于 LogLevel.Warning 的事件，请显式设置日志级别。以下示例将事件日志的默认日志级别设置为 LogLevel.Information：

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog 重载可以传入 EventLogSettings。如果为 null 或未指定，则使用以下默认设置：

LogName：“Application”
SourceName：“.NET Runtime”
MachineName：使用本地计算机名称。

以下代码将 SourceName 从默认值 ".NET Runtime" 更改为 CustomLogs：

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(
    config => config.SourceName = "CustomLogs");

using IHost host = builder.Build();

host.Run();

Azure 应用服务

Microsoft.Extensions.Logging.AzureAppServices 提供程序包将日志写入 Azure App Service 应用的文件系统，以及 Azure 存储帐户中的 blob 存储。

运行时库中不包括该提供程序包。若要使用提供程序，请将提供程序包添加到项目。

要配置提供程序设置，请使用 AzureFileLoggerOptions 和 AzureBlobLoggerOptions，如以下示例所示：

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

部署到 Azure 应用服务时，应用使用 Azure 门户的“应用服务”页面的应用服务日志部分中的设置。更新以下设置后，更改立即生效，无需重启或重新部署应用。

日志文件的默认位置在 D:\home\LogFiles\Application 文件夹中。其他默认值因提供程序而异：

应用程序日志记录（文件系统）：默认文件系统文件名为 diagnostics-yyyymmdd.txt。默认文件大小上限为 10 MB，默认最大保留文件数为 2。
应用程序日志记录 (Blob)：默认 blob 名称为 {app-name}/yyyy/mm/dd/hh/{guid}_applicationLog.txt。

仅当项目在 Azure 环境中运行时，此提供程序才记录日志。

Azure 日志流式处理

Azure 日志流式处理支持从以下位置实时查看日志活动：

应用服务器
Web 服务器
请求跟踪失败

要配置 Azure 日志流式处理，请执行以下操作：

从应用的门户页导航到“应用服务日志”页。
将“应用程序日志记录(Filesystem)”设置为“开” 。
选择日志级别。此设置仅适用于 Azure 日志流式处理。

导航到“日志流”页面以查看日志。记录的消息使用 ILogger 接口进行记录。

Azure Application Insights

Microsoft.Extensions.Logging.ApplicationInsights 提供程序包将日志写入 Azure Application Insights。 Application Insights 是一项服务，可监视 Web 应用并提供用于查询和分析遥测数据的工具。如果使用此提供程序，则可以使用 Application Insights 工具来查询和分析日志。

有关更多信息，请参见以下资源：

Application Insights 概述
.NET Core ILogger 日志的 ApplicationInsightsLoggerProvider - 如果想要在没有其他 Application Insights 遥测的情况下实现日志记录提供程序，请从这里开始。
Application Insights 日志记录适配器。
安装、配置和初始化 Application Insights SDK - Microsoft Learn 网站上的交互式教程。

记录提供程序设计注意事项

如果你计划开发自己的 ILoggerProvider 接口实现和相应的 ILogger 自定义实现，请考虑以下几点：

ILogger.Log 方法是同步方法。
不应假定日志状态和对象的生存期。

ILoggerProvider 的实现将通过其 ILoggerProvider.CreateLogger 方法创建 ILogger。如果实现将日志记录消息以非阻止方式排队，则应首先具体化消息，或将用于具体化日志条目的对象状态序列化。这样做可以避免已释放的对象出现潜在的异常。

有关详细信息，请参阅在 .NET 中实现自定义日志记录提供程序。

第三方日志记录提供程序

下面是适用于 .NET 工作负载的一些第三方日志记录提供程序：

某些第三方框架可以执行语义日志记录（又称结构化日志记录）。

使用第三方框架类似于使用以下内置提供程序之一：

将 NuGet 包添加到你的项目。
调用日志记录框架提供的 ILoggerFactory 或 ILoggingBuilder 扩展方法。

有关详细信息，请参阅各提供程序的相关文档。 Microsoft 不支持第三方日志记录提供程序。

通过