Journalisation dans ASP.NET CoreLogging in ASP.NET Core

Article rédigé par Steve Smith et Tom DykstraBy Steve Smith and Tom Dykstra

ASP.NET Core prend en charge une API de journalisation qui fonctionne avec différents fournisseurs de journalisation tiers et intégrés.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Cet article explique comment utiliser cette API de journalisation avec les fournisseurs de journalisation intégrés.This article shows how to use the logging API with built-in providers.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Ajouter des fournisseursAdd providers

Un fournisseur de journalisation affiche ou stocke des journaux.A logging provider displays or stores logs. Par exemple, le fournisseur Console affiche les journaux dans la console, et le fournisseur Azure Application Insights les stocke dans 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. Il est possible d’envoyer les journaux à plusieurs endroits en ajoutant plusieurs fournisseurs.Logs can be sent to multiple destinations by adding multiple providers.

Pour ajouter un fournisseur, appelez la méthode d’extension Add{provider name} du fournisseur dans 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();
}

Le code précédent nécessite des références à Microsoft.Extensions.Logging et Microsoft.Extensions.Configuration.The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

Le modèle de projet par défaut appelle CreateDefaultBuilder, qui ajoute les fournisseurs de journalisation suivants :The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • ConsoleConsole
  • DébogageDebug
  • EventSource (à partir d’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>();

Si vous utilisez CreateDefaultBuilder, vous pouvez remplacer les fournisseurs par défaut par ceux de votre choix.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Appelez ClearProviders et ajoutez les fournisseurs que vous souhaitez.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();
        });

Pour utiliser un fournisseur, installez son package NuGet et appelez sa méthode d’extension sur une instance de ILoggerFactory :To use a provider, install its NuGet package and call the provider's extension method on an instance of ILoggerFactory:

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole()
        .AddDebug();

L’injection de dépendances ASP.NET Core fournit l’instance ILoggerFactory.ASP.NET Core dependency injection (DI) provides the ILoggerFactory instance. Les méthodes d’extension AddConsole et AddDebug sont définies dans les packages Microsoft.Extensions.Logging.Console et Microsoft.Extensions.Logging.Debug.The AddConsole and AddDebug extension methods are defined in the Microsoft.Extensions.Logging.Console and Microsoft.Extensions.Logging.Debug packages. Chaque méthode d’extension appelle la méthode ILoggerFactory.AddProvider, en passant une instance du fournisseur.Each extension method calls the ILoggerFactory.AddProvider method, passing in an instance of the provider.

Notes

L’exemple d’application ajoute des fournisseurs de journalisation dans la méthode Startup.Configure.The sample app adds logging providers in the Startup.Configure method. Pour obtenir la sortie de journal du code exécuté plus haut, ajoutez les fournisseurs de journalisation au constructeur de classe Startup.To obtain log output from code that executes earlier, add logging providers in the Startup class constructor.

Vous trouverez des informations sur les fournisseurs de journalisation intégrés et les fournisseurs de journalisation tiers plus loin dans cet article.Learn more about built-in logging providers and third-party logging providers later in the article.

Créer des journauxCreate logs

Récupérez un objet ILogger<TCategoryName> auprès de l’injection de dépendances.Get an ILogger<TCategoryName> object from DI.

L’exemple de contrôleur suivant crée des journaux Information et Warning.The following controller example creates Information and Warning logs. La catégorie est TodoApiSample.Controllers.TodoController (le nom de classe complet de TodoController dans l’exemple d’application) :The category is TodoApiSample.Controllers.TodoController (the fully qualified class name of TodoController in the sample app):

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

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
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);
}

L’exemple Razor Pages suivant crée des journaux de niveau Information et de catégorie TodoApiSample.Pages.AboutModel :The following Razor Pages example creates logs with Information as the level and TodoApiSample.Pages.AboutModel as the category:

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
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);
}

L’exemple précédent crée des journaux de niveau Information et Warning et de catégorie classe TodoController.The preceding example creates logs with Information and Warning as the level and TodoController class as the category.

Le niveau du journal indique la gravité de l’événement consigné.The Log level indicates the severity of the logged event. La catégorie du journal est une chaîne associée à chaque journal.The log category is a string that is associated with each log. L’instance ILogger<T> crée des journaux ayant comme catégorie un nom complet de type T.The ILogger<T> instance creates logs that have the fully qualified name of type T as the category. Les niveaux et les catégories sont expliqués plus en détail plus loin dans cet article.Levels and categories are explained in more detail later in this article.

Créer des journaux au démarrageCreate logs in Startup

Pour écrire des journaux dans la classe Startup, ajoutez un paramètre ILogger dans la signature de constructeur :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();
    }
}

Créer des journaux dans le programmeCreate logs in Program

Pour écrire des journaux dans la classe Program, récupérez une instance ILogger auprès de l’injection de dépendances :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();
        });

Aucune méthode d’enregistreur d’événements asynchroneNo asynchronous logger methods

La journalisation doit être suffisamment rapide par rapport au coût du code asynchrone en matière de performances.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Si votre magasin de données de journalisation est lent, n’écrivez pas directement dedans.If your logging data store is slow, don't write to it directly. Écrivez au départ les messages de journal dans un magasin rapide, puis déplacez-les dans le magasin lent.Consider writing the log messages to a fast store initially, then move them to the slow store later. Par exemple, si vous vous connectez à SQL Server, évitez de le faire directement dans une méthode Log, car les méthodes Log sont synchrones.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. Ajoutez plutôt de façon synchronisée des messages de journal à une file d’attente en mémoire, puis configurez un traitement en arrière-plan afin d’extraire les messages de la file d’attente et d’effectuer le travail asynchrone d’envoi des données vers 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.

ConfigurationConfiguration

La configuration de fournisseur de journalisation est fournie par un ou plusieurs fournisseurs de configuration :Logging provider configuration is provided by one or more configuration providers:

  • Formats de fichiers (INI, JSON et XML).File formats (INI, JSON, and XML).
  • Arguments de ligne de commandeCommand-line arguments.
  • Variables d'environnement.Environment variables.
  • Objets .NET en mémoire.In-memory .NET objects.
  • Stockage Secret Manager non chiffré.The unencrypted Secret Manager storage.
  • Magasin utilisateur chiffré comme Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Fournisseurs personnalisés (installés ou créés).Custom providers (installed or created).

Par exemple, la configuration de journalisation est généralement fournie par la section Logging des fichiers de paramètres d’application.For example, logging configuration is commonly provided by the Logging section of app settings files. L’exemple suivant montre le contenu d’un fichier appsettings.Development.json standard :The following example shows the contents of a typical appsettings.Development.json file:

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

La propriété Logging peut avoir un niveau LogLevel et des propriétés de module fournisseur d'informations (Console ici).The Logging property can have LogLevel and log provider properties (Console is shown).

La propriété LogLevel sous Logging spécifie le niveau de journalisation minimal pour les catégories sélectionnées.The LogLevel property under Logging specifies the minimum level to log for selected categories. Dans l’exemple, les catégories System et Microsoft sont consignées au niveau Information, et toutes les autres au niveau Debug.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Les autres propriétés sous Logging spécifient les fournisseurs de journalisation.Other properties under Logging specify logging providers. Cet exemple concerne le fournisseur Console.The example is for the Console provider. Lorsqu’un fournisseur prend en charge les étendues de journal, IncludeScopes indique si elles sont activées.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Une propriété de fournisseur (comme Console dans l’exemple) peut également spécifier une propriété LogLevel.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel sous un fournisseur spécifie les niveaux à consigner pour ce fournisseur.LogLevel under a provider specifies levels to log for that provider.

Si les niveaux sont spécifiés dans Logging.{providername}.LogLevel, ils remplacent ce qui est défini dans Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel.

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

Les clés LogLevel représentent des noms de journal.LogLevel keys represent log names. La clé Default s’applique aux journaux qui ne sont pas explicitement répertoriés.The Default key applies to logs not explicitly listed. La valeur représente le niveau de journal appliqué au journal donné.The value represents the log level applied to the given log.

Pour plus d’informations sur l’implémentation des fournisseurs de configuration, consultez Configuration dans ASP.NET Core.For information on implementing configuration providers, see Configuration dans ASP.NET Core.

Exemple de sortie de la journalisationSample logging output

Avec l’exemple de code présenté dans la section précédente, les journaux s’affichent dans la console lorsque l’application est exécutée en ligne de commande.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Voici un exemple de sortie de la console :Here's an example of console output:

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

Les journaux précédents ont été générés par une requête HTTP Get à l’exemple d’application à l’adresse 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.

Voici un exemple des mêmes journaux tels qu’ils s’affichent dans la fenêtre Débogage quand vous exécutez l’exemple d’application dans 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.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

Les journaux créés par les appels de ILogger illustrés dans la section précédente commencent par « TodoApi.Controllers.TodoController ».The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi.Controllers.TodoController". Ceux qui commencent par les catégories « Microsoft » proviennent du code du framework ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core et le code d’application utilisent la même API de journalisation et les mêmes fournisseurs.ASP.NET Core and application code are using the same logging API and providers.

Les autres sections de cet article détaillent certains points et présentent les options de journalisation.The remainder of this article explains some details and options for logging.

Packages NuGetNuGet packages

Les interfaces ILogger et ILoggerFactory se trouvent dans Microsoft.Extensions.Logging.Abstractions, et leurs implémentations par défaut se trouvent dans Microsoft.Extensions.Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

Catégorie de logLog category

Quand un objet ILogger est créé, une catégorie lui est spécifiée.When an ILogger object is created, a category is specified for it. Cette catégorie est incluse dans tous les messages de journal créés par cette instance de ILogger.That category is included with each log message created by that instance of ILogger. Si la catégorie peut être n’importe quelle chaîne, la convention est d’utiliser le nom de la classe, par exemple « TodoApi.Controllers.TodoController ».The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Utilisez ILogger<T> pour obtenir une instance de ILogger qui utilise le nom de type complet T comme catégorie :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;
    }

Pour spécifier explicitement la catégorie, appelez 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> équivaut à appeler CreateLogger avec le nom de type complet T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Niveau du logLog level

Chaque journal spécifie une valeur LogLevel.Every log specifies a LogLevel value. Le niveau de journalisation indique la gravité ou l’importance.The log level indicates the severity or importance. Vous pourriez par exemple écrire un journal Information lorsqu’une méthode se termine normalement et un journal Warning lorsqu’une méthode retourne un code de statut 404 Not Found.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.

Le code suivant crée des journaux Information et 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);
}

Dans le code précédent, le premier paramètre est l’ID de l’événement de journal.In the preceding code, the first parameter is the Log event ID. Le deuxième paramètre est un modèle de message contenant des espaces réservés pour les valeurs d’argument fournies par les autres paramètres de méthode.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Les paramètres de méthode sont expliqués dans la section Modèle de message plus loin dans cet article.The method parameters are explained in the message template section later in this article.

Les méthodes de journal qui comportent le niveau dans leur nom (par exemple, LogInformation et LogWarning) sont des méthodes d’extension pour ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Elles appellent une méthode Log qui prend un paramètre LogLevel.These methods call a Log method that takes a LogLevel parameter. Vous pouvez appeler la méthode Log directement au lieu d’appeler ces méthodes d’extension, mais la syntaxe est relativement complexe.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Pour plus d’informations, voir ILogger et le code source des extensions d’enregistreur d'événements.For more information, see ILogger and the logger extensions source code.

ASP.NET Core définit les niveaux de journalisation suivants, classés selon leur degré de gravité (du plus faible au plus élevé).ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Trace = 0Trace = 0

    Informations en général exclusivement utiles à des fins de débogage.For information that's typically valuable only for debugging. Ces messages peuvent contenir des données d’application sensibles. Ils ne doivent donc pas être activés dans un environnement de production.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Niveau désactivé par défaut.Disabled by default.

  • Debug = 1Debug = 1

    Informations qui peuvent être utiles dans le développement et le débogage.For information that may be useful in development and debugging. Exemple : Entering method Configure with flag set to true. En raison de leur volume élevé, activez les journaux de niveau Debug en production seulement pour résoudre des problèmes.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

    Informations de suivi du flux général de l’application.For tracking the general flow of the app. Ces journaux ont généralement une utilité à long terme.These logs typically have some long-term value. Exemple : Request received for path /api/todoExample: Request received for path /api/todo

  • Warning = 3Warning = 3

    Informations sur les événements anormaux ou inattendus dans le flux de l’application.For abnormal or unexpected events in the app flow. Il peut s’agir d’erreurs ou d’autres situations qui ne provoquent pas l’arrêt de l’application, mais qu’il peut être intéressant d’examiner.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Le niveau de journalisation Warning est généralement utilisé pour les exceptions gérées.Handled exceptions are a common place to use the Warning log level. Exemple : FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Error = 4Error = 4

    Fournit des informations sur des erreurs et des exceptions qui ne peuvent pas être gérées.For errors and exceptions that cannot be handled. Ces messages indiquent un échec de l’activité ou de l’opération en cours (par exemple, la requête HTTP actuellement exécutée), pas un échec au niveau de l’application.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Exemple de message de log : Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Critical = 5Critical = 5

    Fournit des informations sur des échecs qui nécessitent un examen immédiat.For failures that require immediate attention. Exemples : perte de données, espace disque insuffisant.Examples: data loss scenarios, out of disk space.

Le niveau de journalisation permet de contrôler le volume de la sortie de journal écrite sur un support de stockage ou dans une fenêtre d’affichage.Use the log level to control how much log output is written to a particular storage medium or display window. Par exemple :For example:

  • En production, envoyez Trace au niveau Information dans un magasin de données de volume.In production, send Trace through Information level to a volume data store. Envoyez Warning au niveau Critical à un magasin de données de valeurs.Send Warning through Critical to a value data store.
  • Pendant le développement, envoyez Warning au niveau Critical à la console et ajoutez Trace au niveau Information lors de la résolution des problèmes.During development, send Warning through Critical to the console, and add Trace through Information when troubleshooting.

La section Filtrage de log plus loin dans cet article explique comment déterminer les niveaux de journalisation gérés par un fournisseur.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core écrit des journaux pour les événements de framework.ASP.NET Core writes logs for framework events. Aucun journal du niveau Debug ou Trace n’était créé dans les exemples de journaux présentés plus haut dans cet article, puisque les journaux au-dessous du niveau Information étaient exclus.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Voici un exemple de journaux Console produits par l’exemple d’application configurée pour afficher les journaux Debug :Here's an example of console logs produced by running the sample app configured to show Debug logs:

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 d’événement de logLog event ID

Chaque journal peut spécifier un ID d’événement.Each log can specify an event ID. Pour cela, l’exemple d’application utilise une classe LoggingEvents définie localement :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;
}

Un ID d’événement associe un jeu d’événements.An event ID associates a set of events. Par exemple, tous les journaux liés à l’affichage d’une liste d’éléments sur une page peuvent être 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Le fournisseur de journalisation peut stocker l’ID d’événement dans un champ ID, dans le message de journalisation, ou pas du tout.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Le fournisseur Debug n’affiche pas les ID d’événements.The Debug provider doesn't show event IDs. Le fournisseur Console affiche les ID d’événements entre crochets après la catégorie :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

Modèle de message de logLog message template

Chaque journal spécifie un modèle de message.Each log specifies a message template. Ce dernier peut contenir des espaces réservés pour lesquels les arguments sont fournis.The message template can contain placeholders for which arguments are provided. Utilisez des noms et non des nombres pour les espaces réservés.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);
}

L’ordre des espaces réservés, pas leurs noms, détermine quels paramètres sont utilisés pour fournir leurs valeurs.The order of placeholders, not their names, determines which parameters are used to provide their values. Dans le code suivant, on voit que les noms de paramètres sont hors séquence dans le modèle de message :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);

Ce code crée un message de journal avec les valeurs des paramètres dans la séquence :This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

Le framework de journalisation fonctionne ainsi pour permettre aux fournisseurs de journalisation d’implémenter la journalisation sémantique, également appelée journalisation structurée.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Les arguments proprement dits, et pas seulement le modèle de message mis en forme, sont transmis au système de journalisation.The arguments themselves are passed to the logging system, not just the formatted message template. C’est grâce à ces informations que les fournisseurs de journalisation peuvent stocker les valeurs des paramètres sous forme de champs.This information enables logging providers to store the parameter values as fields. Supposons par exemple que les appels de méthodes d’enregistreur d’événements se présentent ainsi :For example, suppose logger method calls look like this:

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

Si vous envoyez les journaux au Stockage Table Azure, chaque entité Table Azure peut avoir les propriétés ID et RequestTime, ce qui simplifie les requêtes sur les données de journaux.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. Une requête peut rechercher tous les journaux compris dans une plage RequestTime spécifique sans analyser le délai d’expiration du message texte.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Journalisation des exceptionsLogging exceptions

Les méthodes logger ont des surcharges qui vous permettent de passer une exception, comme dans l’exemple suivant :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);

Tous les fournisseurs ne gèrent pas les informations sur les exceptions de la même façon.Different providers handle the exception information in different ways. Voici un exemple de sortie du fournisseur Debug extrait du code montré plus haut.Here's an example of Debug provider output from the code shown above.

TodoApi.Controllers.TodoController:Warning: GetById(036dd898-fb01-47e8-9a65-f92eb73cf924) NOT FOUND

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

Filtrage de journalLog filtering

Vous pouvez spécifier un niveau de journalisation minimum pour une catégorie ou un fournisseur spécifique, ou pour l’ensemble des fournisseurs ou des catégories.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Les enregistrements de log en dessous du niveau minimum ne sont pas passés à ce fournisseur, et ne sont donc pas affichés ou stockés.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Pour supprimer tous les journaux, choisissez LogLevel.None comme niveau de journalisation minimal.To suppress all logs, specify LogLevel.None as the minimum log level. La valeur entière de LogLevel.None est 6, soit un niveau supérieur à LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Créer des règles de filtre dans la configurationCreate filter rules in configuration

Le code du modèle de projet appelle CreateDefaultBuilder afin de configurer la journalisation pour les fournisseurs Console et Debug.The project template code calls CreateDefaultBuilder to set up logging for the Console and Debug providers. La méthode CreateDefaultBuilder définit également la journalisation pour rechercher la configuration dans une section Logging, à l’aide de code similaire à celui-ci :The CreateDefaultBuilder method also sets up logging to look for configuration in a Logging section, using code like the following:

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

Les données de configuration spécifient des niveaux de journalisation minimum par fournisseur et par catégorie, comme dans l’exemple suivant :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"
    }
  }
}

Ce code JSON crée six règles de filtre : une pour le fournisseur Debug, quatre pour le fournisseur Console et une pour tous les fournisseurs.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Une seule règle est choisie pour chaque fournisseur à la création d’un objet ILogger.A single rule is chosen for each provider when an ILogger object is created.

Règles de filtre dans le codeFilter rules in code

L'exemple suivant montre comment enregistrer des règles de filtre dans le code :The following example shows how to register filter rules in code:

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

Le second AddFilter spécifie le fournisseur Debug par son nom de type.The second AddFilter specifies the Debug provider by using its type name. Le premier AddFilter s’applique à tous les fournisseurs, car il ne spécifie aucun type de fournisseur.The first AddFilter applies to all providers because it doesn't specify a provider type.

Mode d’application des règles de filtreHow filtering rules are applied

Les données de configuration et le code AddFilter contenus dans les exemples précédents créent les règles présentées dans le tableau suivant.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Les six premières proviennent de l’exemple de configuration et les deux dernières, de l’exemple de code.The first six come from the configuration example and the last two come from the code example.

nombreNumber FournisseurProvider Catégories commençant par...Categories that begin with ... Niveau de journalisation minimumMinimum log level
11 DébogageDebug Toutes les catégoriesAll categories InformationInformation
22 ConsoleConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal WarningWarning
33 ConsoleConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor DébogageDebug
44 ConsoleConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor ErrorError
55 ConsoleConsole Toutes les catégoriesAll categories InformationInformation
66 Tous les fournisseursAll providers Toutes les catégoriesAll categories DébogageDebug
77 Tous les fournisseursAll providers SystèmeSystem DébogageDebug
88 DébogageDebug MicrosoftMicrosoft SuiviTrace

À la création d’un objet ILogger, l’objet ILoggerFactory sélectionne une seule règle à appliquer à cet enregistrement d’événements par fournisseur.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Tous les messages écrits par une instance ILogger sont filtrés selon les règles sélectionnées.All messages written by an ILogger instance are filtered based on the selected rules. La règle la plus spécifique pouvant être appliquée à chaque paire catégorie/fournisseur est sélectionnée parmi les règles disponibles.The most specific rule possible for each provider and category pair is selected from the available rules.

L’algorithme suivant est utilisé pour chaque fournisseur quand un objet ILogger est créé pour une catégorie donnée :The following algorithm is used for each provider when an ILogger is created for a given category:

  • Sélectionnez toutes les règles qui correspondent au fournisseur ou à son alias.Select all rules that match the provider or its alias. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles avec un fournisseur vide.If no match is found, select all rules with an empty provider.
  • À partir du résultat de l’étape précédente, sélectionnez les règles ayant le plus long préfixe de catégorie correspondant.From the result of the preceding step, select rules with longest matching category prefix. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.If no match is found, select all rules that don't specify a category.
  • Si plusieurs règles sont sélectionnées, prenez la dernière.If multiple rules are selected, take the last one.
  • Si aucune règle n’est sélectionnée, utilisez MinimumLevel.If no rules are selected, use MinimumLevel.

Avec la liste de règles précédente, supposons que vous créez un objet ILogger pour la catégorie « Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine » :With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Les règles 1, 6 et 8 s’appliquent au fournisseur Debug.For the Debug provider, rules 1, 6, and 8 apply. La règle 8 est sélectionnée, car c’est la plus spécifique.Rule 8 is most specific, so that's the one selected.
  • Les règles 3, 4, 5 et 6 s’appliquent au fournisseur Console.For the Console provider, rules 3, 4, 5, and 6 apply. La règle 3 est la plus spécifique.Rule 3 is most specific.

L’instance ILogger ainsi produite envoie des journaux de niveau Trace ou supérieur au fournisseur Debug.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Les journaux de niveau Debug et supérieurs sont envoyés au fournisseur Console.Logs of Debug level and above are sent to the Console provider.

Alias de fournisseurProvider aliases

Chaque fournisseur définit un alias qui peut être utilisé dans la configuration à la place du nom de type complet.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Pour les fournisseurs intégrés, utilisez les alias suivants :For the built-in providers, use the following aliases:

  • ConsoleConsole
  • DébogageDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Niveau minimum par défautDefault minimum level

Un paramètre de niveau minimum est utilisé uniquement si aucune règle de la configuration ou du code ne s’applique à une catégorie ou un fournisseur spécifique.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. L’exemple suivant montre comment définir le niveau minimum :The following example shows how to set the minimum level:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

Si vous ne définissez pas explicitement le niveau minimum, la valeur par défaut est Information, ce qui signifie que les niveaux Trace et Debug sont ignorés.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

Fonctions de filtreFilter functions

Une fonction de filtre est appelée pour tous les fournisseurs et toutes les catégories pour lesquels la configuration ou le code n’applique aucune règle.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. Le code de la fonction a accès au type de fournisseur, à la catégorie et au niveau de journalisation.Code in the function has access to the provider type, category, and log level. Par exemple :For example:

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

Certains fournisseurs de journalisation vous permettent de spécifier quand des enregistrements de log doivent être écrits sur un média de stockage, ou au contraire ignorés, en fonction de la catégorie et du niveau de journalisation.Some logging providers let you specify when logs should be written to a storage medium or ignored based on log level and category.

Les méthodes d’extension AddConsole et AddDebug offrent des surcharges qui acceptent des critères de filtrage.The AddConsole and AddDebug extension methods provide overloads that accept filtering criteria. Dans l’exemple de code suivant, le fournisseur Console ignore les enregistrements en dessous du niveau Warning, et le fournisseur Debug ignore les enregistrements créés par le framework.The following sample code causes the console provider to ignore logs below Warning level, while the Debug provider ignores logs that the framework creates.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole(LogLevel.Warning)
        .AddDebug((category, logLevel) => (category.Contains("TodoApi") && logLevel >= LogLevel.Trace));

La méthode AddEventLog a une surcharge qui accepte une instance EventLogSettings, dont la propriété Filter peut contenir une fonction de filtre.The AddEventLog method has an overload that takes an EventLogSettings instance, which may contain a filtering function in its Filter property. Le fournisseur TraceSource ne fournit aucune de ces surcharges, étant donné que son niveau de journalisation et d’autres paramètres dépendent des SourceSwitch et TraceListener qu’il utilise.The TraceSource provider doesn't provide any of those overloads, since its logging level and other parameters are based on the SourceSwitch and TraceListener it uses.

Pour définir des règles de filtrage sur tous les fournisseurs inscrits auprès d’une instance ILoggerFactory, utilisez la méthode d’extension WithFilter.To set filtering rules for all providers that are registered with an ILoggerFactory instance, use the WithFilter extension method. L’exemple suivant limite les journaux du framework (dont la catégorie commence par « Microsoft » ou « System ») aux avertissements, tout en effectuant une journalisation au niveau Debug pour les journaux créés par le code de l’application.The example below limits framework logs (category begins with "Microsoft" or "System") to warnings while logging at debug level for logs created by application code.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .WithFilter(new FilterLoggerSettings
        {
            { "Microsoft", LogLevel.Warning },
            { "System", LogLevel.Warning },
            { "ToDoApi", LogLevel.Debug }
        })
        .AddConsole()
        .AddDebug();

Pour empêcher l’écriture de journaux, choisissez LogLevel.None comme niveau de journalisation minimal.To prevent any logs from being written, specify LogLevel.None as the minimum log level. La valeur entière de LogLevel.None est 6, soit un niveau supérieur à LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

La méthode d’extension WithFilter est fournie par le package NuGet Microsoft.Extensions.Logging.Filter.The WithFilter extension method is provided by the Microsoft.Extensions.Logging.Filter NuGet package. La méthode retourne une nouvelle instance ILoggerFactory qui filtre les messages de log passés à tous les fournisseurs de journalisation inscrits dans cette méthode.The method returns a new ILoggerFactory instance that will filter the log messages passed to all logger providers registered with it. Cela n’affecte pas les autres instances ILoggerFactory, y compris l’instance ILoggerFactory initiale.It doesn't affect any other ILoggerFactory instances, including the original ILoggerFactory instance.

Niveaux et les catégories de systèmeSystem categories and levels

Voici quelques catégories utilisées par ASP.NET Core et Entity Framework Core, avec des notes sur les journaux associés :Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

CategoryCategory NotesNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Diagnostics ASP.NET Core généraux.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Liste des clés considérées, trouvées et utilisées.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hôtes autorisés.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Temps de traitement des requêtes HTTP et heure de démarrage.How long HTTP requests took to complete and what time they started. Liste des assemblys de démarrage d’hébergement chargés.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc Diagnostics MVC et Razor.MVC and Razor diagnostics. Liaison de données, exécution de filtres, compilation de vues, sélection d’actions.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Informations de correspondance des itinéraires.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Démarrage et arrêt de la connexion, et réponses persistantes.Connection start, stop, and keep alive responses. Informations du certificat HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Fichiers pris en charge.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Diagnostics Entity Framework Core généraux.General Entity Framework Core diagnostics. Activité et configuration de la base de données, détection des modifications, migrations.Database activity and configuration, change detection, migrations.

Étendues de logLog scopes

Une étendue peut regrouper un ensemble d’opérations logiques.A scope can group a set of logical operations. Ce regroupement permet de joindre les mêmes données à tous les journaux créés au sein d’un ensemble.This grouping can be used to attach the same data to each log that's created as part of a set. Par exemple, chaque journal créé dans le cadre du traitement d’une transaction peut contenir l’ID de la transaction.For example, every log created as part of processing a transaction can include the transaction ID.

Une étendue est un type IDisposable qui est retourné par la méthode BeginScope. Elle s’applique tant qu’elle n’est pas supprimée.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Utilisez une étendue en incluant les appels de l’enregistrement d’événements dans un bloc 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);
}

Le code suivant active les étendues pour le fournisseur Console :The following code enables scopes for the console provider:

Program.cs :Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Notes

La configuration de l’option logger IncludeScopes pour la console est nécessaire pour activer la journalisation basée sur des étendues.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Pour plus d'informations sur la configuration, reportez-vous à la section Configuration.For information on configuration, see the Configuration section.

Program.cs :Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Notes

La configuration de l’option logger IncludeScopes pour la console est nécessaire pour activer la journalisation basée sur des étendues.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Startup.cs :Startup.cs:

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole(includeScopes: true)
        .AddDebug();

Chaque message de log fournit les informations incluses dans l’étendue :Each log message includes the scoped information:

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

Fournisseurs de journalisation intégrésBuilt-in logging providers

ASP.NET Core contient les fournisseurs suivants :ASP.NET Core ships the following providers:

Pour plus d'informations sur la journalisation stdout, voir Résoudre les problèmes liés à ASP.NET Core sur IIS et Résoudre les problèmes liés à ASP.NET Core sur Azure App Service.For information about stdout logging, see Résoudre les problèmes liés à ASP.NET Core sur IIS and Résoudre les problèmes liés à ASP.NET Core sur Azure App Service.

Fournisseur ConsoleConsole provider

Le package de fournisseur Microsoft.Extensions.Logging.Console envoie la sortie de log dans la console.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();
loggerFactory.AddConsole();

Les surcharges AddConsole permettent de transmettre un niveau de journalisation minimal, une fonction de filtre et une valeur booléenne qui indique si les étendues sont prises en charge.AddConsole overloads let you pass in a minimum log level, a filter function, and a boolean that indicates whether scopes are supported. Une autre option consiste à passer un objet IConfiguration, qui permet de spécifier la prise en charge des étendues et les niveaux de journalisation.Another option is to pass in an IConfiguration object, which can specify scopes support and logging levels.

Pour les options de fournisseur Console, consultez ConsoleLoggerOptions.For Console provider options, see ConsoleLoggerOptions.

Le fournisseur Console a un impact significatif sur les performances et n’est généralement pas adapté à une utilisation en production.The console provider has a significant impact on performance and is generally not appropriate for use in production.

Quand vous créez un projet dans Visual Studio, la méthode AddConsole ressemble à ceci :When you create a new project in Visual Studio, the AddConsole method looks like this:

loggerFactory.AddConsole(Configuration.GetSection("Logging"));

Ce code fait référence à la section Logging du fichier appSettings.json :This code refers to the Logging section of the appSettings.json file:

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

Les paramètres définis limitent les enregistrements du framework aux avertissements, mais active ceux de l’application au niveau Debug, comme cela est expliqué dans la section Filtrage de log.The settings shown limit framework logs to warnings while allowing the app to log at debug level, as explained in the Log filtering section. Pour plus d’informations, consultez Configuration.For more information, see Configuration.

Pour voir la sortie de la journalisation Console, ouvrez une invite de commandes dans le dossier du projet et exécutez la commande suivante :To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Fournisseur DebugDebug provider

Le package de fournisseur Microsoft.Extensions.Logging.Debug écrit la sortie de log à l’aide de la classe System.Diagnostics.Debug (appels de la méthode Debug.WriteLine).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

Sur Linux, ce fournisseur écrit la sortie de log dans /var/log/message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();
loggerFactory.AddDebug();

Les surcharges AddDebug vous permettent de passer un niveau de log minimum ou une fonction de filtre.AddDebug overloads let you pass in a minimum log level or a filter function.

Fournisseur EventSourceEventSource provider

Pour les applications qui ciblent ASP.NET Core 1.1.0 ou ultérieur, le package de fournisseur Microsoft.Extensions.Logging.EventSource peut implémenter le suivi des événements.For apps that target ASP.NET Core 1.1.0 or later, the Microsoft.Extensions.Logging.EventSource provider package can implement event tracing. Sur Windows, il utilise ETW.On Windows, it uses ETW. Le fournisseur est multiplateforme, mais il ne prend pas en charge la collection d’événements ni les outils d’affichage pour Linux ou macOS.The provider is cross-platform, but there are no event collection and display tools yet for Linux or macOS.

logging.AddEventSourceLogger();
loggerFactory.AddEventSourceLogger();

L’utilitaire PerfView est très utile pour collecter et afficher les journaux.A good way to collect and view logs is to use the PerfView utility. Il existe d’autres outils d’affichage des journaux ETW, mais PerfView est l’outil recommandé pour gérer les événements ETW générés par ASP.NET.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET.

Pour configurer PerfView afin qu’il collecte les événements enregistrés par ce fournisseur, ajoutez la chaîne *Microsoft-Extensions-Logging à la liste des fournisseurs supplémentaires.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (N’oubliez pas d’inclure l’astérisque au début de la chaîne.)(Don't miss the asterisk at the start of the string.)

Fournisseurs supplémentaires dans PerfView

Fournisseur EventLog WindowsWindows EventLog provider

Le package de fournisseur Microsoft.Extensions.Logging.EventLog envoie la sortie de log dans le journal des événements Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();
loggerFactory.AddEventLog();

Les surcharges AddEventLog vous permettent de passer EventLogSettings ou un niveau de journalisation minimum.AddEventLog overloads let you pass in EventLogSettings or a minimum log level.

Fournisseur TraceSourceTraceSource provider

Le package de fournisseur Microsoft.Extensions.Logging.TraceSource utilise les bibliothèques et fournisseurs TraceSource.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);
loggerFactory.AddTraceSource(sourceSwitchName);

Les surcharges AddTraceSource vous permettent de passer un commutateur de source et un écouteur de suivi.AddTraceSource overloads let you pass in a source switch and a trace listener.

Pour pouvoir utiliser ce fournisseur, il faut que l’application s’exécute sur .NET Framework (au lieu de .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Le fournisseur peut acheminer les messages vers différents détecteurs d’événements, comme TextWriterTraceListener (utilisé dans l’exemple d’application).The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

L’exemple suivant configure un fournisseur TraceSource qui enregistre les messages Warning et de niveau supérieur dans la fenêtre de la console.The following example configures a TraceSource provider that logs Warning and higher messages to the console window.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddDebug();

    // add Trace Source logging
    var testSwitch = new SourceSwitch("sourceSwitch", "Logging Sample");
    testSwitch.Level = SourceLevels.Warning;
    loggerFactory.AddTraceSource(testSwitch,
        new TextWriterTraceListener(writer: Console.Out));

Fournisseur Azure App ServiceAzure App Service provider

Le package de fournisseur Microsoft.Extensions.Logging.AzureAppServices écrit les enregistrements de log dans des fichiers texte dans le système de fichiers d’une application Azure App Service, et dans un stockage Blob dans un compte de stockage 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. Le package de fournisseur est disponible pour les applications ciblant .NET Core 1.1 ou ultérieur.The provider package is available for apps targeting .NET Core 1.1 or later.

Si vous ciblez .NET Core, notez les points suivants :If targeting .NET Core, note the following points:

Si vous ciblez le .NET Framework ou référencez le métapackage Microsoft.AspNetCore.App, ajoutez le package de fournisseur dans le projet.If targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project. Appelez AddAzureWebAppDiagnostics :Invoke AddAzureWebAppDiagnostics:

logging.AddAzureWebAppDiagnostics();
loggerFactory.AddAzureWebAppDiagnostics();

Une surcharge AddAzureWebAppDiagnostics permet de transmettre AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. L’objet de paramètres peut remplacer les paramètres par défaut, comme le modèle de sortie de journalisation, le nom d’objet blob et la limite de taille de fichier.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (Modèle de sortie est un modèle de message qui s’applique à tous les journaux en plus de ce qui est fourni avec un appel de méthode ILogger.)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Pour configurer les paramètres du fournisseur, utilisez AzureFileLoggerOptions et AzureBlobLoggerOptions, comme illustré dans l’exemple suivant :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>();

En cas de déploiement sur une application App Service, celle-ci applique les paramètres définis dans la section Journaux App Service de la page App Service du portail 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. Quand les paramètres suivants sont mis à jour, les changements prennent effet immédiatement sans avoir besoin de redémarrer ou redéployer l’application.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Journalisation des applications (système de fichiers)Application Logging (Filesystem)
  • Journalisation des applications (objet blob)Application Logging (Blob)

L’emplacement par défaut des fichiers journaux est le dossier D:\racine\LogFiles\Application, et le nom de fichier par défaut est diagnostics-aaaammjj.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. La limite de taille de fichier par défaut est de 10 Mo, et le nombre maximal de fichiers conservés par défaut est de 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Le nom par défaut du blob est {app-name}{timestamp}/aaaa/mm/jj/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Le fournisseur fonctionne uniquement quand le projet s’exécute dans l’environnement Azure.The provider only works when the project runs in the Azure environment. Il n’a aucun effet si le projet s’exécute localement — il n’écrit pas d’enregistrements dans les fichiers locaux ou dans le stockage de développement local pour les objets blob.It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Streaming des journaux AzureAzure log streaming

La diffusion en continu des journaux Azure permet d’afficher l’activité de journalisation en temps réel aux emplacements suivants :Azure log streaming lets you view log activity in real time from:

  • Serveur d'applicationsThe app server
  • Serveur webThe web server
  • Suivi des demandes ayant échouéFailed request tracing

Pour configurer le streaming des journaux Azure :To configure Azure log streaming:

  • Accédez à la page Journaux App Service dans le portail de votre application.Navigate to the App Service logs page from your app's portal page.
  • Définissez Journalisation des applications (Système de fichiers) sur Activé.Set Application Logging (Filesystem) to On.
  • Choisissez le niveau du journal.Choose the log Level.

Accédez à la page Streaming des journaux pour voir les messages d’application.Navigate to the Log Stream page to view app messages. Ils sont consignés par application par le biais de l’interface ILogger.They're logged by the app through the ILogger interface.

Journalisation des traces Azure Application InsightsAzure Application Insights trace logging

Le package de fournisseur Microsoft.Extensions.Logging.ApplicationInsights écrit des journaux dans Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights est un service qui surveille une application web et fournit des outils pour interroger et analyser les données de télémétrie.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Si vous utilisez ce fournisseur, vous pouvez interroger et analyser vos journaux à l’aide des outils Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Le fournisseur de journalisation est inclus en tant que dépendance de Microsoft.ApplicationInsights.AspNetCore, le package qui fournit toutes les données de télémétrie disponibles pour 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. Si vous utilisez ce package, vous n’avez pas besoin d’installer le package du fournisseur.If you use this package, you don't have to install the provider package.

N’utilisez pas le package Microsoft.ApplicationInsights.Web package—destiné à ASP.NET 4.x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Pour plus d'informations, reportez-vous aux ressources suivantes :For more information, see the following resources:

Notes

Depuis le 1/5/2019, l’article intitulé Application Insights pour ASP.NET Core est obsolète et les étapes du tutoriel ne fonctionnent plus.As of 5/1/2019, the article titled Application Insights for ASP.NET Core is out of date, and the tutorial steps don't work. Reportez-vous à Application Insights pour les applications ASP.NET Core à la place.Refer to Application Insights for ASP.NET Core applications instead. Nous sommes conscients du problème et travaillons à y remédier.We are aware of the issue and are working to correct it.

Fournisseurs de journalisation tiersThird-party logging providers

Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :Third-party logging frameworks that work with ASP.NET Core:

Certains frameworks tiers prennent en charge la journalisation sémantique, également appelée journalisation structurée.Some third-party frameworks can perform semantic logging, also known as structured logging.

L’utilisation d’un framework tiers est semblable à l’utilisation des fournisseurs intégrés :Using a third-party framework is similar to using one of the built-in providers:

  1. Ajoutez un package NuGet à votre projet.Add a NuGet package to your project.
  2. Appelez ILoggerFactory.Call an ILoggerFactory.

Pour plus d’informations, consultez la documentation de chaque fournisseur.For more information, see each provider's documentation. Les fournisseurs de journalisation tiers ne sont pas pris en charge par Microsoft.Third-party logging providers aren't supported by Microsoft.

Ressources supplémentairesAdditional resources