Como fazer registro em log no .NET Core e no ASP.NET Core

Por Kirk Ltda, Juergen Queerch e Rick Anderson

Este tópico descreve o registro em log no .NET, pois ele se aplica a ASP.NET Core aplicativos. Para obter informações detalhadas sobre o registro em log no .NET, consulte Registro em log no .NET. Para obter mais informações sobre como registrar em log em Blazoraplicativos, consulte ASP.NET Core Blazor log.

Provedores de log

Os provedores de log armazenam logs, exceto o Console provedor que exibe logs. Por exemplo, o provedor Aplicativo Azure Insights armazena logs em Aplicativo Azure Insights. Vários provedores podem ser habilitados.

Os modelos ASP.NET Core aplicativo Web padrão:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código anterior mostra o arquivo Program.cs criado com os modelos ASP.NET Core aplicativo Web. As próximas seções fornecem exemplos com base nos ASP.NET Core de aplicativo Web, que usam o Host Genérico.

O código a seguir substitui o conjunto padrão de provedores de log adicionados por WebApplication.CreateBuilder:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Como alternativa, o código de log anterior pode ser escrito da seguinte maneira:

var builder = WebApplication.CreateBuilder();
builder.Host.ConfigureLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
});

Para provedores adicionais, consulte:

Criar logs

Para criar logs, use um objeto ILogger<TCategoryName> da DI (injeção de dependência).

O exemplo a seguir:

  • Cria um logger, ILogger<AboutModel>, que usa uma categoria de log do nome totalmente qualificado do tipo AboutModel. A categoria do log é uma cadeia de caracteres associada a cada log.
  • Chama LogInformation para fazer logoff no Information nível . O nível de log indica a gravidade do evento registrado.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("About page visited at {DT}", 
            DateTime.UtcNow.ToLongTimeString());
    }
}

Níveis e categorias são explicados mais detalhadamente posteriormente neste documento.

Para obter informações sobre Blazor, consulte ASP.NET Core Blazor log.

Configurar o registro em log

A configuração de registro em log normalmente é fornecida Logging pela seção de arquivos appsettings.{ENVIRONMENT}.json , em que o espaço {ENVIRONMENT} reservado é o ambiente. O arquivo appsettings.Development.json a seguir é gerado pelos modelos ASP.NET Core aplicativo Web:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

No JSON anterior:

  • As "Default" categorias "Microsoft.AspNetCore" e são especificadas.
  • A "Microsoft.AspNetCore" categoria se aplica a todas as categorias que começam com "Microsoft.AspNetCore". Por exemplo, essa configuração se aplica à "Microsoft.AspNetCore.Routing.EndpointMiddleware" categoria .
  • A "Microsoft.AspNetCore" categoria registra em log no nível de Warning log e superior.
  • Um provedor de log específico não é especificado, portanto, LogLevel aplica-se a todos os provedores de log habilitados, exceto para o Windows EventLog.

A Logging propriedade pode ter as propriedades LogLevel do provedor de log e . O LogLevel especifica o nível mínimo a ser log para categorias selecionadas. No JSON anterior, e Information os níveis Warning de log são especificados. LogLevel indica a severidade do log e os intervalos de 0 a 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 e None = 6.

Quando um LogLevel é especificado, o registro em log é habilitado para mensagens no nível especificado e superior. No JSON anterior, a categoria Default é registrada para e Information superior. Por exemplo, Informationas mensagens , WarningError, e Critical são registradas. Se nenhum LogLevel for especificado, o registro em log assume como padrão o Information nível . Para obter mais informações, consulte Níveis de log.

Uma propriedade de provedor pode especificar uma LogLevel propriedade . LogLevel em um provedor especifica os níveis a registrar nesse provedor e substitui as configurações de log que não são do provedor. Considere o seguinte appsettings.json arquivo:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Configurações em configurações Logging.{PROVIDER NAME}.LogLevel de substituição no Logging.LogLevel, em que o espaço {PROVIDER NAME} reservado é o nome do provedor. No JSON anterior, o nível Debug de log padrão do provedor é definido como Information:

Logging:Debug:LogLevel:Default:Information

A configuração anterior especifica o nível de Information log para cada categoria, exceto Logging:Debug:Microsoft.Hosting. Quando uma categoria específica é listada, a categoria específica substitui a categoria padrão. No JSON anterior, as categorias Logging:Debug:LogLevel e "Microsoft.Hosting""Default" substituem as configurações em Logging:LogLevel.

O nível de log mínimo pode ser especificado para qualquer um dos:

  • Provedores específicos: por exemplo, Logging:EventSource:LogLevel:Default:Information
  • Categorias específicas: por exemplo, Logging:LogLevel:Microsoft:Warning
  • Todos os provedores e todas as categorias: Logging:LogLevel:Default:Warning

Os logs abaixo do nível mínimo não são:

  • Passado para o provedor.
  • Registrado ou exibido.

Para suprimir todos os logs, especifique LogLevel.None. LogLevel.None tem um valor de 6, que é maior que LogLevel.Critical (5).

Se um provedor dá suporte a escopos de log, IncludeScopes indica se eles estão habilitados. Para obter mais informações, consulte escopos de log.

O arquivo appsettings.json a seguir contém todos os provedores habilitados por padrão:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Na amostra anterior:

  • As categorias e os níveis não são valores sugeridos. O exemplo é fornecido para mostrar todos os provedores padrão.
  • Configurações em configurações Logging.{PROVIDER NAME}.LogLevel de substituição no Logging.LogLevel, em que o espaço {PROVIDER NAME} reservado é o nome do provedor. Por exemplo, o nível em Debug.LogLevel.Default substitui o nível em LogLevel.Default.
  • Cada alias de provedor padrão é usado. Cada provedor define um alias que pode ser usado na configuração no lugar do nome de tipo totalmente qualificado. Os aliases de provedores integrados são:
    • Console
    • Debug
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Definir o nível de log por linha de comando, variáveis de ambiente e outras configurações

O nível de log pode ser definido por qualquer um dos provedores de configuração.

O : separador não funciona com chaves hierárquicas de variável de ambiente em todas as plataformas. __, o sublinhado duplo, é:

  • Com suporte em todas as plataformas. Por exemplo, o : separador não é suportado pelo Bash, mas __ é.
  • Substituído automaticamente por um :

Os comandos seguintes:

  • De definir a chave de Logging:LogLevel:Microsoft ambiente como um valor de Information Windows.
  • Teste as configurações ao usar um aplicativo criado com os modelos ASP.NET Core aplicativo Web. O dotnet run comando deve ser executado no diretório do projeto depois de usar set.
set Logging__LogLevel__Microsoft=Information
dotnet run

A configuração de ambiente anterior:

  • Só é definido em processos lançados na janela de comando em que foram definidos.
  • Não é lido por navegadores lançados com Visual Studio.

O comando setx a seguir também define a chave de ambiente e o valor Windows. Ao setcontrário de , setx as configurações são persistentes. A /M opção define a variável no ambiente do sistema. Se /M não for usado, uma variável de ambiente de usuário será definida.

setx Logging__LogLevel__Microsoft Information /M

Considere o seguinte appsettings.json arquivo:

"Logging": {
  "Console": {
    "LogLevel": {
      "Microsoft.Hosting.Lifetime": "Trace"
    }
  }
}

O comando a seguir define a configuração anterior no ambiente:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Na Serviço de Aplicativo do Azure, selecione Nova configuração de aplicativo na página Configurações > Configuração. Serviço de Aplicativo do Azure configurações do aplicativo são:

  • Criptografado em repouso e transmitido por um canal criptografado.
  • Exposto como variáveis de ambiente.

Para saber mais, confira Aplicativos do Azure: substituir a configuração do aplicativo usando o portal do Azure.

Para obter mais informações sobre como definir ASP.NET Core de configuração usando variáveis de ambiente, consulte variáveis de ambiente. Para obter informações sobre como usar outras fontes de configuração, incluindo a linha de comando, o Azure Key Vault, Configuração de Aplicativos do Azure, outros formatos de arquivo e muito mais, consulte Configuração no ASP.NET Core.

Como as regras de filtragem são aplicadas

Quando um objeto ILogger<TCategoryName> é criado, o objeto ILoggerFactory seleciona uma única regra por provedor para aplicar a esse agente. Todas as mensagens gravadas pela instância ILogger são filtradas com base nas regras selecionadas. A regra mais específica para cada provedor e par de categorias é selecionada nas regras disponíveis.

O algoritmo a seguir é usado para cada provedor quando um ILogger é criado para uma determinada categoria:

  • Selecione todas as regras que correspondem ao provedor ou seu alias. Se nenhuma correspondência for encontrada, selecione todas as regras com um provedor vazio.
  • Do resultado da etapa anterior, selecione as regras com o prefixo de categoria de maior correspondência. Se nenhuma correspondência for encontrada, selecione todas as regras que não especificam uma categoria.
  • Se várias regras forem selecionadas, use a última.
  • Se nenhuma regra for selecionada, use MinimumLevel.

Registrar em log a saída de dotnet run e Visual Studio

Os logs criados com os provedores de log padrão são exibidos:

  • No Visual Studio
    • Na janela Depurar saída durante a depuração.
    • Na janela ASP.NET Core Web Server.
  • Na janela do console quando o aplicativo é executado com dotnet run.

Os logs que começam com categorias "Microsoft" são ASP.NET Core código de estrutura. ASP.NET Core e o código do aplicativo usam a mesma API e provedores de log.

Categoria do log

Quando um ILogger objeto é criado, uma categoria é especificada. Essa categoria é incluída em cada mensagem de log criada por essa instância de ILogger. A cadeia de caracteres de categoria é arbitrária, mas a convenção é usar o nome da classe. Por exemplo, em um controlador, o nome pode ser "TodoApi.Controllers.TodoController". A ASP.NET Core aplicativos Web usa ILogger<T> para obter automaticamente ILogger uma instância que usa o nome de tipo totalmente qualificado de T como a categoria:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Para especificar explicitamente a categoria, chame ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Chamar CreateLogger com um nome fixo pode ser útil quando usado em vários métodos para que os eventos possam ser organizados por categoria.

ILogger<T> é equivalente a chamar CreateLogger com o nome de tipo totalmente qualificado de T.

Nível de log

A tabela a seguir lista os LogLevel valores, o método de Log{LogLevel} extensão de conveniência e o uso sugerido:

LogLevel Valor Método Descrição
Trace 0 LogTrace Contêm as mensagens mais detalhadas. Essas mensagens podem conter dados confidenciais do aplicativo. Essas mensagens são desabilitadas por padrão e não devem ser habilitadas em produção.
Debug 1 LogDebug Para depuração e desenvolvimento. Use com cuidado na produção devido ao alto volume.
Information 2 LogInformation Rastreia o fluxo geral do aplicativo. Pode ter um valor de longo prazo.
Warning 3 LogWarning Para eventos anormais ou inesperados. Normalmente, inclui erros ou condições que não causam falha no aplicativo.
Error 4 LogError Para erros e exceções que não podem ser manipulados. Essas mensagens indicam uma falha na operação ou solicitação atual, não uma falha em todo o aplicativo.
Critical 5 LogCritical Para falhas que exigem atenção imediata. Exemplos: cenários de perda de dados, espaço em disco insuficiente.
None 6 Especifica que uma categoria de registro em log não deve gravar mensagens.

Na tabela anterior, o é LogLevel listado da gravidade mais baixa para a mais alta.

O Log primeiro parâmetro do método, LogLevel, indica a severidade do log. Em vez de chamar Log(LogLevel, ...), a maioria dos desenvolvedores chama os Log{LOG LEVEL} métodos de extensão, em que o espaço {LOG LEVEL} reservado é o nível de log. Por exemplo, as duas chamadas de log a seguir são funcionalmente equivalentes e produzem o mesmo log:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem é a ID do evento. MyLogEvents faz parte do aplicativo de exemplo e é exibido na seção ID do evento log.

MyDisplayRouteInfo e ToCtxString são fornecidos pelo pacote de NuGet Rick.Docs.Samples.RouteInfo. Os métodos exibem e Controller roteam Razor Page informações.

O código a seguir cria os logs Information e Warning:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

No código anterior, o primeiro Log{LOG LEVEL} parâmetro éMyLogEvents.GetItem a ID do evento log. O segundo parâmetro é um modelo de mensagem com espaços reservados para valores de argumento fornecidos pelos parâmetros de método restantes. Os parâmetros de método são explicados na seção modelo de mensagem mais adiante neste documento.

Chame o método apropriado Log{LOG LEVEL} para controlar a quanto de saída de log é gravado em uma mídia de armazenamento específica. Por exemplo:

  • Em produção:
    • O registro em log Trace nos níveis Information ou produz um alto volume de mensagens de log detalhadas. Para controlar os custos e não exceder os limites de armazenamento de dados, registre TraceInformation e nivele mensagens para um armazenamento de dados de alto volume e baixo custo. Considere limitar e Trace a Information categorias específicas.
    • O registro em Warning log em Critical níveis deve produzir poucas mensagens de log.
      • Os custos e os limites de armazenamento geralmente não são uma preocupação.
      • Alguns logs permitem mais flexibilidade nas opções de armazenamento de dados.
  • Em desenvolvimento:
    • Defina como Warning.
    • Adicionar Trace ou Information mensagens ao solucionar problemas. Para limitar a saída, de definido Trace ou Information apenas para as categorias em investigação.

O ASP.NET Core grava logs para eventos de estrutura. Por exemplo, considere a saída de log para:

  • Um Razor aplicativo Pages criado com os ASP.NET Core modelos.
  • Registro em log definido como Logging:Console:LogLevel:Microsoft:Information.
  • Navegação até a Privacy página:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

O seguinte JSON define Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ID de evento de log

Cada log pode especificar uma ID do evento. O aplicativo de exemplo usa a MyLogEvents classe para definir IDs de evento:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Uma ID de evento associa um conjunto de eventos. Por exemplo, todos os logs relacionados à exibição de uma lista de itens em uma página podem ser 1001.

O provedor de logs pode armazenar a ID do evento em um campo de ID na mensagem de log ou não armazenar. O provedor de Depuração não mostra IDs de eventos. O provedor de console mostra IDs de evento entre colchetes após a categoria:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Alguns provedores de log armazenam a ID do evento em um campo, o que permite a filtragem na ID.

Modelo de mensagem de log

Cada API de log usa um modelo de mensagem. O modelo de mensagem pode conter espaços reservados para os quais são fornecidos argumentos. Use nomes para os espaços reservados, não números.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

A ordem dos parâmetros, não seus nomes de espaço reservado, determina quais parâmetros são usados para fornecer valores de espaço reservado em mensagens de log. No código a seguir, os nomes de parâmetro estão fora de sequência nos espaço reservados do modelo de mensagem:

string apples = 1;
string pears = 2;
string bananas = 3;

_logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);

No entanto, os parâmetros são atribuídos aos espaço reservados na ordem: apples, pears, bananas. A mensagem de log reflete a ordem dos parâmetros:

Parameters: 1, 2, 3

Essa abordagem permite que os provedores de log implementem o registro em log semântico ou estruturado. Os próprios argumentos são passados para o sistema de registro em log, não apenas o modelo de mensagem formatado. Isso permite que provedores de log armazenem os valores de parâmetro como campos. Por exemplo, considere o seguinte método de logger:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Por exemplo, ao registrar em log no Azure Table Armazenamento:

  • Cada entidade tabela do Azure pode ter propriedades ID e RequestTime .
  • Tabelas com propriedades simplificam consultas em dados registrados. Por exemplo, uma consulta pode encontrar todos os logs dentro de um intervalo RequestTime específico sem precisar analisar o tempo fora da mensagem de texto.

Registrar exceções em log

Os métodos de logger têm sobrecargas que levam um parâmetro de exceção:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo e ToCtxString são fornecidos pelo pacote de NuGet Rick.Docs.Samples.RouteInfo. Os métodos exibem e Controller roteam Razor Page informações.

O log de exceção é específico do provedor.

Nível de log padrão

Se o nível de log padrão não estiver definido, o valor padrão do nível de log será Information.

Por exemplo, considere o seguinte aplicativo Web:

  • Criado com os modelos ASP.NET aplicativo Web.
  • appsettings.json e appsettings.Development.json excluídos ou renomeados.

Com a configuração anterior, navegar até a privacidade ou home page produz Tracemuitas mensagens , Debuge InformationMicrosoft com no nome da categoria.

O código a seguir define o nível de log padrão quando o nível de log padrão não está definido na configuração:

var builder = WebApplication.CreateBuilder();
builder.Logging.SetMinimumLevel(LogLevel.Warning);

Em geral, os níveis de log devem ser especificados na configuração e não no código.

Função Filter

Uma função de filtro é invocada para todos os provedores e categorias que não têm regras atribuídas a eles por configuração ou código:

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter((provider, category, logLevel) =>
{
    if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Controller")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Microsoft")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else
    {
        return false;
    }
});

O código anterior exibe os logs do console quando a categoria contém Controller ou Microsoft e o nível de log é Information ou superior.

Em geral, os níveis de log devem ser especificados na configuração e não no código.

ASP.NET Core e EF Core categorias

A tabela a seguir contém algumas categorias usadas por ASP.NET Core e Entity Framework Core, com observações sobre os logs:

Categoria Observações
Microsoft.AspNetCore Diagnóstico geral de ASP.NET Core.
Microsoft.AspNetCore.DataProtection Quais chaves foram consideradas, encontradas e usadas.
Microsoft.AspNetCore.HostFiltering Hosts permitidos.
Microsoft.AspNetCore.Hosting Quanto tempo levou para que as solicitações de HTTP fossem concluídas e em que horário foram iniciadas. Quais assemblies de inicialização de hospedagem foram carregados.
Microsoft.AspNetCore.Mvc MVC e Razor diagnóstico. Model binding, execução de filtro, compilação de exibição, seleção de ação.
Microsoft.AspNetCore.Routing Informações de correspondência de rotas.
Microsoft.AspNetCore.Server Respostas de início, parada e atividade da conexão. Informações sobre o certificado HTTPS.
Microsoft.AspNetCore.StaticFiles Arquivos atendidos.
Microsoft.EntityFrameworkCore Diagnóstico geral do Entity Framework Core. Atividade e configuração do banco de dados, detecção de alterações, migrações.

Para exibir mais categorias na janela do console, de definido appsettings.Development.json como o seguinte:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Escopos de log

Um escopo pode agrupar um conjunto de operações lógicas. Esse agrupamento pode ser usado para anexar os mesmos dados para cada log criado como parte de um conjunto. Por exemplo, todo log criado como parte do processamento de uma transação pode incluir a ID da transação.

Um escopo:

Os seguintes provedores suportam escopos:

Use um escopo por meio do encapsulamento de chamadas de agente em um bloco using:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Provedores de log internos

ASP.NET Core inclui os seguintes provedores de log como parte da estrutura compartilhada:

Os provedores de log a seguir são enviados pela Microsoft, mas não como parte da estrutura compartilhada. Eles devem ser instalados como nuget adicional.

ASP.NET Core não inclui um provedor de log para a escrita de logs em arquivos. Para gravar logs em arquivos de um ASP.NET Core, considere usar um provedor de log de terceiros.

stdout Para obter informações sobre e depurar o registro em log com o módulo ASP.NET Core, consulte Solucionar problemas ASP.NET Core no Serviço de Aplicativo do Azure e no IIS e no MÓDULO ASP.NET Core (ANCM) para IIS.

Console

O Console provedor registra a saída no console. Para obter mais informações sobre como exibir Console logs em desenvolvimento, consulte Log output from dotnet run and Visual Studio.

Depurar

O Debug provedor grava a saída do log usando a System.Diagnostics.Debug classe . Chama para System.Diagnostics.Debug.WriteLine gravar no Debug provedor.

No Linux, o local Debug do log do provedor depende da distribuição e pode ser um dos seguintes:

  • /var/log/message
  • /var/log/syslog

Origem do Evento

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

Ferramentas de rastreamento dotnet

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

Para obter instruções de instalação, consulte dotnet-trace.

Use as dotnet trace ferramentas para coletar um rastreamento de um aplicativo:

  1. Execute o aplicativo com o dotnet run comando .

  2. Determine o PID (identificador de processo) do aplicativo .NET Core:

    dotnet trace ps
    

    Encontre o PID para o processo que tem o mesmo nome que o assembly do aplicativo.

  3. Execute o comando dotnet trace.

    Sintaxe de comando geral:

    dotnet trace collect -p {PID} 
        --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Category Level 1};
                {Logger Category 2}:{Category Level 2};
                ...
                {Logger Category N}:{Category Level N}\"
    

    Ao usar um shell de comando do PowerShell, coloque o --providers valor entre aspas simples ('):

    dotnet trace collect -p {PID} 
        --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Category Level 1};
                {Logger Category 2}:{Category Level 2};
                ...
                {Logger Category N}:{Category Level N}\"'
    

    Em plataformas Windows, adicione a -f speedscope opção para alterar o formato do arquivo de rastreamento de saída para speedscope.

    A tabela a seguir define a palavra-chave :

    Palavra-chave Descrição
    1 Registrar metadados em log sobre o LoggingEventSource. Não registra eventos de ILogger.
    2 Liga o evento Message quando ILogger.Log() é chamado. Fornece informações de maneira programática (não formatada).
    4 Liga o evento FormatMessage quando ILogger.Log() é chamado. Fornece a versão de cadeia de caracteres formatada das informações.
    8 Liga o evento MessageJson quando ILogger.Log() é chamado. Fornece uma representação JSON dos argumentos.

    A tabela a seguir lista os níveis do provedor:

    Nível do provedor Descrição
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    A análise de um nível de categoria pode ser uma cadeia de caracteres ou um número:

    Valor nomeado da categoria Valor numérico
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    O nível do provedor e o nível de categoria:

    • Estão em ordem inversa.
    • As constantes de cadeia de caracteres não são idênticas.

    Se nenhum FilterSpecs for especificado, a implementação EventSourceLogger tentará converter o nível do provedor em um nível de categoria e o aplicará a todas as categorias.

    Nível do provedor Nível da categoria
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    Se FilterSpecs for fornecida, qualquer categoria incluída na lista usará o nível de categoria codificado lá, todas as outras categorias serão filtradas.

    Os exemplos a seguir pressupom:

    • Um aplicativo está em execução e chamando logger.LogDebug("12345").
    • A ID do processo (PID) foi definida por meio de set PID=12345, em que 12345 é o PID real.

    Considere o seguinte código:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
    

    O comando anterior:

    • Captura mensagens de depuração.
    • Não aplica um FilterSpecs.
    • Especifica o nível 5 que mapeia a categoria Depuração.

    Considere o seguinte código:

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
    

    O comando anterior:

    • Não captura mensagens de depuração porque o nível de categoria 5 é Critical.
    • Fornece um FilterSpecs.

    O comando a seguir captura mensagens de depuração porque o nível de categoria 1 especifica Debug.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
    

    O comando a seguir captura mensagens de depuração porque a categoria especifica Debug.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
    

    FilterSpecs entradas para e representam {Logger Category} condições {Category Level} de filtragem de log adicionais. Separe FilterSpecs entradas com o caractere ; de ponto e vírgula.

    Exemplo usando um shell Windows comando:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
    

    O comando anterior ativa:

    • O logger de Origem do Evento para produzir cadeias de caracteres formatadas (4) para erros (2).
    • Microsoft.AspNetCore.Hosting registro em log no nível Informational de log (4).
  4. Pare as ferramentas de rastreamento dotnet pressionando a tecla Enter ou CtrlC+.

    O rastreamento é salvo com o nome trace.nettrace na pasta em que o dotnet trace comando é executado.

  5. Abra o rastreamento com Perfview. Abra o trace.nettrace arquivo e explore os eventos de rastreamento.

Se o aplicativo não criar o host com , adicione o provedor WebApplication.CreateBuilderde Origem do Evento à configuração de log do aplicativo.

Para obter mais informações, consulte:

Perfview

Use o utilitário PerfView para coletar e exibir logs. Há outras ferramentas para exibir os logs do ETW, mas o PerfView proporciona a melhor experiência para trabalhar com os eventos de ETW emitidos pelo ASP.NET Core.

Para configurar o PerfView para coletar eventos registrados por esse provedor, adicione a cadeia de caracteres *Microsoft-Extensions-Logging à lista Provedores Adicionais. Não perca o no * início da cadeia de caracteres.

EventLog do Windows

O EventLog provedor envia a saída de log para o log Windows log de eventos. Ao contrário dos outros provedores, o EventLog provedor não herda as configurações padrão de não provedor. Se EventLog as configurações de log não são especificadas, elas assumem como padrão LogLevel.Warning.

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

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

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

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

O código a seguir altera SourceName o do valor padrão de ".NET Runtime" para MyLogs:


var builder = WebApplication.CreateBuilder();
builder.Logging.AddEventLog(eventLogSettings =>
{
    eventLogSettings.SourceName = "MyLogs";
});

Serviço de aplicativo do Azure

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

O pacote do provedor não está incluído na estrutura compartilhada. 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;

var builder = WebApplication.CreateBuilder();
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";
});

Quando implantado no Serviço de Aplicativo do Azure, o aplicativo usa as configurações na seção Serviço de Aplicativo logs 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.

  • Log de aplicativo (Sistema de Arquivos)
  • Log de aplicativo (Blob)

O local padrão para arquivos de log está na D:\\home\\LogFiles\\Application pasta e o nome de arquivo padrão é 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. O nome do blob padrão é {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt .

Esse provedor só registra quando o projeto é executado no ambiente do Azure.

Fluxo de log do Azure

O Azure log streaming dá suporte à exibição da atividade de log em tempo real em:

  • 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 de logs de Serviço de Aplicativo na página do 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 registradas são registradas com a ILogger interface.

Azure Application Insights

o pacote do Microsoft.Extensions.Logging.ApplicationInsights provedor grava logs em Aplicativo Azure 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.

O provedor de log está incluído como uma dependência de Microsoft.ApplicationInsights.AspNetCore , que é o pacote que fornece toda a telemetria disponível para ASP.NET Core. Se você usar esse pacote, não precisará instalar o pacote de provedor.

o Microsoft.ApplicationInsights.Web pacote é para ASP.NET 4. x, não ASP.NET Core.

Para saber mais, consulte os recursos a seguir:

Provedores de log de terceiros

Estruturas de log de terceiros que funcionam com o ASP.NET Core:

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 ILoggerFactory método de extensão fornecido pela estrutura de log.

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

Sem métodos de agente assíncronos

O registro em log deve ser tão rápido que não justifique o custo de desempenho de código assíncrono. Se um armazenamento de dados de log estiver lento, não grave-o diretamente. Considere gravar as mensagens de log em um repositório rápido inicialmente e, em seguida, movê-las para o armazenamento lento mais tarde. por exemplo, ao fazer logon no SQL Server, não faça isso diretamente em um Log método, pois os Log métodos são síncronos. Em vez disso, adicione mensagens de log de forma síncrona a uma fila na memória e faça com que uma função de trabalho de plano de fundo efetue pull das mensagens para fora da fila para fazer o trabalho assíncrono de envio de dados por push para o SQL Server. Para obter mais informações, consulte orientação sobre como fazer logon em uma fila de mensagens para armazenamentos de dados lentos (dotNet/AspNetCore. Docs #11801).

Alterar os níveis de log em um aplicativo em execução

A API de registro em log não inclui um cenário para alterar os níveis de log enquanto um aplicativo está em execução. No entanto, alguns provedores de configuração são capazes de recarregar a configuração, o que exige um efeito imediato na configuração de log. Por exemplo, o provedor de configuração de arquivo, recarrega a configuração de log por padrão. Se a configuração for alterada no código enquanto um aplicativo estiver em execução, o aplicativo poderá chamar IConfigurationRoot.Reload para atualizar a configuração de log do aplicativo.

ILogger e ILoggerFactory

ILoggerFactoryAs ILogger<TCategoryName> interfaces e implementações são incluídas no SDK do .NET Core. eles também estão disponíveis nos seguintes pacotes de NuGet:

Aplicar regras de filtro de log no código

A abordagem preferida para definir regras de filtro de log é usando a configuraçãodo.

O exemplo a seguir mostra como registrar regras de filtro no código:

using Microsoft.Extensions.Logging.Console;
using Microsoft.Extensions.Logging.Debug;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter("System", LogLevel.Debug);
builder.Logging.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information);
builder.Logging.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace);

logging.AddFilter("System", LogLevel.Debug)Especifica a categoria e o nível Debug de System log. O filtro é aplicado a todos os provedores porque um provedor específico não foi configurado.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) especificado

  • O provedor de Debug log.
  • Nível Information de log e superior.
  • Todas as categorias que começam com "Microsoft" .

Registrar automaticamente o escopo com SpanId , ParentIdTraceId ,, Baggage e Tags .

As bibliotecas de registro em log criam implicitamente um objeto de escopo com SpanId , ParentIdTraceId ,, Baggage e Tags . Esse comportamento é configurado via ActivityTrackingOptions .

  var loggerFactory = LoggerFactory.Create(logging =>
  {
      logging.Configure(options =>
      {
          options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                              | ActivityTrackingOptions.TraceId
                                              | ActivityTrackingOptions.ParentId
                                              | ActivityTrackingOptions.Baggage
                                              | ActivityTrackingOptions.Tags;
      }).AddSimpleConsole(options =>
      {
          options.IncludeScopes = true;
      });
  });

Se o traceparent cabeçalho de solicitação HTTP for definido, o ParentId no escopo de log mostrará o W3C parent-id do cabeçalho na associação traceparent e o SpanId no escopo do log mostrará a atualização parent-id para o próximo passo/span fora associado. Para obter mais informações, consulte mutando o campo traceparent.

Criar um agente de log personalizado

Para criar um agente personalizado, consulte implementar um provedor de log personalizado no .net.

Recursos adicionais

Por Kirk Larkin, Juergen Gutsche Rick Anderson

este tópico descreve o registro em log no .net, pois ele se aplica a aplicativos ASP.NET Core. Para obter informações detalhadas sobre o registro em log no .NET, consulte Logging in .net. para obter mais informações sobre como fazer logon em Blazor aplicativos, consulte ASP.NET Core Blazor log.

Exiba ou baixe o código de exemplo (como baixar).

Provedores de log

Os provedores de log armazenam logs, exceto para o Console provedor que exibe logs. por exemplo, o provedor de Insights Aplicativo Azure armazena logs em Aplicativo Azure Insights. Vários provedores podem ser habilitados.

os modelos de aplicativo web padrão ASP.NET Core:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

O código anterior mostra a classe Program criada com os modelos ASP.NET Core aplicativo Web. As próximas seções fornecem exemplos com base nos ASP.NET Core de aplicativo Web, que usam o Host Genérico. Os aplicativos de console não host são discutidos posteriormente neste documento.

Para substituir o conjunto padrão de provedores de log adicionados pelo Host.CreateDefaultBuilder, chame ClearProviders e adicione os provedores de log necessários. Por exemplo, o código a seguir:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Para provedores adicionais, consulte:

Criar logs

Para criar logs, use um objeto ILogger<TCategoryName> da DI ( injeção de dependência ).

O exemplo a seguir:

  • Cria um logger, ILogger<AboutModel>, que usa uma categoria de log do nome totalmente qualificado do tipo AboutModel. A categoria do log é uma cadeia de caracteres associada a cada log.
  • Chama LogInformation para fazer logoff no Information nível . O nível de log indica a gravidade do evento registrado.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

Níveis e categorias são explicados mais detalhadamente posteriormente neste documento.

Para obter informações sobre Blazor, consulte ASP.NET Core Blazor log.

Criar logs no Main e na Inicialização mostra como criar logs no Main e no Startup.

Configurar o registro em log

A configuração de registro em log normalmente é fornecida pela Logging seção de appsettings.{Environment}.json arquivos. O arquivo appsettings.Development.json a seguir é gerado pelos modelos ASP.NET Core aplicativo Web:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

No JSON anterior:

  • As "Default"categorias "Microsoft", e "Microsoft.Hosting.Lifetime" são especificadas.
  • A "Microsoft" categoria se aplica a todas as categorias que começam com "Microsoft". Por exemplo, essa configuração se aplica à "Microsoft.AspNetCore.Routing.EndpointMiddleware" categoria .
  • A "Microsoft" categoria registra em log no nível de Warning log e superior.
  • A "Microsoft.Hosting.Lifetime" categoria é mais específica do que a "Microsoft" categoria, portanto, a "Microsoft.Hosting.Lifetime" categoria registra em log o nível de log "Informações" e superior.
  • Um provedor de log específico não é especificado, portanto, LogLevel aplica-se a todos os provedores de log habilitados, exceto para o Windows EventLog.

A Logging propriedade pode ter as propriedades LogLevel do provedor de log e . O LogLevel especifica o nível mínimo a ser log para categorias selecionadas. No JSON anterior, e Information os níveis Warning de log são especificados. LogLevel indica a severidade do log e os intervalos de 0 a 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 e None = 6.

Quando um LogLevel é especificado, o registro em log é habilitado para mensagens no nível especificado e superior. No JSON anterior, a categoria Default é registrada para e Information superior. Por exemplo, Informationas mensagens , WarningError, e Critical são registradas. Se nenhum LogLevel for especificado, o registro em log assume como padrão o Information nível . Para obter mais informações, consulte Níveis de log.

Uma propriedade de provedor pode especificar uma LogLevel propriedade . LogLevel em um provedor especifica os níveis a registrar nesse provedor e substitui as configurações de log que não são do provedor. Considere o seguinte appsettings.json arquivo:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Configurações em configurações Logging.{providername}.LogLevel de substituição no Logging.LogLevel. No JSON anterior, o nível Debug de log padrão do provedor é definido como Information:

Logging:Debug:LogLevel:Default:Information

A configuração anterior especifica o nível de Information log para cada categoria, exceto Logging:Debug:Microsoft.Hosting. Quando uma categoria específica é listada, a categoria específica substitui a categoria padrão. No JSON anterior, as categorias Logging:Debug:LogLevel e "Microsoft.Hosting" substituem "Default" as configurações em Logging:LogLevel

O nível de log mínimo pode ser especificado para qualquer um dos:

  • Provedores específicos: por exemplo, Logging:EventSource:LogLevel:Default:Information
  • Categorias específicas: por exemplo, Logging:LogLevel:Microsoft:Warning
  • Todos os provedores e todas as categorias: Logging:LogLevel:Default:Warning

Os logs abaixo do nível mínimo não são:

  • Passado para o provedor.
  • Registrado ou exibido.

Para suprimir todos os logs, especifique LogLevel.None. LogLevel.None tem um valor de 6, que é maior que LogLevel.Critical (5).

Se um provedor dá suporte a escopos de log, IncludeScopes indica se eles estão habilitados. Para obter mais informações, consulte escopos de log

O arquivo appsettings.json a seguir contém todos os provedores habilitados por padrão:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Na amostra anterior:

  • As categorias e os níveis não são valores sugeridos. O exemplo é fornecido para mostrar todos os provedores padrão.
  • Configurações em configurações Logging.{providername}.LogLevel de substituição no Logging.LogLevel. Por exemplo, o nível em Debug.LogLevel.Default substitui o nível em LogLevel.Default.
  • Cada alias de provedor padrão é usado. Cada provedor define um alias que pode ser usado na configuração no lugar do nome de tipo totalmente qualificado. Os aliases de provedores integrados são:
    • Console
    • Depurar
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Definir o nível de log por linha de comando, variáveis de ambiente e outras configurações

O nível de log pode ser definido por qualquer um dos provedores de configuração.

O : separador não funciona com chaves hierárquicas de variável de ambiente em todas as plataformas. __, o sublinhado duplo, é:

  • Com suporte em todas as plataformas. Por exemplo, o : separador não é suportado pelo Bash, mas __ é.
  • Substituído automaticamente por um :

Os comandos seguintes:

  • De definir a chave de Logging:LogLevel:Microsoft ambiente como um valor de Information Windows.
  • Teste as configurações ao usar um aplicativo criado com os modelos ASP.NET Core aplicativo Web. O dotnet run comando deve ser executado no diretório do projeto depois de usar set.
set Logging__LogLevel__Microsoft=Information
dotnet run

A configuração de ambiente anterior:

  • Só é definido em processos lançados na janela de comando em que foram definidos.
  • Não é lido por navegadores lançados com Visual Studio.

O comando setx a seguir também define a chave de ambiente e o valor Windows. Ao setcontrário de , setx as configurações são persistentes. A /M opção define a variável no ambiente do sistema. Se /M não for usado, uma variável de ambiente de usuário será definida.

setx Logging__LogLevel__Microsoft Information /M

Considere o seguinte appsettings.json arquivo:

"Logging": {
    "Console": {
      "LogLevel": {
        "Microsoft.Hosting.Lifetime": "Trace"
      }
    }
}

O comando a seguir define a configuração anterior no ambiente:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Na Serviço de Aplicativo do Azure, selecione Nova configuração de aplicativo na página Configurações > Configuração. Serviço de Aplicativo do Azure configurações do aplicativo são:

  • Criptografado em repouso e transmitido por um canal criptografado.
  • Exposto como variáveis de ambiente.

Para saber mais, confira Aplicativos do Azure: substituir a configuração do aplicativo usando o portal do Azure.

para obter mais informações sobre como definir ASP.NET Core valores de configuração usando variáveis de ambiente, consulte variáveis de ambiente. para obter informações sobre como usar outras fontes de configuração, incluindo a linha de comando, Key Vault do Azure, Configuração de Aplicativos do Azure, outros formatos de arquivo e muito mais, consulte configuração no ASP.NET Core.

Como as regras de filtragem são aplicadas

Quando um objeto ILogger<TCategoryName> é criado, o objeto ILoggerFactory seleciona uma única regra por provedor para aplicar a esse agente. Todas as mensagens gravadas pela instância ILogger são filtradas com base nas regras selecionadas. A regra mais específica para cada par de provedor e categoria é selecionada nas regras disponíveis.

O algoritmo a seguir é usado para cada provedor quando um ILogger é criado para uma determinada categoria:

  • Selecione todas as regras que correspondem ao provedor ou seu alias. Se nenhuma correspondência for encontrada, selecione todas as regras com um provedor vazio.
  • Do resultado da etapa anterior, selecione as regras com o prefixo de categoria de maior correspondência. Se nenhuma correspondência for encontrada, selecione todas as regras que não especificam uma categoria.
  • Se várias regras forem selecionadas, use a última.
  • Se nenhuma regra for selecionada, use MinimumLevel.

Log de saída de dotnet executar e Visual Studio

Os logs criados com os provedores de log padrão são exibidos:

  • No Visual Studio
    • Na janela de saída de depuração durante a depuração.
    • na janela do servidor Web do ASP.NET Core.
  • Na janela do console, quando o aplicativo é executado com dotnet run .

os Logs que começam com as categorias "Microsoft" são de ASP.NET Core código do framework. ASP.NET Core e o código do aplicativo usam a mesma API e provedores de log.

Categoria do log

Quando um ILogger objeto é criado, uma categoria é especificada. Essa categoria é incluída em cada mensagem de log criada por essa instância de ILogger. A cadeia de caracteres da categoria é arbitrária, mas a Convenção é usar o nome da classe. Por exemplo, em um controlador, o nome pode ser "TodoApi.Controllers.TodoController" . o ASP.NET Core aplicativos web usam ILogger<T> para obter automaticamente uma ILogger instância que usa o nome T do tipo totalmente qualificado como a categoria:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Para especificar explicitamente a categoria, chame ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Chamar CreateLogger com um nome fixo pode ser útil quando usado em vários métodos para que os eventos possam ser organizados por categoria.

ILogger<T> é equivalente a chamar CreateLogger com o nome de tipo totalmente qualificado de T.

Nível de log

A tabela a seguir lista os LogLevel valores, o método de extensão de conveniência Log{LogLevel} e o uso sugerido:

LogLevel Valor Método Descrição
Trace 0 LogTrace Conter as mensagens mais detalhadas. Essas mensagens podem conter dados confidenciais do aplicativo. Essas mensagens são desabilitadas por padrão e não devem ser habilitadas na produção.
Depurar 1 LogDebug Para depuração e desenvolvimento. Use com cuidado na produção devido ao alto volume.
Informações 2 LogInformation Rastreia o fluxo geral do aplicativo. Pode ter um valor de longo prazo.
Aviso 3 LogWarning Para eventos anormais ou inesperados. Normalmente inclui erros ou condições que não fazem com que o aplicativo falhe.
Erro 4 LogError Para erros e exceções que não podem ser manipulados. Essas mensagens indicam uma falha na operação ou solicitação atual, não uma falha em todo o aplicativo.
Crítico 5 LogCritical Para falhas que exigem atenção imediata. Exemplos: cenários de perda de dados, espaço em disco insuficiente.
Nenhum 6 Especifica que uma categoria de log não deve gravar nenhuma mensagem.

Na tabela anterior, o LogLevel é listado da severidade mais baixa para a mais alta.

O primeiro parâmetro do método de log , LogLevel , indica a severidade do log. Em vez de chamar Log(LogLevel, ...) , a maioria dos desenvolvedores chama os métodos de extensão do log {LogLevel} . Os métodos de Log{LogLevel} extensão chamam o método de log e especificam o LogLevel. Por exemplo, as duas chamadas de log a seguir são funcionalmente equivalentes e produzem o mesmo log:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem é a ID do evento. MyLogEvents faz parte do aplicativo de exemplo e é exibido na seção ID do evento de log .

MyDisplayRouteInfo e ToCtxString são fornecidos pelo pacote de NuGet Rick. Docs. samples. RouteInfo . Os métodos exibem Controller e Razor Page roteiam informações.

O código a seguir cria os logs Information e Warning:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

No código anterior, o primeiro Log{LogLevel} parâmetro, MyLogEvents.GetItem , é a ID do evento de log. O segundo parâmetro é um modelo de mensagem com espaços reservados para valores de argumento fornecidos pelos parâmetros de método restantes. Os parâmetros do método são explicados na seção de modelo de mensagem mais adiante neste documento.

Chame o método apropriado Log{LogLevel} para controlar a quantidade de saída de log gravada em um meio de armazenamento específico. Por exemplo:

  • Em produção:
    • O Trace registro em log nos níveis ou Information produz um alto volume de mensagens de log detalhadas. Para controlar os custos e não exceder os limites de armazenamento de dados, as mensagens de log Trace e de nível para um armazenamento de dados de alto volume e Information baixo custo. Considere limitar Trace e Information para categorias específicas.
    • O registro em log por meio Critical de níveis deve produzir algumas mensagens de Warning log.
      • Os custos e os limites de armazenamento geralmente não são uma preocupação.
      • Alguns logs permitem mais flexibilidade em opções de armazenamento de dados.
  • Em desenvolvimento:
    • Defina como Warning.
    • Adicionar Trace ou Information mensagens ao solucionar problemas. Para limitar a saída, defina Trace ou Information apenas para as categorias em investigação.

O ASP.NET Core grava logs para eventos de estrutura. Por exemplo, considere a saída de log para:

  • um Razor aplicativo de páginas criado com os modelos de ASP.NET Core.
  • Registro em log definido como Logging:Console:LogLevel:Microsoft:Information
  • Navegação para a Privacy página:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Os seguintes conjuntos Logging:Console:LogLevel:Microsoft:Information JSON:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ID de evento de log

Cada log pode especificar uma ID do evento. O aplicativo de exemplo usa a MyLogEvents classe para definir IDs de evento:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Uma ID de evento associa um conjunto de eventos. Por exemplo, todos os logs relacionados à exibição de uma lista de itens em uma página podem ser 1001.

O provedor de logs pode armazenar a ID do evento em um campo de ID na mensagem de log ou não armazenar. O provedor de Depuração não mostra IDs de eventos. O provedor de console mostra IDs de evento entre colchetes após a categoria:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Alguns provedores de log armazenam a ID do evento em um campo, o que permite a filtragem na ID.

Modelo de mensagem de log

Cada API de log usa um modelo de mensagem. O modelo de mensagem pode conter espaços reservados para os quais são fornecidos argumentos. Use nomes para os espaços reservados, não números.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

A ordem dos parâmetros, não seus nomes de espaço reservado, determina quais parâmetros são usados para fornecer valores de espaço reservado em mensagens de log. No código a seguir, os nomes de parâmetro estão fora de sequência nos espaço reservados do modelo de mensagem:

string apples = 1;
string pears = 2;
string bananas = 3;

_logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);

No entanto, os parâmetros são atribuídos aos espaço reservados na ordem: apples, pears, bananas. A mensagem de log reflete a ordem dos parâmetros:

Parameters: 1, 2, 3

Essa abordagem permite que os provedores de log implementem o registro em log semântico ou estruturado. Os próprios argumentos são passados para o sistema de registro em log, não apenas o modelo de mensagem formatado. Isso permite que provedores de log armazenem os valores de parâmetro como campos. Por exemplo, considere o seguinte método de logger:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Por exemplo, ao registrar em log no Azure Table Armazenamento:

  • Cada entidade tabela do Azure pode ter propriedades ID e RequestTime .
  • Tabelas com propriedades simplificam consultas em dados registrados. Por exemplo, uma consulta pode encontrar todos os logs dentro de um intervalo RequestTime específico sem precisar analisar o tempo fora da mensagem de texto.

Registrar exceções em log

Os métodos de logger têm sobrecargas que levam um parâmetro de exceção:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo e ToCtxString são fornecidos pelo pacote de NuGet Rick.Docs.Samples.RouteInfo. Os métodos exibem e Controller roteam Razor Page informações.

O log de exceção é específico do provedor.

Nível de log padrão

Se o nível de log padrão não estiver definido, o valor padrão do nível de log será Information.

Por exemplo, considere o seguinte aplicativo Web:

  • Criado com os modelos ASP.NET aplicativo Web.
  • appsettings.json e appsettings.Development.json excluídos ou renomeados.

Com a configuração anterior, navegar até a privacidade ou home page produz Tracemuitas mensagens , Debuge InformationMicrosoft com no nome da categoria.

O código a seguir define o nível de log padrão quando o nível de log padrão não está definido na configuração:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Em geral, os níveis de log devem ser especificados na configuração e não no código.

Função Filter

Uma função de filtro é invocada para todos os provedores e categorias que não têm regras atribuídas a eles por configuração ou código:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

O código anterior exibe os logs do console quando a categoria contém Controller ou Microsoft e o nível de log é Information ou superior.

Em geral, os níveis de log devem ser especificados na configuração e não no código.

ASP.NET Core e EF Core categorias

A tabela a seguir contém algumas categorias usadas por ASP.NET Core e Entity Framework Core, com observações sobre os logs:

Categoria Observações
Microsoft.AspNetCore Diagnóstico geral de ASP.NET Core.
Microsoft.AspNetCore.DataProtection Quais chaves foram consideradas, encontradas e usadas.
Microsoft.AspNetCore.HostFiltering Hosts permitidos.
Microsoft.AspNetCore.Hosting Quanto tempo levou para que as solicitações de HTTP fossem concluídas e em que horário foram iniciadas. Quais assemblies de inicialização de hospedagem foram carregados.
Microsoft.AspNetCore.Mvc MVC e Razor diagnóstico. Model binding, execução de filtro, compilação de exibição, seleção de ação.
Microsoft.AspNetCore.Routing Informações de correspondência de rotas.
Microsoft.AspNetCore.Server Respostas de início, parada e atividade da conexão. Informações sobre o certificado HTTPS.
Microsoft.AspNetCore.StaticFiles Arquivos atendidos.
Microsoft.EntityFrameworkCore Diagnóstico geral do Entity Framework Core. Atividade e configuração do banco de dados, detecção de alterações, migrações.

Para exibir mais categorias na janela do console, de definido appsettings.Development.json como o seguinte:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Escopos de log

Um escopo pode agrupar um conjunto de operações lógicas. Esse agrupamento pode ser usado para anexar os mesmos dados para cada log criado como parte de um conjunto. Por exemplo, todo log criado como parte do processamento de uma transação pode incluir a ID da transação.

Um escopo:

Os seguintes provedores suportam escopos:

Use um escopo por meio do encapsulamento de chamadas de agente em um bloco using:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Provedores de log internos

ASP.NET Core inclui os seguintes provedores de log como parte da estrutura compartilhada:

Os provedores de log a seguir são enviados pela Microsoft, mas não como parte da estrutura compartilhada. Eles devem ser instalados como nuget adicional.

ASP.NET Core não inclui um provedor de log para a escrita de logs em arquivos. Para gravar logs em arquivos de um ASP.NET Core, considere usar um provedor de log de terceiros.

stdout Para obter informações sobre e depurar o registro em log com o módulo ASP.NET Core, consulte Solucionar problemas ASP.NET Core no Serviço de Aplicativo do Azure e no IIS e no MÓDULO ASP.NET Core (ANCM) para IIS.

Console

O Console provedor registra a saída no console. Para obter mais informações sobre como exibir Console logs em desenvolvimento, consulte Log output from dotnet run and Visual Studio.

Depurar

O Debug provedor grava a saída do log usando a System.Diagnostics.Debug classe . Chama para System.Diagnostics.Debug.WriteLine gravar no Debug provedor.

No Linux, o local Debug do log do provedor depende da distribuição e pode ser um dos seguintes:

  • /var/log/message
  • /var/log/syslog

Origem do Evento

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

Ferramentas de rastreamento dotnet

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

Consulte dotnet-trace para obter instruções de instalação.

Use as ferramentas de rastreamento dotnet para coletar um rastreamento de um aplicativo:

  1. Execute o aplicativo com o dotnet run comando .

  2. Determine o PID (identificador de processo) do aplicativo .NET Core:

    dotnet trace ps
    

    Encontre o PID para o processo que tem o mesmo nome que o assembly do aplicativo.

  3. Execute o comando dotnet trace.

    Sintaxe de comando geral:

    dotnet trace collect -p {PID} 
        --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Category Level 1};
                {Logger Category 2}:{Category Level 2};
                ...
                {Logger Category N}:{Category Level N}\"
    

    Ao usar um shell de comando do PowerShell, coloque o --providers valor entre aspas simples ('):

    dotnet trace collect -p {PID} 
        --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Category Level 1};
                {Logger Category 2}:{Category Level 2};
                ...
                {Logger Category N}:{Category Level N}\"'
    

    Em plataformas Windows, adicione a -f speedscope opção para alterar o formato do arquivo de rastreamento de saída para speedscope.

    A tabela a seguir define a palavra-chave :

    Palavra-chave Descrição
    1 Registrar metadados em log sobre o LoggingEventSource. Não registra eventos de ILogger.
    2 Liga o evento Message quando ILogger.Log() é chamado. Fornece informações de maneira programática (não formatada).
    4 Liga o evento FormatMessage quando ILogger.Log() é chamado. Fornece a versão de cadeia de caracteres formatada das informações.
    8 Liga o evento MessageJson quando ILogger.Log() é chamado. Fornece uma representação JSON dos argumentos.

    A tabela a seguir lista os níveis do provedor:

    Nível do provedor Descrição
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    A análise de um nível de categoria pode ser uma cadeia de caracteres ou um número:

    Valor nomeado da categoria Valor numérico
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    O nível do provedor e o nível de categoria:

    • Estão em ordem inversa.
    • As constantes de cadeia de caracteres não são idênticas.

    Se nenhum FilterSpecs for especificado, a implementação EventSourceLogger tentará converter o nível do provedor em um nível de categoria e o aplicará a todas as categorias.

    Nível do provedor Nível da categoria
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    Se FilterSpecs for fornecida, qualquer categoria incluída na lista usará o nível de categoria codificado lá, todas as outras categorias serão filtradas.

    Os exemplos a seguir pressupom:

    • Um aplicativo está em execução e chamando logger.LogDebug("12345").
    • A ID do processo (PID) foi definida por meio de set PID=12345, em que 12345 é o PID real.

    Considere o seguinte código:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
    

    O comando anterior:

    • Captura mensagens de depuração.
    • Não aplica um FilterSpecs.
    • Especifica o nível 5 que mapeia a categoria Depuração.

    Considere o seguinte código:

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
    

    O comando anterior:

    • Não captura mensagens de depuração porque o nível de categoria 5 é Critical.
    • Fornece um FilterSpecs.

    O comando a seguir captura mensagens de depuração porque o nível de categoria 1 especifica Debug.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
    

    O comando a seguir captura mensagens de depuração porque a categoria especifica Debug.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
    

    FilterSpecs entradas para e representam {Logger Category} condições {Category Level} de filtragem de log adicionais. Separe FilterSpecs entradas com o caractere ; de ponto e vírgula.

    Exemplo usando um shell Windows comando:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
    

    O comando anterior ativa:

    • O logger de Origem do Evento para produzir cadeias de caracteres formatadas (4) para erros (2).
    • Microsoft.AspNetCore.Hosting registro em log no nível Informational de log (4).
  4. Pare as ferramentas de rastreamento dotnet pressionando a tecla Enter ou Ctrl+C.

    O rastreamento é salvo com o nome trace.nettrace na pasta em que o dotnet trace comando é executado.

  5. Abra o rastreamento com Perfview. Abra o arquivo trace.nettrace e explore os eventos de rastreamento.

Se o aplicativo não criar o host com , adicione o provedor CreateDefaultBuilderde Origem do Evento à configuração de log do aplicativo.

Para obter mais informações, consulte:

Perfview

Use o utilitário PerfView para coletar e exibir logs. Há outras ferramentas para exibir os logs do ETW, mas o PerfView proporciona a melhor experiência para trabalhar com os eventos de ETW emitidos pelo ASP.NET Core.

Para configurar o PerfView para coletar eventos registrados por esse provedor, adicione a cadeia de caracteres *Microsoft-Extensions-Logging à lista Provedores Adicionais. Não perca o no * início da cadeia de caracteres.

EventLog do Windows

O EventLog provedor envia a saída de log para o log Windows log de eventos. Ao contrário dos outros provedores, o EventLog provedor não herda as configurações padrão de não provedor. Se EventLog as configurações de log não são especificadas, elas assumem Como padrão LogLevel.Warning.

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

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

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

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

O código a seguir altera SourceName o do valor padrão de ".NET Runtime" para MyLogs:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

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 na estrutura compartilhada. 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:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

Quando implantado no Serviço de Aplicativo do Azure, o aplicativo usa as configurações na seção Serviço de Aplicativo logs 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.

  • Log de aplicativo (Sistema de Arquivos)
  • Log de aplicativo (Blob)

O local padrão para arquivos de log está na pasta D:\home\LogFiles\Application e o nome de arquivo padrão é 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. O nome de blob padrão é {app-name}{timestamp}/aaaa/mm/dd/hh/{guid}-applicationLog.txt.

Esse provedor só registra em logs quando o projeto é executado no ambiente do Azure.

Fluxo de log do Azure

O streaming de log do Azure dá suporte à exibição da atividade de log em tempo real de:

  • 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 Serviço de Aplicativo de logs da página do 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 Logs para exibir logs. As mensagens registradas são registradas com a ILogger interface .

Azure Application Insights

O pacote do provedor Microsoft.Extensions.Logging.ApplicationInsights grava logs em Aplicativo Azure 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.

O provedor de registro em log está incluído como uma dependência de Microsoft.ApplicationInsights.AspNetCore, que é o pacote que fornece toda a telemetria disponível para o ASP.NET Core. Se você usar esse pacote, não precisará instalar o pacote de provedor.

O pacote Microsoft.ApplicationInsights.Web é para ASP.NET 4.x, não ASP.NET Core.

Para saber mais, consulte os recursos a seguir:

Provedores de log de terceiros

Estruturas de log de terceiros que funcionam com o ASP.NET Core:

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 ILoggerFactory de extensão fornecido pela estrutura de registro em log.

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

Aplicativo de console não host

Para ver um exemplo de como usar o Host Genérico em um aplicativo de console não Web, Program.cs consulte o arquivo do aplicativo de exemplo Tarefas em Segundo Plano (Tarefas em segundo plano com serviços hospedados no ASP.NET Core).

O código de registro em log de aplicativos sem host genérico difere na maneira como os provedores são adicionados e como os agentes são criados.

Provedores de log

Em um aplicativo de console não host, chame o método de extensão Add{provider name} do provedor ao criar um LoggerFactory:

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Criar logs

Para criar logs, use um objeto ILogger<TCategoryName>. Use o LoggerFactory para criar um ILogger.

O exemplo a seguir cria um logger com LoggingConsoleApp.Program como a categoria .

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

No exemplo a seguir, o logger é usado para criar logs com Information como o nível . O nível de log indica a gravidade do evento registrado.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Níveis e categorias são explicados mais detalhadamente neste documento.

Log durante a construção do host

Não há suporte direto para o registro em log durante a construção do host. No entanto, um logger separado pode ser usado. No exemplo a seguir, um log de Serilog é usado para fazer logoff em CreateHostBuilder. AddSerilog usa a configuração estática especificada em Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Configurar um serviço que depende do ILogger

A injeção de construtor de um agente em Startup funciona em versões anteriores do ASP.NET Core porque um contêiner de DI separado é criado para o host da Web. Para obter informações sobre por que apenas um contêiner é criado para o host genérico, consulte o anúncio de alteração da falha.

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 ILogger<T> instância fornecida pela DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

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

Criar logs no Main

O código a seguir faz logo login Main ao obter uma instância ILogger da DI depois de criar o host:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Criar logs na inicialização

O código a seguir grava logs em Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

A gravação de logs antes da conclusão da configuração do contêiner de DI no método Startup.ConfigureServices não é uma ação compatível:

  • A injeção de agente no construtor Startup não é uma ação compatível.
  • A injeção de agente na assinatura do método Startup.ConfigureServices não é uma ação compatível

O motivo para essa restrição é que o registro em log depende da DI e da configuração, a qual por sua vez depende da DI. O contêiner de DI não é configurado até ConfigureServices ser concluído.

Para obter informações sobre como configurar um serviço que depende ILogger<T> ou por que a injeção de construtor de um agente de log Startup funciona em versões anteriores, consulte configurar um serviço que depende do ILogger

Sem métodos de agente assíncronos

O registro em log deve ser tão rápido que não justifique o custo de desempenho de código assíncrono. Se um armazenamento de dados de log estiver lento, não grave-o diretamente. Considere gravar as mensagens de log em um repositório rápido inicialmente e, em seguida, movê-las para o armazenamento lento mais tarde. por exemplo, ao fazer logon no SQL Server, não faça isso diretamente em um Log método, pois os Log métodos são síncronos. Em vez disso, adicione mensagens de log de forma síncrona a uma fila na memória e faça com que uma função de trabalho de plano de fundo efetue pull das mensagens para fora da fila para fazer o trabalho assíncrono de envio de dados por push para o SQL Server. para obter mais informações, consulte este GitHub problema.

Alterar os níveis de log em um aplicativo em execução

A API de registro em log não inclui um cenário para alterar os níveis de log enquanto um aplicativo está em execução. No entanto, alguns provedores de configuração são capazes de recarregar a configuração, o que exige um efeito imediato na configuração de log. Por exemplo, o provedor de configuração de arquivo, recarrega a configuração de log por padrão. Se a configuração for alterada no código enquanto um aplicativo estiver em execução, o aplicativo poderá chamar IConfigurationRoot.Reload para atualizar a configuração de log do aplicativo.

ILogger e ILoggerFactory

ILoggerFactoryAs ILogger<TCategoryName> interfaces e implementações são incluídas no SDK do .NET Core. eles também estão disponíveis nos seguintes pacotes de NuGet:

Aplicar regras de filtro de log no código

A abordagem preferida para definir regras de filtro de log é usando a configuraçãodo.

O exemplo a seguir mostra como registrar regras de filtro no código:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

logging.AddFilter("System", LogLevel.Debug)Especifica a categoria e o nível Debug de System log. O filtro é aplicado a todos os provedores porque um provedor específico não foi configurado.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) especificado

  • O provedor de Debug log.
  • Nível Information de log e superior.
  • Todas as categorias que começam com "Microsoft" .

Registrar automaticamente o escopo com Spanid, TraceID e ParentId

As bibliotecas de registro em log criam implicitamente um objeto de escopo com SpanId , TraceId e ParentId . Esse comportamento é configurado via ActivityTrackingOptions .

  var loggerFactory = LoggerFactory.Create(logging =>
  {
      logging.Configure(options =>
      {
          options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                              | ActivityTrackingOptions.TraceId
                                              | ActivityTrackingOptions.ParentId;
      }).AddSimpleConsole(options =>
      {
          options.IncludeScopes = true;
      });
  });

Se o traceparent cabeçalho de solicitação HTTP for definido, o ParentId no escopo de log mostrará o W3C parent-id do cabeçalho na associação traceparent e o SpanId no escopo do log mostrará a atualização parent-id para o próximo passo/span fora associado. Para obter mais informações, consulte mutando o campo traceparent.

Criar um agente de log personalizado

Para criar um agente personalizado, consulte implementar um provedor de log personalizado no .net.

Recursos adicionais