Provedores de log no .NET

  • Artigo

Os provedores de registro em log persistem logs, exceto o provedor Console, que apenas exibe logs como saída padrão. Por exemplo, o provedor do Azure Application Insights armazena logs no Azure Application Insights. Vários provedores podem ser habilitados.

Os modelos de aplicativo padrão do Worker do .NET:

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

O código anterior mostra a classe Program criada com os modelos de aplicativo do Worker do .NET. As próximas seções fornecem exemplos baseados nos modelos de aplicativo do Worker do .NET, que usam o Host Genérico.

Para substituir o conjunto padrão de provedores de registro em log adicionados por Host.CreateApplicationBuilder, chame ClearProviders e adicione os provedores de registro em log desejados. Por exemplo, o código a seguir:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

Para provedores adicionais, consulte:

Configurar um serviço que depende do ILogger

Para configurar um serviço que depende de ILogger<T>, use a injeção de construtor ou forneça um método de fábrica. A abordagem do método de fábrica é recomendada somente se não há nenhuma outra opção. Por exemplo, considere um serviço que precisa de uma instância de ILogger<T> fornecida pelo DI:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

O código anterior é um Func<IServiceProvider, IExampleService> que é executado na primeira vez que o contêiner de DI precisa construir uma instância de IExampleService. Você pode acessar qualquer um dos serviços registrados dessa maneira.

Provedores de log internos

As Extensões da Microsoft incluem os seguintes provedores de registro em log como parte das bibliotecas de runtime:

Os provedores de registro em log a seguir são fornecidos pela Microsoft, mas não como parte das bibliotecas de runtime. Eles devem ser instalados como pacotes NuGet adicionais.

Console

O provedor Console registra a saída no console.

Depurar

O provedor Debug grava a saída de log usando a classe System.Diagnostics.Debug, especificamente por meio do método Debug.WriteLine e somente quando o depurador está anexado. O DebugLoggerProvider cria instâncias de uma classe de agente que implementa a interface do ILogger.

Origem do Evento

O provedor EventSource grava em uma origem do evento multiplataforma com o nome Microsoft-Extensions-Logging. No Windows, o provedor usa ETW.

Ferramentas de rastreamento dotnet

A ferramenta dotnet-trace é uma ferramenta global multiplataforma da CLI que permite a coleta pelo .NET Core de rastreamentos de um processo em execução. A ferramenta coleta dados do provedor Microsoft.Extensions.Logging.EventSource usando um LoggingEventSource.

Consulte dotnet-trace para obter instruções de instalação. Para obter um tutorial de diagnóstico usando dotnet-trace, confira Depurar o alto uso da CPU no .NET Core.

EventLog do Windows

O provedor EventLog envia a saída de log para o Log de Eventos do Windows. Diferente dos outros provedores, o provedor EventLognão herda as configurações de não provedor padrão. Se as configurações de log EventLog não forem especificadas, elas serão LogLevel.Warning por padrão.

Para registrar eventos inferiores a LogLevel.Warning, defina explicitamente o nível de log. O seguinte exemplo define o nível de log padrão do Log de Eventos como LogLevel.Information:

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

Sobrecargas de AddEventLog podem passar em EventLogSettings. Se for null ou não for especificado, as seguintes configurações padrão serão usadas:

  • LogName: "Aplicativo"
  • SourceName: "Runtime do .NET"
  • MachineName: o nome do computador local é usado.

O seguinte código altera o SourceName do valor padrão de ".NET Runtime" para CustomLogs:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

using IHost host = builder.Build();

host.Run();

Serviço de aplicativo do Azure

O pacote de provedor Microsoft.Extensions.Logging.AzureAppServices grava logs em arquivos de texto no sistema de arquivos de um aplicativo do Serviço de Aplicativo do Azure e no armazenamento de blobs em uma conta de Armazenamento do Azure.

O pacote do provedor não está incluído nas bibliotecas de runtime. Para usar o provedor, adicione o pacote do provedor ao projeto.

Para definir as configurações do provedor, use AzureFileLoggerOptions e AzureBlobLoggerOptions, conforme mostrado no exemplo a seguir:

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();

Quando implantado no Serviço de Aplicativo do Azure, o aplicativo usa as configurações na seção Logs do Serviço de Aplicativo da página Serviço de Aplicativo do portal do Azure. Quando as configurações a seguir são atualizadas, as alterações entram em vigor imediatamente sem a necessidade de uma reinicialização ou reimplantação do aplicativo.

O local padrão para arquivos de log é na pasta D:\home\LogFiles\Application. Os padrões adicionais variam de acordo com o provedor:

  • Registro em log de aplicativos (sistema de arquivos): o nome do arquivo padrão do sistema de arquivos é diagnostics-yyyymmdd.txt. O limite padrão de tamanho do arquivo é 10 MB e o número padrão máximo de arquivos mantidos é 2.
  • Registro em log do aplicativo (Blob): o nome de blob padrão é {app-name}/yyyy/mm/dd/hh/{guid}_applicationLog.txt.

O provedor registra somente quando o projeto é executado no ambiente do Azure.

Fluxo de log do Azure

O streaming de log do Azure dá suporte à exibição de atividades de log em tempo usando:

  • O servidor de aplicativos
  • Do servidor Web
  • De uma solicitação de rastreio com falha

Para configurar o fluxo de log do Azure:

  • Navegue até a página Logs do Serviço de Aplicativo no portal do aplicativo.
  • Defina Habilitar o log de aplicativo (sistema de arquivos) como Ativada.
  • Escolha o Nível de log. Essa configuração se aplica somente ao streaming de log do Azure.

Navegue até a página Fluxo de Log para exibir os logs. As mensagens são registradas com a interface ILogger.

Azure Application Insights

O pacote de provedor Microsoft.Extensions.Logging.ApplicationInsights grava os logs no Azure Application Insights. O Application Insights é um serviço que monitora um aplicativo web e fornece ferramentas para consultar e analisar os dados de telemetria. Se você usar esse provedor, poderá consultar e analisar os logs usando as ferramentas do Application Insights.

Para saber mais, consulte os recursos a seguir:

Considerações de design do provedor de registro em log

Se você planeja desenvolver sua própria implementação da interface ILoggerProvider e da implementação personalizada correspondente de ILogger, considere os seguintes pontos:

  • O método ILogger.Log é síncrono.
  • O tempo de vida do estado do log e dos objetos não deve ser assumido.

Uma implementação de ILoggerProvider criará um ILogger por meio do método ILoggerProvider.CreateLogger dele. Se a sua implementação se esforça para enfileirar mensagens de registro em log de maneira não bloqueada, as mensagens devem primeiro ser materializadas ou o estado do objeto usado para materializar uma entrada de log deve ser serializado. Isso evita possíveis exceções de objetos descartados.

Para obter mais informações, confira Implementar um provedor de registro em log personalizado no .NET.

Provedores de log de terceiros

Aqui estão algumas estruturas de registro em log de terceiros que funcionam com várias cargas de trabalho do .NET:

Algumas estruturas de terceiros podem fazer o log semântico, também conhecido como registro em log estruturado.

Usar uma estrutura de terceiros é semelhante ao uso de um dos provedores internos:

  1. Adicione um pacote NuGet ao projeto.
  2. Chame um método de extensão ILoggerFactory ou ILoggingBuilder fornecido pela estrutura de registros.

Para saber mais, consulte a documentação de cada provedor. Não há suporte para provedores de log de terceiros na Microsoft.

Confira também