Fournisseurs de journalisation dans .NET

  • Article

Les fournisseurs de journalisation conservent les journaux, à l’exception du fournisseur Console, qui affiche uniquement les journaux sous forme de sortie standard. Par exemple, le fournisseur Azure Application Insights stocke les journaux dans Azure Application Insights. Plusieurs fournisseurs peuvent être activés.

Les modèles d’application Worker .NET par défaut :

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

Le code précédent montre la classe Program créée avec les modèles d’application Worker .NET. Les sections suivantes fournissent des exemples basés sur les modèles d’application Worker .NET, qui utilisent l’hôte générique.

Pour remplacer l’ensemble par défaut de fournisseurs de journalisation ajoutés par Host.CreateApplicationBuilder, appelez ClearProviders et ajoutez les fournisseurs de journalisation de votre choix. Par exemple, le code suivant :

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

Pour connaître les autres fournisseurs, consultez :

Configurer un service qui dépend de ILogger

Pour configurer un service qui dépend de ILogger<T>, utilisez l’injection de constructeur ou fournissez une méthode de fabrique. L’approche de la méthode de fabrique est recommandée uniquement s’il n’y a aucune autre option. Par exemple, prenons un service qui a besoin d’une instance ILogger<T> fournie par une injection de dépendances :

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

Le code précédent est un Func<IServiceProvider, IExampleService> qui s’exécute la première fois que le conteneur d’injection doit construire une instance de IExampleService. Vous pouvez accéder à tous les services inscrits de cette manière.

Fournisseurs de journalisation intégrés

Les extensions Microsoft incluent les fournisseurs de journalisation suivants dans le cadre des bibliothèques de runtime :

Les fournisseurs de journalisation suivants sont fournis par Microsoft, mais pas dans le cadre des bibliothèques de runtime. Ils doivent être installés en tant que packages NuGet supplémentaires.

Console

Le fournisseur Console journalise la sortie de la console.

Débogage

Le fournisseur Debug écrit la sortie du journal à l’aide de la classe System.Diagnostics.Debug, en particulier par le biais de la méthode Debug.WriteLine et uniquement lorsque le débogueur est joint. Le DebugLoggerProvider crée des instances DebugLogger, qui sont des implémentations de l’interface ILogger.

Source de l’événement

Le fournisseur EventSource écrit les données dans une source d’événements multiplateforme portant le nom de Microsoft-Extensions-Logging. Sur Windows, le fournisseur utilise ETW.

Outils de suivi dotnet

L’outil dotnet-trace est un outil CLI multiplateforme qui permet la collection de traces .NET Core issues d’un processus en cours d’exécution. L’outil collecte des données de fournisseur Microsoft.Extensions.Logging.EventSource à l’aide d’un LoggingEventSource.

Consultez dotnet-trace pour obtenir des instructions d’installation. Pour accéder à un tutoriel de diagnostic à l’aide de dotnet-trace, consultez Déboguer une utilisation élevée du processeur dans .NET Core.

Journal des événements Windows

Le fournisseur EventLog envoie la sortie de journal dans le journal des événements Windows. Contrairement aux autres fournisseurs, le fournisseur EventLog n’hérite pas des paramètres par défaut qui ne sont pas relatifs au fournisseur. Si les paramètres du journal EventLog ne sont pas spécifiés, leur valeur par défaut est LogLevel.Warning.

Pour journaliser les événements inférieurs à LogLevel.Warning, définissez explicitement le niveau de journalisation. L’exemple suivant définit le niveau de journalisation par défaut du journal des événements sur LogLevel.Information :

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

Les surcharges AddEventLog permettent de passer EventLogSettings. Si la valeur est null ou non spécifiée, les paramètres par défaut suivants sont utilisés :

  • LogName : "Application"
  • SourceName : ".NET Runtime"
  • MachineName : le nom de l’ordinateur local est utilisé.

Le code suivant remplace la valeur par défaut de SourceName (".NET Runtime") par CustomLogs :

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

using IHost host = builder.Build();

host.Run();

Azure App Service

Le package de fournisseur Microsoft.Extensions.Logging.AzureAppServices écrit les enregistrements de journal 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.

Le package du fournisseur n’est pas inclus dans les bibliothèques de runtime. Pour utiliser le fournisseur, ajoutez le package du fournisseur au projet.

Pour configurer les paramètres du fournisseur, utilisez AzureFileLoggerOptions et AzureBlobLoggerOptions, comme illustré dans l’exemple suivant :

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Si elle est déployée dans Azure App Service, l’application utilise les paramètres qui sont définis dans la section Journaux App Service de la page App Service du portail Azure. 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.

L’emplacement par défaut des fichiers journaux se trouve dans le dossier D:\home\LogFiles\Application. Les valeurs par défaut supplémentaires varient selon le fournisseur :

  • Journalisation des applications (système de fichiers) : le nom de fichier du système de fichiers par défaut est diagnostics-aaaammjj.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.
  • Journalisation des applications (blob) : le nom d’objet blob par défaut est {app-name}/aaaa/mm/jj/hh/{guid}_applicationLog.txt.

Ce fournisseur journalise uniquement quand le projet s’exécute dans l’environnement Azure.

Streaming des journaux Azure

Le streaming de journaux Azure prend en charge l’affichage de l’activité des journaux en temps réel provenant de ce qui suit :

  • Serveur d'applications
  • Serveur web
  • Suivi des demandes ayant échoué

Pour configurer le streaming des journaux Azure :

  • Accédez à la page Journaux App Service dans le portail de l’application.
  • Définissez Journal des applications (Système de fichiers) sur Activé.
  • Choisissez le niveau du journal. Ce paramètre s’applique uniquement au streaming de journaux Azure.

Accédez à la page Streaming des journaux pour afficher les journaux. Les messages journalisés le sont avec l’interface ILogger.

Azure Application Insights

Le package de fournisseur Microsoft.Extensions.Logging.ApplicationInsights écrit des journaux dans 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. Si vous utilisez ce fournisseur, vous pouvez interroger et analyser vos journaux à l’aide des outils Application Insights.

Pour plus d’informations, consultez les ressources suivantes :

Considérations relatives à la conception du fournisseur de journalisation

Si vous envisagez de développer votre propre implémentation de l’interface ILoggerProvider et l’implémentation personnalisée correspondante de ILogger, tenez compte des points suivants :

  • La méthode ILogger.Log est synchrone.
  • La durée de vie de l’état du journal et des objets ne doit pas être supposée.

Une implémentation de ILogger va créer un ILoggerProvider via sa méthode ILoggerProvider.CreateLogger. Si votre implémentation s’efforce de mettre en file d’attente les messages de journalisation de façon non bloquante, les messages doivent d’abord être matérialisés ou l’état d’objet utilisé pour matérialiser une entrée de journal doit être sérialisé. Cela permet d’éviter les exceptions potentielles des objets supprimés.

Pour plus d’informations, consultez Implémenter un fournisseur de journalisation personnalisé dans .NET.

Fournisseurs de journalisation tiers

Voici des frameworks de journalisation tiers qui fonctionnent avec différentes charges de travail .NET :

Certains frameworks tiers prennent en charge la journalisation sémantique, également appelée journalisation structurée.

L’utilisation d’un framework tiers est semblable à l’utilisation des fournisseurs intégrés :

  1. Ajoutez un package NuGet à votre projet.
  2. Appelez une méthode d’extension ILoggerFactory ou ILoggingBuilder fournie par le framework de journalisation.

Pour plus d’informations, consultez la documentation de chaque fournisseur. Les fournisseurs de journalisation tiers ne sont pas pris en charge par Microsoft.

Voir aussi