Como fazer registro em log no .NET Core e no ASP.NET CoreLogging in .NET Core and ASP.NET Core

Por Tom Dykstra e Steve SmithBy Tom Dykstra and Steve Smith

O .NET Core oferece suporte a uma API de registro em log que funciona com uma variedade de provedores de logs internos e terceirizados..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Este artigo mostra como usar a API de registro em log com provedores internos.This article shows how to use the logging API with built-in providers.

A maioria dos exemplos de código mostrados neste artigo é de aplicativos ASP.NET Core.Most of the code examples shown in this article are from ASP.NET Core apps. As partes específicas de log desses trechos de código se aplicam a qualquer aplicativo .NET Core que usa o host genérico.The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. Para obter um exemplo de como usar o host genérico em um aplicativo de console não Web, consulte o arquivo Program.cs do aplicativo de exemplo de tarefas em segundo plano (Tarefas em segundo plano com serviços hospedados no ASP.NET Core).For an example of how to use the Generic Host in a non-web console app, see the Program.cs file of the Background Tasks sample app (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.Logging code for apps without Generic Host differs in the way providers are added and loggers are created. Exemplos de código não host são mostrados nessas seções do artigo.Non-host code examples are shown in those sections of the article.

Exibir ou baixar código de exemplo (como baixar)View or download sample code (how to download)

Adicionar provedoresAdd providers

Um provedor de log exibe ou armazena logs.A logging provider displays or stores logs. Por exemplo, o provedor de Console exibe os logs no console, e o provedor do Azure Application Insights armazena-os no Azure Application Insights.For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. Os logs podem ser enviados para vários destinos por meio da adição de vários provedores.Logs can be sent to multiple destinations by adding multiple providers.

Para adicionar um provedor em um aplicativo que usa um host genérico, chame o método de extensão Add{provider name} do provedor no Program.cs:To add a provider in an app that uses Generic Host, call the provider's Add{provider name} extension method in Program.cs:

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

Em um aplicativo de console não host, chame o método de extensão Add{provider name} do provedor ao criar um LoggerFactory:In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory:

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

LoggerFactory e AddConsole exigem uma instrução using para Microsoft.Extensions.Logging.LoggerFactory and AddConsole require a using statement for Microsoft.Extensions.Logging.

Os modelos de projeto padrão do ASP.NET Core chamam CreateDefaultBuilder, que adiciona os seguintes provedores de log:The default ASP.NET Core project templates call CreateDefaultBuilder, which adds the following logging providers:

Você pode substituir os provedores padrão por aqueles de sua preferência.You can replace the default providers with your own choices. Chame ClearProviders e adicione os provedores desejados.Call ClearProviders, and add the providers you want.

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

Para adicionar um provedor, chame o método de extensão Add{provider name} do provedor no Program.cs:To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

O código anterior requer referências a Microsoft.Extensions.Logging e Microsoft.Extensions.Configuration.The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

O modelo de projeto padrão chama o CreateDefaultBuilder, que adiciona os seguintes provedores de log:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • Console doConsole
  • DepuraçãoDebug
  • EventSource (a partir do ASP.NET Core 2.2)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Se você usar CreateDefaultBuilder, poderá substituir os provedores padrão por aqueles que preferir.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Chame ClearProviders e adicione os provedores desejados.Call ClearProviders, and add the providers you want.

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Saiba mais sobre provedores de log internos e provedores de log de terceiros mais adiante no artigo.Learn more about built-in logging providers and third-party logging providers later in the article.

Criar logsCreate logs

Para criar logs, use um objeto ILogger<TCategoryName>.To create logs, use an ILogger<TCategoryName> object. Em um aplicativo Web ou serviço hospedado, obtenha um ILogger da DI (injeção de dependência).In a web app or hosted service, get an ILogger from dependency injection (DI). Em aplicativos de console não host, use o LoggerFactory para criar um ILogger.In non-host console apps, use the LoggerFactory to create an ILogger.

O exemplo do ASP.NET Core a seguir cria um agente de categoria TodoApiSample.Pages.AboutModel.The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. A categoria do log é uma cadeia de caracteres associada a cada log.The log category is a string that is associated with each log. A instância de ILogger<T> cria logs que têm como a categoria o nome totalmente qualificado do tipo T.The ILogger<T> instance provided by DI creates logs that have the fully qualified name of type T as the category.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

O exemplo do aplicativo de console não host a seguir cria um agente de categoria LoggingConsoleApp.Program.The following non-host console app example creates a logger with LoggingConsoleApp.Program as the category.

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");
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

Nos exemplos de ASP.NET Core e aplicativo de console a seguir, o agente é usado para criar logs de nível Information.In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. O nível de log indica a gravidade do evento registrado.The Log level indicates the severity of the logged event.

public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}
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");
public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}

Níveis e categorias serão explicados com mais detalhes posteriormente neste artigo.Levels and categories are explained in more detail later in this article.

Criar logs na classe ProgramaCreate logs in the Program class

Para gravar logs na classe Program de um aplicativo ASP.NET Core, obtenha uma instância de ILogger por meio da DI após compilar o host:To write logs in the Program class of an ASP.NET Core app, get an ILogger instance from DI after building the host:

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    IMyService myService = host.Services.GetRequiredService<IMyService>();
    myService.WriteLog("Logged from MyService.");

    host.Run();
}

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

Não há suporte direto para o registro em log durante a construção do host.Logging during host construction isn't directly supported. No entanto, um agente separado pode ser usado.However, a separate logger can be used. No exemplo a seguir, um agente de log do Serilog é usado para fazer logon CreateHostBuilder.In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilog usa a configuração estática especificada em Log.Logger:AddSerilog uses the static configuration specified in 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();
        }
    }
}

Criar logs na classe StartupCreate logs in the Startup class

Para gravar logs no método Startup.Configure de um aplicativo ASP.NET Core, inclua um parâmetro ILogger na assinatura do método:To write logs in the Startup.Configure method of an ASP.NET Core app, include an ILogger parameter in the method signature:

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

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

    app.UseRouting();

    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:Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • A injeção de agente no construtor Startup não é uma ação compatível.Logger injection into the Startup constructor is not supported.
  • A injeção de agente na assinatura do método Startup.ConfigureServices não é uma ação compatívelLogger injection into the Startup.ConfigureServices method signature is not supported

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.The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. O contêiner de DI não é configurado até ConfigureServices ser concluído.The DI container isn't set up until ConfigureServices finishes.

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.Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI container is created for the Web Host. 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.For information about why only one container is created for the Generic Host, see the breaking change announcement.

Se precisar configurar um serviço que dependa de ILogger<T>, você ainda poderá fazer isso usando a injeção de construtor ou fornecendo um método de fábrica.If you need to configure a service that depends on ILogger<T>, you can still do that by using constructor injection or by providing a factory method. A abordagem do método de fábrica é recomendada somente se não há nenhuma outra opção.The factory method approach is recommended only if there is no other option. Por exemplo, suponha que você precise preencher uma propriedade com um serviço da DI:For example, suppose you need to fill a property with a service from 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 };
    });

    services.AddSingleton<ITodoRepository, TodoRepository>();
}

O código realçado anterior é um Func que é executado na primeira vez que o contêiner de DI precisa construir uma instância de MyService.The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. Você pode acessar qualquer um dos serviços registrados dessa maneira.You can access any of the registered services in this way.

Criar logs na inicializaçãoCreate logs in Startup

Para gravar logs na classe Startup, inclua um parâmetro ILogger na assinatura de construtor:To write logs in the Startup class, include an ILogger parameter in the constructor signature:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseMvc();
    }
}

Criar logs na classe ProgramaCreate logs in the Program class

Para gravar logs na classe Program, obtenha uma instância ILogger da DI:To write logs in the Program class, get an ILogger instance from DI:

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Não há suporte direto para o registro em log durante a construção do host.Logging during host construction isn't directly supported. No entanto, um agente separado pode ser usado.However, a separate logger can be used. No exemplo a seguir, um agente de log do Serilog é usado para fazer logon CreateWebHostBuilder.In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilog usa a configuração estática especificada em Log.Logger:AddSerilog uses the static configuration specified in Log.Logger:

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

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

    public static IWebHostBuilder CreateWebHostBuilder(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 WebHost.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddMvc();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {
                    logging.AddSerilog();
                })
                .UseStartup<Startup>();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

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

Sem métodos de agente assíncronosNo asynchronous logger methods

O registro em log deve ser tão rápido que não justifique o custo de desempenho de código assíncrono.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Se o armazenamento de dados em log estiver lento, não grave diretamente nele.If your logging data store is slow, don't write to it directly. Grave as mensagens de log em um repositório rápido primeiro e, depois, mova-as para um repositório lento.Consider writing the log messages to a fast store initially, then move them to the slow store later. Por exemplo, se você estiver enviado logs para o SQL Server, convém não fazer isso diretamente em um método Log, uma vez que os métodos Log são síncronos.For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. 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.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Para obter mais informações, consulte este problema do github.For more information, see this GitHub issue.

Configuração doConfiguration

A configuração do provedor de logs é fornecida por um ou mais provedores de sincronização:Logging provider configuration is provided by one or more configuration providers:

  • Formatos de arquivo (INI, JSON e XML).File formats (INI, JSON, and XML).
  • Argumentos de linha de comando.Command-line arguments.
  • Variáveis de ambiente.Environment variables.
  • Objetos do .NET na memória.In-memory .NET objects.
  • O armazenamento do Secret Manager não criptografado.The unencrypted Secret Manager storage.
  • Um repositório de usuário criptografado, como o Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Provedores personalizados (instalados ou criados).Custom providers (installed or created).

Por exemplo, a configuração de log geralmente é fornecida pela seção Logging dos arquivos de configurações do aplicativo.For example, logging configuration is commonly provided by the Logging section of app settings files. O exemplo a seguir mostra o conteúdo de um típico arquivo appsettings.Development.json:The following example shows the contents of a typical appsettings.Development.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console":
    {
      "IncludeScopes": true
    }
  }
}

A propriedade Logging pode ter LogLevel e propriedades do provedor de logs (o Console é mostrado).The Logging property can have LogLevel and log provider properties (Console is shown).

A propriedade LogLevel em Logging especifica o nível mínimo para log nas categorias selecionadas.The LogLevel property under Logging specifies the minimum level to log for selected categories. No exemplo, as categorias System e Microsoft têm log no nível Information, e todas as outras no nível Debug.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Outras propriedades em Logging especificam provedores de logs.Other properties under Logging specify logging providers. O exemplo se refere ao provedor de Console.The example is for the Console provider. Se um provedor oferecer suporte a escopos de log, IncludeScopes indicará se eles estão habilitados.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Uma propriedade de provedor (como Console, no exemplo) também pode especificar uma propriedade LogLevel.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel em um provedor especifica os níveis de log para esse provedor.LogLevel under a provider specifies levels to log for that provider.

Se os níveis forem especificados em Logging.{providername}.LogLevel, eles substituirão o que estiver definido em Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel.

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.The Logging API doesn't include a scenario to change log levels while an app is running. 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.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Por exemplo, o provedor de configuração de arquivo, que é adicionado pelo CreateDefaultBuilder para ler arquivos de configuração, recarrega a configuração de log por padrão.For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. Se a configuração for alterada no código enquanto um aplicativo estiver em execução, o aplicativo poderá chamar IConfigurationRoot. recarregar para atualizar a configuração de log do aplicativo.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

Saiba mais sobre como implementar provedores de configuração em Configuração no ASP.NET Core.For information on implementing configuration providers, see Configuração no ASP.NET Core.

Exemplo de saída de registro em logSample logging output

Com o código de exemplo mostrado na seção anterior, os logs serão exibidos no console quando o aplicativo for executado pela linha de comando.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Aqui está um exemplo da saída do console:Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 84.26180000000001ms 307
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/api/todo/0
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
info: TodoApiSample.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

Os logs anteriores foram gerados por meio de uma solicitação HTTP Get para o aplicativo de exemplo em http://localhost:5000/api/todo/0.The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Veja um exemplo de como os mesmos logs aparecem na janela Depuração quando você executa o aplicativo de exemplo no Visual Studio:Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual Studio:

Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request starting HTTP/2.0 GET https://localhost:44328/api/todo/0  
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
TodoApiSample.Controllers.TodoController: Information: Getting item 0
TodoApiSample.Controllers.TodoController: Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult: Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 34.167ms
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request finished in 98.41300000000001ms 404

Os logs criados pelas chamadas ILogger mostradas na seção anterior começam com "TodoApiSample".The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApiSample". Os logs que começam com categorias "Microsoft" são de código da estrutura ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. O ASP.NET Core e o código do aplicativo estão usando a mesma API de registro em log e os mesmos provedores.ASP.NET Core and application code are using the same logging API and providers.

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

Os logs criados pelas chamadas ILogger mostradas na seção anterior começam com "TodoApi".The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". Os logs que começam com categorias "Microsoft" são de código da estrutura ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. O ASP.NET Core e o código do aplicativo estão usando a mesma API de registro em log e os mesmos provedores.ASP.NET Core and application code are using the same logging API and providers.

O restante deste artigo explica alguns detalhes e opções para registro em log.The remainder of this article explains some details and options for logging.

Pacotes NuGetNuGet packages

As interfaces ILogger e ILoggerFactory estão em Microsoft.Extensions.Logging.Abstractions e as implementações padrão para elas estão em Microsoft.Extensions.Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

Categoria de logLog category

Quando um objeto ILogger é criado, uma categoria é especificada para ele.When an ILogger object is created, a category is specified for it. Essa categoria é incluída em cada mensagem de log criada por essa instância de ILogger.That category is included with each log message created by that instance of ILogger. A categoria pode ser qualquer cadeia de caracteres, mas a convenção é usar o nome da classe, como "TodoApi.Controllers.TodoController".The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Use ILogger<T> para obter uma instância ILogger que usa o nome de tipo totalmente qualificado do T como a categoria:Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

Para especificar explicitamente a categoria, chame ILoggerFactory.CreateLogger:To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

ILogger<T> é equivalente a chamar CreateLogger com o nome de tipo totalmente qualificado de T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Nível de logLog level

Todo log especifica um valor LogLevel.Every log specifies a LogLevel value. O nível de log indica a gravidade ou importância.The log level indicates the severity or importance. Por exemplo, você pode gravar um log Information quando um método é finalizado normalmente e um log Warning quando um método retorna um código de status 404 Não Encontrado.For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

O código a seguir cria os logs Information e Warning:The following code creates Information and Warning logs:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

No código anterior, o primeiro parâmetro é a ID de evento de log.In the preceding code, the first parameter is the Log event ID. O segundo parâmetro é um modelo de mensagem com espaços reservados para valores de argumento fornecidos pelos parâmetros de método restantes.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Os parâmetros de método serão explicados com posteriormente neste artigo, na seção de modelos de mensagem.The method parameters are explained in the message template section later in this article.

Os métodos de log que incluem o nível no nome do método (por exemplo, LogInformation e LogWarning) são métodos de extensão para ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Esses métodos chamam um método Log que recebe um parâmetro LogLevel.These methods call a Log method that takes a LogLevel parameter. Você pode chamar o método Log diretamente em vez de um desses métodos de extensão, mas a sintaxe é relativamente complicada.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Para saber mais, veja ILogger e o código-fonte de extensões de agente.For more information, see ILogger and the logger extensions source code.

O ASP.NET Core define os seguintes níveis de log, ordenados aqui da menor para a maior gravidade.ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Trace = 0Trace = 0

    Para obter informações que normalmente são valiosas somente para depuração.For information that's typically valuable only for debugging. Essas mensagens podem conter dados confidenciais de aplicativos e, portanto, não devem ser habilitadas em um ambiente de produção.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Desabilitado por padrão.Disabled by default.

  • Debug = 1Debug = 1

    Para obter informações que possam ser úteis durante o desenvolvimento e a depuração.For information that may be useful in development and debugging. Exemplo: Entering method Configure with flag set to true. habilite logs de nível Debug em produção somente ao solucionar problemas, devido ao alto volume de logs.Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Information = 2Information = 2

    Para rastrear o fluxo geral do aplicativo.For tracking the general flow of the app. Esses logs normalmente têm algum valor a longo prazo.These logs typically have some long-term value. Exemplo: Request received for path /api/todoExample: Request received for path /api/todo

  • Warning = 3Warning = 3

    Para eventos anormais ou inesperados no fluxo de aplicativo.For abnormal or unexpected events in the app flow. Eles podem incluir erros ou outras condições que não fazem com que o aplicativo pare, mas que talvez precisem ser investigados.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Exceções manipuladas são um local comum para usar o nível de log Warning.Handled exceptions are a common place to use the Warning log level. Exemplo: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Erro = 4Error = 4

    Para erros e exceções que não podem ser manipulados.For errors and exceptions that cannot be handled. Essas mensagens indicam uma falha na atividade ou na operação atual (como a solicitação HTTP atual) e não uma falha em todo o aplicativo.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Mensagem de log de exemplo:Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Critical = 5Critical = 5

    Para falhas que exigem atenção imediata.For failures that require immediate attention. Exemplos: cenários de perda de dados, espaço em disco insuficiente.Examples: data loss scenarios, out of disk space.

Use o nível de log para controlar a quantidade de saída de log que é gravada em uma mídia de armazenamento específica ou em uma janela de exibição.Use the log level to control how much log output is written to a particular storage medium or display window. Por exemplo:For example:

  • Em produção:In production:
    • O registro em log na Trace por meio de níveis de Information produz um alto volume de mensagens de log detalhadas.Logging at the Trace through Information levels produces a high-volume of detailed log messages. Para controlar os custos e não exceder os limites de armazenamento de dados, Trace de log por meio de mensagens de nível de Information para um armazenamento de dados de alto volume e baixo custo.To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • O registro em log em Warning por meio de níveis de Critical produz menos mensagens de log menores.Logging at Warning through Critical levels typically produces fewer, smaller log messages. Portanto, os custos e os limites de armazenamento geralmente não são uma preocupação, o que resulta em maior flexibilidade de escolha de armazenamento de dados.Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • Durante o desenvolvimento:During development:
    • Warning de log por meio de mensagens de Critical para o console.Log Warning through Critical messages to the console.
    • Adicione Trace por meio de mensagens Information ao solucionar o problema.Add Trace through Information messages when troubleshooting.

A seção Filtragem de log mais adiante neste artigo explicará como controlar os níveis de log que um provedor manipula.The Log filtering section later in this article explains how to control which log levels a provider handles.

O ASP.NET Core grava logs para eventos de estrutura.ASP.NET Core writes logs for framework events. Os exemplos de log anteriores neste artigo excluíram logs abaixo do nível Information, portanto, logs de nível Debug ou Trace não foram criados.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Veja um exemplo de logs de console produzidos por meio da execução do aplicativo de exemplo configurado para mostrar logs Debug:Here's an example of console logs produced by running the sample app configured to show Debug logs:

info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of authorization filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of resource filters (in the following order): Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of action filters (in the following order): Microsoft.AspNetCore.Mvc.Filters.ControllerActionFilter (Order: -2147483648), Microsoft.AspNetCore.Mvc.ModelBinding.UnsupportedContentTypeFilter (Order: -3000)
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of exception filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of result filters (in the following order): Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[22]
      Attempting to bind parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[44]
      Attempting to bind parameter 'id' of type 'System.String' using the name 'id' in request data ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[45]
      Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[23]
      Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[26]
      Attempting to validate the bound parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[27]
      Done attempting to validate the bound parameter 'id' of type 'System.String'.
info: TodoApiSample.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[2]
      Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 32.690400000000004ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 176.9103ms 404
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

ID de evento de logLog event ID

Cada log pode especificar uma ID do evento.Each log can specify an event ID. O aplicativo de exemplo faz isso usando uma classe LoggingEvents definida localmente:The sample app does this by using a locally defined LoggingEvents class:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    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 GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    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 GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

Uma ID de evento associa um conjunto de eventos.An event ID associates a set of events. Por exemplo, todos os logs relacionados à exibição de uma lista de itens em uma página podem ser 1001.For example, all logs related to displaying a list of items on a page might be 1001.

O provedor de logs pode armazenar a ID do evento em um campo de ID na mensagem de log ou não armazenar.The logging provider may store the event ID in an ID field, in the logging message, or not at all. O provedor de Depuração não mostra IDs de eventos.The Debug provider doesn't show event IDs. O provedor de console mostra IDs de evento entre colchetes após a categoria:The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

Modelo de mensagem de logLog message template

Cada log especifica um modelo de mensagem.Each log specifies a message template. O modelo de mensagem pode conter espaços reservados para os quais são fornecidos argumentos.The message template can contain placeholders for which arguments are provided. Use nomes para os espaços reservados, não números.Use names for the placeholders, not numbers.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

A ordem dos espaços reservados e não de seus nomes, determina quais parâmetros serão usados para fornecer seus valores.The order of placeholders, not their names, determines which parameters are used to provide their values. No código a seguir, observe que os nomes de parâmetro estão fora de sequência no modelo de mensagem:In the following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Esse código cria uma mensagem de log com os valores de parâmetro na sequência:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

A estrutura de registros funciona dessa maneira para que os provedores de logs possam implementar registro em log semântico, também conhecido como registro em log estruturado.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Os próprios argumentos são passados para o sistema de registro em log, não apenas o modelo de mensagem formatado.The arguments themselves are passed to the logging system, not just the formatted message template. Essas informações permitem que os provedores de log armazenem os valores de parâmetro como campos.This information enables logging providers to store the parameter values as fields. Por exemplo, suponha que as chamadas de método do agente sejam assim:For example, suppose logger method calls look like this:

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

Se você estiver enviando os logs para o Armazenamento de Tabelas do Azure, cada entidade da Tabela do Azure poderá ter propriedades ID e RequestTime, o que simplificará as consultas nos dados de log.If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. Uma consulta pode encontrar todos os logs em determinado intervalo de RequestTime sem analisar o tempo limite da mensagem de texto.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Exceções de registro em logLogging exceptions

Os métodos de agente têm sobrecargas que permitem que você passe uma exceção, como no exemplo a seguir:The logger methods have overloads that let you pass in an exception, as in the following example:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);
catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Provedores diferentes manipulam as informações de exceção de maneiras diferentes.Different providers handle the exception information in different ways. Aqui está um exemplo da saída do provedor Depuração do código mostrado acima.Here's an example of Debug provider output from the code shown above.

TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.
   at TodoApiSample.Controllers.TodoController.GetById(String id) in C:\TodoApiSample\Controllers\TodoController.cs:line 226

Filtragem de logLog filtering

Você pode especificar um nível de log mínimo para um provedor e uma categoria específicos ou para todos os provedores ou todas as categorias.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Os logs abaixo do nível mínimo não serão passados para esse provedor, para que não sejam exibidos ou armazenados.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Para suprimir todos os logs, especifique LogLevel.None como o nível de log mínimo.To suppress all logs, specify LogLevel.None as the minimum log level. O valor inteiro de LogLevel.None é 6, que é maior do que LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Criar regras de filtro na configuraçãoCreate filter rules in configuration

O código de modelo de projeto chama CreateDefaultBuilder para configurar o registro em log para os provedores console, Debug e EventSource (ASP.NET Core 2,2 ou posteriores).The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. O método CreateDefaultBuilder configura o registro em log para procurar a configuração em uma seção Logging, conforme explicado anteriormente neste artigo.The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

Os dados de configuração especificam níveis de log mínimo por provedor e por categoria, como no exemplo a seguir:The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}
{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Este JSON cria seis regras de filtro, uma para o provedor Depuração, quatro para o provedor Console e uma para todos os provedores.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Apenas uma regra é escolhida para cada provedor quando um objeto ILogger é criado.A single rule is chosen for each provider when an ILogger object is created.

Regras de filtro no códigoFilter rules in code

O exemplo a seguir mostra como registrar regras de filtro no código:The following example shows how to register filter rules in code:

.ConfigureLogging(logging =>
    logging.AddFilter("System", LogLevel.Debug)
           .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))
WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

O segundo AddFilter especifica o provedor Depuração usando seu nome de tipo.The second AddFilter specifies the Debug provider by using its type name. O primeiro AddFilter se aplica a todos os provedores porque ele não especifica um tipo de provedor.The first AddFilter applies to all providers because it doesn't specify a provider type.

Como as regras de filtragem são aplicadasHow filtering rules are applied

Os dados de configuração e o código AddFilter, mostrados nos exemplos anteriores, criam as regras mostradas na tabela a seguir.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. As primeiras seis vêm do exemplo de configuração e as últimas duas vêm do exemplo de código.The first six come from the configuration example and the last two come from the code example.

NúmeroNumber ProviderProvider Categorias que começam com...Categories that begin with ... Nível de log mínimoMinimum log level
11 DepuraçãoDebug Todas as categoriasAll categories Informações doInformation
22 Console doConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal AvisoWarning
33 Console doConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor DepuraçãoDebug
44 Console doConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor Erro doError
55 Console doConsole Todas as categoriasAll categories Informações doInformation
66 Todos os provedoresAll providers Todas as categoriasAll categories DepuraçãoDebug
77 Todos os provedoresAll providers SystemSystem DepuraçãoDebug
88 DepuraçãoDebug MicrosoftMicrosoft RastreamentoTrace

Quando um objeto ILogger é criado, o objeto ILoggerFactory seleciona uma única regra por provedor para aplicar a esse agente.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Todas as mensagens gravadas pela instância ILogger são filtradas com base nas regras selecionadas.All messages written by an ILogger instance are filtered based on the selected rules. A regra mais específica possível para cada par de categoria e provedor é selecionada dentre as regras disponíveis.The most specific rule possible for each provider and category pair is selected from the available rules.

O algoritmo a seguir é usado para cada provedor quando um ILogger é criado para uma determinada categoria:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Selecione todas as regras que correspondem ao provedor ou seu alias.Select all rules that match the provider or its alias. Se nenhuma correspondência for encontrada, selecione todas as regras com um provedor vazio.If no match is found, select all rules with an empty provider.
  • Do resultado da etapa anterior, selecione as regras com o prefixo de categoria de maior correspondência.From the result of the preceding step, select rules with longest matching category prefix. Se nenhuma correspondência for encontrada, selecione todas as regras que não especificam uma categoria.If no match is found, select all rules that don't specify a category.
  • Se várias regras forem selecionadas, use a última.If multiple rules are selected, take the last one.
  • Se nenhuma regra for selecionada, use MinimumLevel.If no rules are selected, use MinimumLevel.

Com a lista anterior de regras, suponha que você crie um objeto ILogger para a categoria "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Para o provedor Depuração as regras 1, 6 e 8 se aplicam.For the Debug provider, rules 1, 6, and 8 apply. A regra 8 é mais específica, portanto é a que será selecionada.Rule 8 is most specific, so that's the one selected.
  • Para o provedor Console as regras 3, 4, 5 e 6 se aplicam.For the Console provider, rules 3, 4, 5, and 6 apply. A regra 3 é a mais específica.Rule 3 is most specific.

A instância ILogger resultante envia logs de nível Trace e superior para o provedor Depuração.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Logs de nível Debug e superior são enviados para o provedor Console.Logs of Debug level and above are sent to the Console provider.

Aliases de provedorProvider aliases

Cada provedor define um alias que pode ser usado na configuração no lugar do nome de tipo totalmente qualificado.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Para os provedores internos, use os seguintes aliases:For the built-in providers, use the following aliases:

  • Console doConsole
  • DepuraçãoDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Nível mínimo padrãoDefault minimum level

Há uma configuração de nível mínimo que entra em vigor somente se nenhuma regra de código ou de configuração se aplicar a um provedor e uma categoria determinados.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. O exemplo a seguir mostra como definir o nível mínimo:The following example shows how to set the minimum level:

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

Se você não definir explicitamente o nível mínimo, o valor padrão será Information, o que significa que logs Trace e Debug serão ignorados.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

Funções de filtroFilter functions

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.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. O código na função tem acesso ao tipo de provedor, à categoria e ao nível de log.Code in the function has access to the provider type, category, and log level. Por exemplo:For example:

.ConfigureLogging(logBuilder =>
{
    logBuilder.AddFilter((provider, category, logLevel) =>
    {
        if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
            category == "TodoApiSample.Controllers.TodoController")
        {
            return false;
        }
        return true;
    });
})
WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

Categorias e níveis de sistemaSystem categories and levels

Veja algumas categorias usadas pelo ASP.NET Core e Entity Framework Core, com anotações sobre quais logs esperar delas:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

CategoriaCategory {1>Observações<1}Notes
Microsoft.AspNetCoreMicrosoft.AspNetCore Diagnóstico geral de ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Quais chaves foram consideradas, encontradas e usadas.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hosts permitidos.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Quanto tempo levou para que as solicitações de HTTP fossem concluídas e em que horário foram iniciadas.How long HTTP requests took to complete and what time they started. Quais assemblies de inicialização de hospedagem foram carregados.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc Diagnóstico do MVC e Razor.MVC and Razor diagnostics. Model binding, execução de filtro, compilação de exibição, seleção de ação.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Informações de correspondência de rotas.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Respostas de início, parada e atividade da conexão.Connection start, stop, and keep alive responses. Informações sobre o certificado HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Arquivos atendidos.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Diagnóstico geral do Entity Framework Core.General Entity Framework Core diagnostics. Atividade e configuração do banco de dados, detecção de alterações, migrações.Database activity and configuration, change detection, migrations.

Escopos de logLog scopes

Um escopo pode agrupar um conjunto de operações lógicas.A scope can group a set of logical operations. Esse agrupamento pode ser usado para anexar os mesmos dados para cada log criado como parte de um conjunto.This grouping can be used to attach the same data to each log that's created as part of a set. Por exemplo, todo log criado como parte do processamento de uma transação pode incluir a ID da transação.For example, every log created as part of processing a transaction can include the transaction ID.

Um escopo é um tipo IDisposable retornado pelo método BeginScope e que dura até que seja descartado.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Use um escopo por meio do encapsulamento de chamadas de agente em um bloco using:Use a scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

O código a seguir habilita os escopos para o provedor de console:The following code enables scopes for the console provider:

Program.cs:Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.ClearProviders();
            logging.AddConsole(options => options.IncludeScopes = true);
            logging.AddDebug();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });
.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Observação

A configuração da opção de agente de console IncludeScopes é necessária para habilitar o registro em log baseado em escopo.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Saiba mais sobre como configurar na seção Configuração.For information on configuration, see the Configuration section.

Cada mensagem de log inclui as informações com escopo definido:Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

Provedores de log internosBuilt-in logging providers

O ASP.NET Core vem com os seguintes provedores:ASP.NET Core ships the following providers:

Para obter informações sobre StdOut e o log de depuração com o Módulo do ASP.NET Core, consulte Solucionar problemas ASP.NET Core no serviço Azure App e no IIS e Módulo do ASP.NET Core.For information on stdout and debug logging with the ASP.NET Core Module, see Solucionar problemas ASP.NET Core no serviço Azure App e no IIS and Módulo do ASP.NET Core.

Provedor do consoleConsole provider

O pacote de provedor Microsoft.Extensions.Logging.Console envia a saída de log para o console.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

Para ver a saída de registro em log de console, abra um prompt de comando na pasta do projeto e execute o seguinte comando:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Depurar provedorDebug provider

O pacote de provedor Microsoft.Extensions.Logging.Debug grava a saída de log usando a classe System.Diagnostics.Debug (chamadas de método Debug.WriteLine).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

No Linux, esse provedor grava logs em /var/log/message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

Provedor de origem do eventoEvent Source provider

O pacote do provedor Microsoft. Extensions. Logging. EventSource grava em uma origem de evento entre plataformas com o nome Microsoft-Extensions-Logging.The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. No Windows, o provedor usa o ETW.On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

O provedor de origem do evento é adicionado automaticamente quando CreateDefaultBuilder é chamado para compilar o host.The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

ferramentas de rastreamento dotnetdotnet trace tooling

A ferramenta dotnet-Trace é uma ferramenta global da CLI de plataforma cruzada que habilita a coleta de rastreamentos do .NET Core de um processo em execução.The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. A ferramenta coleta dados de provedor de Microsoft.Extensions.Logging.EventSource usando um LoggingEventSource.The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

Instale as ferramentas de rastreamento dotnet com o seguinte comando:Install the dotnet trace tooling with the following command:

dotnet tool install --global dotnet-trace

Use as ferramentas de rastreamento dotnet para coletar um rastreamento de um aplicativo:Use the dotnet trace tooling to collect a trace from an app:

  1. Se o aplicativo não criar o host com CreateDefaultBuilder, adicione o provedor de origem de evento à configuração de log do aplicativo.If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

  2. Execute o aplicativo com o comando dotnet run.Run the app with the dotnet run command.

  3. Determine o identificador do processo (PID) do aplicativo .NET Core:Determine the process identifier (PID) of the .NET Core app:

    Localize o PID do processo que tem o mesmo nome que o assembly do aplicativo.Find the PID for the process that has the same name as the app's assembly.

  4. Execute o comando dotnet trace.Execute the dotnet trace command.

    Sintaxe de comando geral:General command syntax:

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

    Ao usar um shell de comando do PowerShell, coloque o valor --providers entre aspas simples ('):When using a PowerShell command shell, enclose the --providers value in single quotes ('):

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

    Em plataformas não Windows, adicione a opção -f speedscope para alterar o formato do arquivo de rastreamento de saída para speedscope.On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    Palavra-chaveKeyword DescriçãoDescription
    11 Eventos meta de log sobre o LoggingEventSource.Log meta events about the LoggingEventSource. Não registra eventos de ILogger).Doesn't log events from ILogger).
    22 Ativa o evento Message quando ILogger.Log() é chamado.Turns on the Message event when ILogger.Log() is called. Fornece informações em uma maneira programática (não formatada).Provides information in a programmatic (not formatted) way.
    44 Ativa o evento FormatMessage quando ILogger.Log() é chamado.Turns on the FormatMessage event when ILogger.Log() is called. Fornece a versão de cadeia de caracteres formatada das informações.Provides the formatted string version of the information.
    88 Ativa o evento MessageJson quando ILogger.Log() é chamado.Turns on the MessageJson event when ILogger.Log() is called. Fornece uma representação JSON dos argumentos.Provides a JSON representation of the arguments.
    Nível de eventoEvent Level DescriçãoDescription
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    FilterSpecs entradas para {Logger Category} e {Event Level} representam condições de filtragem de log adicionais.FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. Separe FilterSpecs entradas com um ponto e vírgula (;).Separate FilterSpecs entries with a semicolon (;).

    Exemplo usando um shell de comando do Windows (sem aspas simples em relação ao valor --providers):Example using a Windows command shell (no single quotes around the --providers value):

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

    O comando anterior é ativado:The preceding command activates:

    • O agente de log de origem do evento para produzir cadeias de caracteres formatadas (4) para erros (2).The Event Source logger to produce formatted strings (4) for errors (2).
    • Microsoft.AspNetCore.Hosting registro em log no nível de log de Informational (4).Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  5. Pare as ferramentas de rastreamento dotnet pressionando a tecla Enter ou CTRL + C.Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    O rastreamento é salvo com o nome trace. NetTrace na pasta em que o comando dotnet trace é executado.The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  6. Abra o rastreamento com Perfview.Open the trace with Perfview. Abra o arquivo trace. NetTrace e explore os eventos de rastreamento.Open the trace.nettrace file and explore the trace events.

Para obter mais informações, consulte .For more information, see:

PerfviewPerfview

Use o utilitário Perfview para coletar e exibir logs.Use the PerfView utility to collect and view 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.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by 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.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (Não se esqueça do asterisco no início da cadeia de caracteres).(Don't miss the asterisk at the start of the string.)

Outros provedores de Perfview

Provedor EventLog do WindowsWindows EventLog provider

O pacote de provedor Microsoft.Extensions.Logging.EventLog envia a saída de log para o Log de Eventos do Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

As sobrecargas de AddEventLog permitem que você passe EventLogSettings.AddEventLog overloads let you pass in EventLogSettings. Se null ou não for especificado, as seguintes configurações padrão serão usadas:If null or not specified, the following default settings are used:

  • LogName – "aplicativo"LogName – "Application"
  • SourceName – ".NET Runtime"SourceName – ".NET Runtime"
  • MachineName – computador localMachineName – local machine

Os eventos são registrados em log para o nível de aviso e superior.Events are logged for Warning level and higher. Para registrar em log eventos inferiores a Warning, defina explicitamente o nível de log.To log events lower than Warning, explicitly set the log level. Por exemplo, adicione o seguinte ao arquivo appSettings. JSON :For example, add the following to the appsettings.json file:

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

Provedor TraceSourceTraceSource provider

O pacote de provedor Microsoft.Extensions.Logging.TraceSource usa as bibliotecas e provedores de TraceSource.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

As sobrecargas de AddTraceSource permitem que você passe um comutador de fonte e um ouvinte de rastreamento.AddTraceSource overloads let you pass in a source switch and a trace listener.

Para usar esse provedor, o aplicativo deve ser executado no .NET Framework (em vez do .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). O provedor pode rotear mensagens a uma variedade de ouvintes, como o TextWriterTraceListener usado no aplicativo de exemplo.The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Provedor do Serviço de Aplicativo do AzureAzure App Service provider

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.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

logging.AddAzureWebAppDiagnostics();

O pacote do provedor não está incluído na estrutura compartilhada.The provider package isn't included in the shared framework. Para usar o provedor, adicione o pacote do provedor ao projeto.To use the provider, add the provider package to the project.

O pacote de provedor não está incluído no metapacote Microsoft.AspNetCore.App.The provider package isn't included in the Microsoft.AspNetCore.App metapackage. Se você estiver direcionando para o .NET Framework ou referenciando o metapacote Microsoft.AspNetCore.App, adicione o pacote do provedor ao projeto.When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

Para definir as configurações do provedor, use AzureFileLoggerOptions e AzureBlobLoggerOptions, conforme mostrado no exemplo a seguir:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.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>();
        });

Para definir as configurações do provedor, use AzureFileLoggerOptions e AzureBlobLoggerOptions, conforme mostrado no exemplo a seguir:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

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

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.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";
                }))
        .UseStartup<Startup>();

Uma sobrecarga AddAzureWebAppDiagnostics permite passar AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. O objeto settings pode substituir as configurações padrão, como o modelo de saída de registro em log, o nome do blob e o limite do tamanho do arquivo.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (O modelo Output é um modelo de mensagem aplicado a todos os logs, além daquele fornecido com uma chamada ao método ILogger).(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Quando você implanta em um aplicativo do Serviço de Aplicativo, o aplicativo respeita as configurações na seção Logs do Serviço de Aplicativo da página Serviço de Aplicativo do portal do Azure.When you deploy to an App Service app, the application honors the settings in the App Service logs section of the App Service page of the Azure portal. 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.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Log de aplicativo (Sistema de Arquivos)Application Logging (Filesystem)
  • Log de aplicativo (Blob)Application Logging (Blob)

O local padrão para arquivos de log é na pasta D:\home\LogFiles\Application e o nome de arquivo padrão é diagnostics-aaaammdd.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is 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.The default file size limit is 10 MB, and the default maximum number of files retained is 2. O nome de blob padrão é {app-name}{timestamp}/aaaa/mm/dd/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

O provedor funciona somente quando o projeto é executado no ambiente do Azure.The provider only works when the project runs in the Azure environment. Ele não tem nenhum efeito quando o projeto é executado localmente—ele não grava em arquivos locais ou no armazenamento de desenvolvimento local para blobs.It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Fluxo de log do AzureAzure log streaming

O fluxo de log do Azure permite que você exiba a atividade de log em tempo real:Azure log streaming lets you view log activity in real time from:

  • O servidor de aplicativosThe app server
  • Do servidor WebThe web server
  • De uma solicitação de rastreio com falhaFailed request tracing

Para configurar o fluxo de log do Azure:To configure Azure log streaming:

  • Navegue até a página Logs do Serviço de Aplicativo da página do portal do seu aplicativo.Navigate to the App Service logs page from your app's portal page.
  • Defina o Log de aplicativo (Sistema de Arquivos) como Ativado.Set Application Logging (Filesystem) to On.
  • Escolha o Nível de log.Choose the log Level. Essa configuração se aplica somente ao streaming de log do Azure, não a outros provedores de log no aplicativo.This setting only applies to Azure log streaming, not other logging providers in the app.

Navegue até a página Fluxo de Log para exibir as mensagens de aplicativo.Navigate to the Log Stream page to view app messages. Elas são registradas pelo aplicativo por meio da interface ILogger.They're logged by the app through the ILogger interface.

Log de rastreamento do Azure Application InsightsAzure Application Insights trace logging

O pacote de provedor Microsoft.Extensions.Logging.ApplicationInsights grava os logs no Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. O Application Insights é um serviço que monitora um aplicativo web e fornece ferramentas para consultar e analisar os dados de telemetria.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Se você usar esse provedor, poderá consultar e analisar os logs usando as ferramentas do Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

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.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Se você usar esse pacote, não precisará instalar o pacote de provedor.If you use this package, you don't have to install the provider package.

Não use o pacote Microsoft.ApplicationInsights.Web—que é para o ASP.NET 4.x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Para obter mais informações, consulte os seguintes recursos:For more information, see the following resources:

Provedores de log de terceirosThird-party logging providers

Estruturas de log de terceiros que funcionam com o ASP.NET Core:Third-party logging frameworks that work with ASP.NET Core:

Algumas estruturas de terceiros podem fazer o log semântico, também conhecido como registro em log estruturado.Some third-party frameworks can perform semantic logging, also known as structured logging.

Usar uma estrutura de terceiros é semelhante ao uso de um dos provedores internos:Using a third-party framework is similar to using one of the built-in providers:

  1. Adicione um pacote NuGet ao projeto.Add a NuGet package to your project.
  2. Chame um método de extensão de ILoggerFactory fornecido pela estrutura de log.Call an ILoggerFactory extension method provided by the logging framework.

Para saber mais, consulte a documentação de cada provedor.For more information, see each provider's documentation. Não há suporte para provedores de log de terceiros na Microsoft.Third-party logging providers aren't supported by Microsoft.

Recursos adicionaisAdditional resources