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

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

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

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 并添加所需的日志记录提供程序。 例如,以下代码:

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 扩展包含以下日志记录提供程序作为运行时库的一部分:

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

控制台

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 存储

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

要配置提供程序设置,请使用 AzureFileLoggerOptionsAzureBlobLoggerOptions,如以下示例所示:

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 工具来查询和分析日志。

有关更多信息,请参见以下资源:

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

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

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

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

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

第三方日志记录提供程序

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

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

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

  1. 将 NuGet 包添加到你的项目。
  2. 调用日志记录框架提供的 ILoggerFactoryILoggingBuilder 扩展方法。

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

另请参阅