.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 Worker 应用程序模板的示例,这些模板使用通用宿主。

若要替代 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:“应用程序”
  • 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不支持第三方日志记录提供程序。

另请参阅