Événement
Championnats du monde Power BI DataViz
14 févr., 16 h - 31 mars, 16 h
Avec 4 chances d’entrer, vous pourriez gagner un package de conférence et le rendre à la Live Grand Finale à Las Vegas
En savoir plusCe navigateur n’est plus pris en charge.
Effectuez une mise à niveau vers Microsoft Edge pour tirer parti des dernières fonctionnalités, des mises à jour de sécurité et du support technique.
Note
Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 de cet article.
Avertissement
Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la stratégie de support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 de cet article.
Important
Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.
Pour la version actuelle, consultez la version .NET 9 de cet article.
Par Kirk Larkin, Juergen Gutsch et Rick Anderson
Cette rubrique décrit la journalisation dans .NET, telle qu’elle s’applique aux applications ASP.NET Core. Pour plus d’informations sur la journalisation dans .NET, consultez Journalisation dans .NET.
Pour obtenir des instructions de journalisation Blazor, qui ajoute ou remplace les instructions de ce nœud, consultez Journalisation Blazor ASP.NET Core.
Les fournisseurs de journalisation permettent de stocker les journaux, à l’exception du fournisseur Console
qui permet d’afficher les journaux. 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 web ASP.NET Core par défaut appellent WebApplication.CreateBuilder, qui ajoute les fournisseurs de journalisation suivants :
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Le code précédent montre le fichier Program.cs
créé à l’aide des modèles d’application web ASP.NET Core. Les sections suivantes fournissent des exemples basés sur les modèles d’application web ASP.NET Core.
Le code suivant remplace l’ensemble de fournisseurs de journalisation par défaut ajouté par WebApplication.CreateBuilder
:
var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole();
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Vous pouvez également écrire le code de journalisation précédent de la façon suivante :
var builder = WebApplication.CreateBuilder();
builder.Host.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
});
Pour connaître les autres fournisseurs, consultez :
Pour créer des journaux, utilisez un objet ILogger<TCategoryName> issu d’une injection de dépendances.
L’exemple suivant :
ILogger<AboutModel>
) qui utilise une catégorie de journal pour le nom complet du type AboutModel
. La catégorie du journal est une chaîne associée à chaque journal.public class AboutModel : PageModel
{
private readonly ILogger _logger;
public AboutModel(ILogger<AboutModel> logger)
{
_logger = logger;
}
public void OnGet()
{
_logger.LogInformation("About page visited at {DT}",
DateTime.UtcNow.ToLongTimeString());
}
}
Les niveaux et les catégories sont expliqués en détail plus loin dans ce document.
Pour plus d’informations sur Blazor, consultez Journalisation Blazor ASP.NET Core.
La configuration de la journalisation est généralement fournie par la section Logging
des fichiers appsettings.{ENVIRONMENT}.json
, où l’espace réservé {ENVIRONMENT}
correspond à l’environnement. Le fichier appsettings.Development.json
suivant est généré par les modèles d’application web ASP.NET Core :
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
}
}
Dans le code JSON précédent :
"Default"
et "Microsoft.AspNetCore"
sont spécifiées."Microsoft.AspNetCore"
s’applique à toutes les catégories qui commencent par "Microsoft.AspNetCore"
. Par exemple, ce paramètre s’applique à la catégorie "Microsoft.AspNetCore.Routing.EndpointMiddleware"
."Microsoft.AspNetCore"
journalise au niveau de journalisation Warning
et aux niveaux supérieurs.LogLevel
s’applique donc à tous les fournisseurs de journalisation activés, à l’exception de Windows EventLog.La propriété Logging
peut avoir des propriétés LogLevel et des propriétés de fournisseur de journaux. La propriété LogLevel
spécifie le niveau de journalisation minimal pour les catégories sélectionnées. Dans le code JSON précédent, les niveaux de journalisation Information
et Warning
sont spécifiés. LogLevel
indique le niveau de gravité du journal, qui peut varier de 0 à 6 :
Trace
= 0, Debug
= 1, Information
= 2, Warning
= 3, Error
= 4, Critical
= 5 et None
= 6.
Quand LogLevel
est spécifié, la journalisation est activée pour les messages au niveau spécifié et aux niveaux supérieurs. Dans le code JSON précédent, la catégorie Default
est journalisée pour Information
et niveaux supérieurs. Par exemple, les messages Information
, Warning
, Error
et Critical
sont journalisés. Si aucun n’est LogLevel
spécifié, la journalisation est définie par défaut sur le niveau Information
. Pour plus d’informations, consultez Niveaux de journalisation.
Une propriété de fournisseur peut spécifier une propriété LogLevel
. Le LogLevel
indiqué sous un fournisseur spécifie les niveaux à journaliser pour ce fournisseur, et remplace les paramètres de journalisation ne concernant pas le fournisseur. Examinons le fichier appsettings.json
suivant :
{
"Logging": {
"LogLevel": { // All providers, LogLevel applies to all the enabled providers.
"Default": "Error", // Default logging, Error and higher.
"Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
},
"Debug": { // Debug provider.
"LogLevel": {
"Default": "Information", // Overrides preceding LogLevel:Default setting.
"Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
}
},
"EventSource": { // EventSource provider
"LogLevel": {
"Default": "Warning" // All categories of EventSource provider.
}
}
}
}
Les paramètres de Logging.{PROVIDER NAME}.LogLevel
remplacent les paramètres de Logging.LogLevel
, où l’espace réservé {PROVIDER NAME}
correspond au nom du fournisseur. Dans le code JSON précédent, le niveau de journalisation par défaut du fournisseur Debug
est défini sur Information
:
Logging:Debug:LogLevel:Default:Information
Le paramètre précédent spécifie le niveau de journalisation Information
pour chaque catégorie Logging:Debug:
, sauf Microsoft.Hosting
. Lorsqu’une catégorie spécifique est listée, celle-ci remplace la catégorie par défaut. Dans le code JSON précédent, les catégories Logging:Debug:LogLevel
"Microsoft.Hosting"
et "Default"
remplacent les paramètres de Logging:LogLevel
Le niveau de journalisation minimal peut être spécifié pour tous les éléments suivants :
Logging:EventSource:LogLevel:Default:Information
Logging:LogLevel:Microsoft:Warning
Logging:LogLevel:Default:Warning
Les journaux situés en dessous du niveau minimal ne seront pas :
Pour empêcher la génération de tous les journaux, spécifiez LogLevel.None. LogLevel.None
a une valeur de 6, ce qui est supérieur à LogLevel.Critical
(5).
Lorsqu’un fournisseur prend en charge les étendues de journal, IncludeScopes
indique si elles sont activées. Pour plus d’informations, consultez Étendues de journalisation.
Le fichier appsettings.json
suivant contient tous les fournisseurs activés par défaut :
{
"Logging": {
"LogLevel": { // No provider, LogLevel applies to all the enabled providers.
"Default": "Error",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Warning"
},
"Debug": { // Debug provider.
"LogLevel": {
"Default": "Information" // Overrides preceding LogLevel:Default setting.
}
},
"Console": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
"Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
"Microsoft.AspNetCore.Mvc.Razor": "Error",
"Default": "Information"
}
},
"EventSource": {
"LogLevel": {
"Microsoft": "Information"
}
},
"EventLog": {
"LogLevel": {
"Microsoft": "Information"
}
},
"AzureAppServicesFile": {
"IncludeScopes": true,
"LogLevel": {
"Default": "Warning"
}
},
"AzureAppServicesBlob": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft": "Information"
}
},
"ApplicationInsights": {
"LogLevel": {
"Default": "Information"
}
}
}
}
Dans l’exemple précédent :
Logging.{PROVIDER NAME}.LogLevel
remplacent les paramètres de Logging.LogLevel
, où l’espace réservé {PROVIDER NAME}
correspond au nom du fournisseur. Par exemple, le niveau dans Debug.LogLevel.Default
remplace le niveau dans LogLevel.Default
.Console
Debug
EventSource
EventLog
AzureAppServicesFile
AzureAppServicesBlob
ApplicationInsights
L’exemple suivant appelle Builder.WebApplication.Logger dans Program.cs
et journalise les messages d’information :
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Logger.LogInformation("Adding Routes");
app.MapGet("/", () => "Hello World!");
app.Logger.LogInformation("Starting the app");
app.Run();
L’exemple suivant appelle AddConsole dans Program.cs
et journalise le point de terminaison /Test
:
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddConsole();
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
logger.LogInformation("Testing logging in Program.cs");
await response.WriteAsync("Testing");
});
app.Run();
L’exemple suivant appelle AddSimpleConsole dans Program.cs
, désactive la sortie couleur et journalise le point de terminaison /Test
:
using Microsoft.Extensions.Logging.Console;
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddSimpleConsole(i => i.ColorBehavior = LoggerColorBehavior.Disabled);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
logger.LogInformation("Testing logging in Program.cs");
await response.WriteAsync("Testing");
});
app.Run();
Le niveau de journalisation peut être défini par l’un des fournisseurs de configuration.
Le séparateur :
ne fonctionne pas avec les clés hiérarchiques des variables d’environnement sur toutes les plateformes. Par exemple, le séparateur :
n’est pas pris en charge par Bash. Le double trait de soulignement __
est :
:
.Les commandes suivantes permettent de :
Logging:LogLevel:Microsoft
sur la valeur Information
dans Windows.dotnet run
doit être exécutée dans le répertoire du projet après l’utilisation de set
.set Logging__LogLevel__Microsoft=Information
dotnet run
Le paramètre d’environnement précédent :
La commande setx suivante définit également la clé et la valeur d’environnement dans Windows. Contrairement à set
, les paramètres setx
sont persistants. Le commutateur /M
définit la variable dans l’environnement système. Si /M
n’est pas utilisé, une variable d’environnement utilisateur est définie.
setx Logging__LogLevel__Microsoft Information /M
Examinons le fichier appsettings.json
suivant :
"Logging": {
"Console": {
"LogLevel": {
"Microsoft.Hosting.Lifetime": "Trace"
}
}
}
La commande suivante définit la configuration précédente dans l’environnement :
setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M
Note
Quand vous configurez des variables d’environnement avec des noms qui contiennent .
(des points) dans macOS et Linux, prenez en compte la question « Exporter une variable avec un point (.) » sur Stack Exchange et sa réponse acceptée correspondante.
Dans Azure App Service, sélectionnez Nouveau paramètre d’application dans la page Paramètres > Configuration. Les paramètres d’application Azure App Service sont :
Pour plus d’informations, consultez Azure Apps : remplacer la configuration de l’application à l’aide du Portail Azure.
Pour plus d’informations sur la définition de valeurs de configuration ASP.NET Core à l’aide de variables d’environnement, consultez Variables d’environnement. Pour plus d’informations sur l’utilisation d’autres sources de configuration, notamment la ligne de commande, Azure Key Vault, Azure App Configuration, d’autres formats de fichiers, etc. consultez Configuration dans ASP.NET Core.
À la création d’un objet ILogger<TCategoryName>, l’objet ILoggerFactory sélectionne une seule règle à appliquer à cet enregistrement d’événements par fournisseur. Tous les messages écrits par une instance ILogger
sont filtrés selon les règles sélectionnées. La règle la plus précise qui peut être appliquée à chaque paire catégorie/fournisseur est sélectionnée parmi les règles disponibles.
L’algorithme suivant est utilisé pour chaque fournisseur quand un objet ILogger
est créé pour une catégorie donnée :
MinimumLevel
.Les journaux créés à l’aide des fournisseurs de journalisation par défaut sont affichés :
dotnet run
.Les journaux qui commencent par les catégories « Microsoft » proviennent de .NET. .NET et le code d’application utilisent la même API de journalisation et les mêmes fournisseurs.
Quand un objet ILogger
est créé, une catégorie est spécifiée. Cette catégorie est incluse dans tous les messages de journal créés par cette instance de ILogger
. La chaîne de la catégorie est arbitraire, mais la convention est d’utiliser le nom complet de la classe. Par exemple, dans un contrôleur, le nom peut être "TodoApi.Controllers.TodoController"
. Les applications web ASP.NET Core utilisent ILogger<T>
pour obtenir automatiquement une instance ILogger
qui utilise le nom de type complet de T
en tant que catégorie :
public class PrivacyModel : PageModel
{
private readonly ILogger<PrivacyModel> _logger;
public PrivacyModel(ILogger<PrivacyModel> logger)
{
_logger = logger;
}
public void OnGet()
{
_logger.LogInformation("GET Pages.PrivacyModel called.");
}
}
SSi une catégorisation plus poussée est souhaitée, la convention consiste à utiliser un nom hiérarchique en ajoutant une sous-catégorie au nom de classe complet, et à spécifier explicitement la catégorie à l’aide de ILoggerFactory.CreateLogger
:
public class ContactModel : PageModel
{
private readonly ILogger _logger;
public ContactModel(ILoggerFactory logger)
{
_logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
}
public void OnGet()
{
_logger.LogInformation("GET Pages.ContactModel called.");
}
L’appel de CreateLogger
avec un nom fixe peut être utile si vous l’utilisez dans plusieurs méthodes afin que les événements puissent être organisés par catégorie.
ILogger<T>
équivaut à appeler CreateLogger
avec le nom de type complet T
.
Le tableau suivant liste les valeurs LogLevel, la méthode d’extension de commodité Log{LogLevel}
, ainsi que des suggestions d’utilisation :
LogLevel | Valeur | Méthode | Description |
---|---|---|---|
Trace | 0 | LogTrace | Contiennent les messages les plus détaillés. Ces messages peuvent contenir des données d’application sensibles. Ils sont désactivés par défaut et ne doivent pas être activés dans un environnement de production. |
Debug | 1 | LogDebug | Pour le débogage et le développement. À utiliser avec prudence dans un environnement de production en raison du volume élevé de messages. |
Information | 2 | LogInformation | Effectue le suivi du flux général de l’application. Peut avoir une valeur à long terme. |
Warning | 3 | LogWarning | Pour les événements anormaux ou inattendus. Comprend généralement des erreurs ou des conditions qui n’entraînent pas l’échec de l’application. |
Error | 4 | LogError | Fournit des informations sur des erreurs et des exceptions qui ne peuvent pas être gérées. Ces messages indiquent un échec de l’opération ou de la demande en cours, et non l’échec de l’application. |
Critical | 5 | LogCritical | Fournit des informations sur des échecs qui nécessitent un examen immédiat. Exemples : perte de données, espace disque insuffisant. |
None | 6 | Spécifie qu’une catégorie de journalisation ne doit écrire aucun message. |
Dans le tableau précédent, LogLevel
est listé du plus faible niveau de gravité au plus élevé.
Le premier paramètre de la méthode Log (LogLevel) indique le niveau de gravité du journal. Au lieu d’appeler Log(LogLevel, ...)
, la plupart des développeurs appellent les méthodes d’extension Log{LOG LEVEL}
, où l’espace réservé {LOG LEVEL}
correspond au niveau de journalisation. Par exemple, les deux appels de journalisation suivants ont un fonctionnement équivalent et produisent le même journal :
[HttpGet]
public IActionResult Test1(int id)
{
var routeInfo = ControllerContext.ToCtxString(id);
_logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
_logger.LogInformation(MyLogEvents.TestItem, routeInfo);
return ControllerContext.MyDisplayRouteInfo();
}
MyLogEvents.TestItem
est l’ID de l’événement. MyLogEvents
fait partie de l’exemple d’application et s’affiche dans la section ID d’événement du journal.
MyDisplayRouteInfo et ToCtxString sont fournis par le package NuGet Rick.Docs.Samples.RouteInfo. Les méthodes affichent les informations de routage Controller
et Razor Page
.
Le code suivant crée des journaux Information
et Warning
:
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
return NotFound();
}
return ItemToDTO(todoItem);
}
Dans le code précédent, le premier paramètre Log{LOG LEVEL}
(MyLogEvents.GetItem
) est l’ID de l’événement de journal. 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. Les paramètres de méthode sont expliqués dans la section Modèle de message plus loin dans ce document.
Appelez la méthode Log{LOG LEVEL}
appropriée pour contrôler le volume de la sortie de journal pouvant être écrite sur un support de stockage spécifique. Exemple :
Trace
, Debug
ou Information
produit un volume élevé de messages de journal détaillés. Pour contrôler les coûts et ne pas dépasser les limites de stockage des données, journaliser Trace
, Debug
ou Information
messages de niveau vers un magasin de données à faible coût et à volume élevé. Envisagez de limiter Trace
, Debug
ou Information
à des catégories spécifiques.Warning
à Critical
doivent produire moins de messages de journal.
Warning
.Trace
, Debug
ou Information
messages lors de la résolution des problèmes. Pour limiter la sortie, définissez Trace
, Debug
ou Information
uniquement pour les catégories en cours d’examen.ASP.NET Core écrit des journaux pour les événements de framework. Par exemple, tenez compte de la sortie du journal pour :
Logging:Console:LogLevel:Microsoft:Information
.info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 149.3023ms 200 text/html; charset=utf-8
Le code JSON suivant définit Logging:Console:LogLevel:Microsoft:Information
:
{
"Logging": { // Default, all providers.
"LogLevel": {
"Microsoft": "Warning"
},
"Console": { // Console provider.
"LogLevel": {
"Microsoft": "Information"
}
}
}
}
Chaque journal peut spécifier un ID d’événement. L’exemple d’application utilise la classe MyLogEvents
pour définir les ID d’événement :
public class MyLogEvents
{
public const int GenerateItems = 1000;
public const int ListItems = 1001;
public const int GetItem = 1002;
public const int InsertItem = 1003;
public const int UpdateItem = 1004;
public const int DeleteItem = 1005;
public const int TestItem = 3000;
public const int GetItemNotFound = 4000;
public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
return NotFound();
}
return ItemToDTO(todoItem);
}
Un ID d’événement associe un jeu d’événements. Par exemple, tous les journaux liés à l’affichage d’une liste d’éléments sur une page peuvent être 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. Le fournisseur Debug n’affiche pas les ID d’événements. Le fournisseur Console affiche les ID d’événements entre crochets après la catégorie :
info: TodoApi.Controllers.TodoItemsController[1002]
Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
Get(1) NOT FOUND
Certains fournisseurs de journalisation stockent l’ID d’événement dans un champ, ce qui permet de filtrer en fonction de l’ID.
Chaque API de journalisation utilise un modèle de message. Ce dernier peut contenir des espaces réservés pour lesquels les arguments sont fournis. Utilisez des noms et non des nombres pour les espaces réservés.
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
return NotFound();
}
return ItemToDTO(todoItem);
}
C’est l’ordre des paramètres, et non leur nom d’espace réservé, qui détermine les paramètres utilisés pour fournir des valeurs d’espace réservé dans les messages de journal. Dans le code suivant, les noms de paramètres ne sont pas dans l’ordre dans le modèle de message :
var apples = 1;
var pears = 2;
var bananas = 3;
_logger.LogInformation("Parameters: {Pears}, {Bananas}, {Apples}", apples, pears, bananas);
Cependant, les paramètres sont attribués aux espaces réservés dans l’ordre : apples
, pears
, bananas
. Le message de journal reflète l’ordre des paramètres :
Parameters: 1, 2, 3
Cette approche permet aux fournisseurs de journalisation d’implémenter une journalisation sémantique ou structurée. Les arguments proprement dits, et pas seulement le modèle de message mis en forme, sont transmis au système de journalisation. Cela permet aux fournisseurs de journalisation de stocker les valeurs des paramètres sous forme de champs. Prenons l’exemple de la méthode d’enregistreur d’événements suivante :
_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);
Par exemple, lorsque vous journalisez des événements vers le Stockage Table Azure :
ID
et RequestTime
.RequestTime
spécifique, sans avoir besoin d’analyser le délai d’expiration du message texte.Les méthodes d’enregistreur d’événements ont des surcharges qui prennent un paramètre d’exception :
[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
var routeInfo = ControllerContext.ToCtxString(id);
_logger.LogInformation(MyLogEvents.TestItem, routeInfo);
try
{
if (id == 3)
{
throw new Exception("Test exception");
}
}
catch (Exception ex)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
return NotFound();
}
return ControllerContext.MyDisplayRouteInfo();
}
MyDisplayRouteInfo et ToCtxString sont fournis par le package NuGet Rick.Docs.Samples.RouteInfo. Les méthodes affichent les informations de routage Controller
et Razor Page
.
La journalisation des exceptions dépend du fournisseur.
Si le niveau de journalisation par défaut n’est pas défini, la valeur sera Information
.
Prenons l’exemple de l’application web suivante :
appsettings.json
et appsettings.Development.json
ont été supprimés ou renommés.Avec la configuration précédente, l’accès à la page de privacy ou d’home produit de nombreux messages Trace
, Debug
et Information
de catégorie Microsoft
.
Le code suivant définit le niveau de journalisation par défaut lorsque celui-ci n’est pas défini dans la configuration :
var builder = WebApplication.CreateBuilder();
builder.Logging.SetMinimumLevel(LogLevel.Warning);
En règle générale, les niveaux de journalisation doivent être spécifiés dans la configuration et non dans le code.
Une fonction de filtre est appelée pour tous les fournisseurs et toutes les catégories auxquels aucune règle n’est affectée dans la configuration ou dans le code :
var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter((provider, category, logLevel) =>
{
if (provider.Contains("ConsoleLoggerProvider")
&& category.Contains("Controller")
&& logLevel >= LogLevel.Information)
{
return true;
}
else if (provider.Contains("ConsoleLoggerProvider")
&& category.Contains("Microsoft")
&& logLevel >= LogLevel.Information)
{
return true;
}
else
{
return false;
}
});
Le code précédent affiche les journaux de console lorsque la catégorie contient Controller
ou Microsoft
, et si le niveau de journalisation est Information
ou supérieur.
En règle générale, les niveaux de journalisation doivent être spécifiés dans la configuration et non dans le code.
Le tableau suivant contient certaines catégories utilisées par ASP.NET Core.
Catégorie | Notes |
---|---|
Microsoft.AspNetCore |
Diagnostics ASP.NET Core généraux. |
Microsoft.AspNetCore.DataProtection |
Liste des clés considérées, trouvées et utilisées. |
Microsoft.AspNetCore.HostFiltering |
Hôtes autorisés. |
Microsoft.AspNetCore.Hosting |
Temps de traitement des requêtes HTTP et heure de démarrage. Liste des assemblys de démarrage d’hébergement chargés. |
Microsoft.AspNetCore.Mvc |
Diagnostics MVC et Razor. Liaison de données, exécution de filtres, compilation de vues, sélection d’actions. |
Microsoft.AspNetCore.Routing |
Informations de correspondance des itinéraires. |
Microsoft.AspNetCore.Server |
Démarrage et arrêt de la connexion, et réponses persistantes. Informations du certificat HTTPS. |
Microsoft.AspNetCore.StaticFiles |
Fichiers pris en charge. |
Pour afficher d’autres catégories dans la fenêtre de console, définissez appsettings.Development.json
sur la valeur suivante :
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Trace",
"Microsoft.Hosting.Lifetime": "Information"
}
}
}
Pour obtenir la liste des catégories d’Entity Framework, consultez les catégories de messages EF.
Une étendue peut regrouper un ensemble d’opérations logiques. Ce regroupement permet de joindre les mêmes données à tous les journaux créés au sein d’un ensemble. Par exemple, chaque journal créé dans le cadre du traitement d’une transaction peut contenir l’ID de la transaction.
Une étendue :
Les fournisseurs suivants prennent en charge les étendues :
Utilisez une étendue en incluant les appels de l’enregistrement d’événements dans un bloc using
:
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
TodoItem todoItem;
var transactionId = Guid.NewGuid().ToString();
using (_logger.BeginScope(new List<KeyValuePair<string, object>>
{
new KeyValuePair<string, object>("TransactionId", transactionId),
}))
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound,
"Get({Id}) NOT FOUND", id);
return NotFound();
}
}
return ItemToDTO(todoItem);
}
ASP.NET Core inclut les fournisseurs de journalisation suivants dans le cadre du framework partagé :
Les fournisseurs de journalisation suivants sont fournis par Microsoft, mais pas dans le cadre du framework partagé. Ils doivent être installés en tant que NuGet supplémentaire.
ASP.NET Core n’inclut pas de fournisseur de journalisation permettant d’écrire des journaux dans des fichiers. Pour écrire des journaux d’activité dans des fichiers à partir d’une application ASP.NET Core, vous pouvez utiliser un fournisseur de journalisation tiers.
Pour plus d’informations sur stdout
et sur la journalisation du débogage avec le module ASP.NET Core, consultez Résoudre les problèmes liés à ASP.NET Core sur Azure App Service et IIS et Module ASP.NET Core (ANCM) pour IIS.
Le fournisseur Console
journalise la sortie de la console. Pour plus d’informations sur l’affichage des journaux Console
durant la phase de développement, consultez Journalisation de la sortie de l’exécution dotnet et Visual Studio.
Le fournisseur Debug
écrit la sortie du journal à l’aide de la classe System.Diagnostics.Debug. Les appels à System.Diagnostics.Debug.WriteLine
sont écrits dans le fournisseur Debug
.
Sur Linux, l’emplacement du journal du fournisseur Debug
dépend de la distribution et peut être l’un des emplacements suivants :
/var/log/message
/var/log/syslog
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.
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.
Pour obtenir des instructions d’installation, consultez dotnet-trace
.
Utilisez les outils dotnet-trace
pour collecter une trace à partir d’une application :
Exécutez l’application avec la commande dotnet run
.
Déterminez l’identificateur de processus (PID) de l’application .NET Core :
dotnet-trace ps
Recherchez le PID du processus qui porte le même nom que l’assembly de l’application.
Exécutez la commande dotnet-trace
.
Syntaxe de commande générale :
dotnet-trace collect -p {PID}
--providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
:FilterSpecs=\"
{Logger Category 1}:{Category Level 1};
{Logger Category 2}:{Category Level 2};
...
{Logger Category N}:{Category Level N}\"
Lorsque vous utilisez un interpréteur de commandes PowerShell, placez la valeur --providers
entre guillemets simples ('
) :
dotnet-trace collect -p {PID}
--providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
:FilterSpecs=\"
{Logger Category 1}:{Category Level 1};
{Logger Category 2}:{Category Level 2};
...
{Logger Category N}:{Category Level N}\"'
Sur les plateformes autres que Windows, ajoutez l’option -f speedscope
pour remplacer le format du fichier de trace de sortie par speedscope
.
Le tableau suivant définit le mot clé :
Mot clé | Description |
---|---|
1 | Journalise les événements meta à propos de LoggingEventSource . Ne journalise pas les événements provenant de ILogger . |
2 | Active l’événement Message lors de l’appel de ILogger.Log() . Fournit les informations de façon programmatique (sans mise en forme). |
4 | Active l’événement FormatMessage lors de l’appel de ILogger.Log() . Fournit la version de chaîne mise en forme des informations. |
8 | Active l’événement MessageJson lors de l’appel de ILogger.Log() . Fournit une représentation JSON des arguments. |
Le tableau suivant liste les niveaux fournisseur :
Niveau fournisseur | Description |
---|---|
0 | LogAlways |
1 | Critical |
2 | Error |
3 | Warning |
4 | Informational |
5 | Verbose |
L’analyse d’un niveau de catégorie peut être une chaîne ou un nombre :
Valeur nommée de catégorie | Valeur numérique |
---|---|
Trace |
0 |
Debug |
1 |
Information |
2 |
Warning |
3 |
Error |
4 |
Critical |
5 |
Le niveau fournisseur et le niveau catégorie :
Si aucune FilterSpecs
n’est spécifiée, l’implémentation de EventSourceLogger
tente de convertir le niveau fournisseur en niveau catégorie, et l’applique à toutes les catégories.
Niveau fournisseur | Niveau catégorie |
---|---|
Verbose (5) |
Debug (1) |
Informational (4) |
Information (2) |
Warning (3) |
Warning (3) |
Error (2) |
Error (4) |
Critical (1) |
Critical (5) |
Si des FilterSpecs
sont fournies, toutes les catégories incluses dans la liste utiliseront le niveau catégorie qui y est encodé. Toutes les autres catégories seront filtrées.
Les exemples suivants supposent ce qui suit :
logger.LogDebug("12345")
.set PID=12345
, où 12345
est le PID réel.Prenez la commande suivante :
dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
La commande précédente :
FilterSpecs
.Prenez la commande suivante :
dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
La commande précédente :
Critical
.FilterSpecs
.La commande suivante capture les messages de débogage, car le niveau de catégorie 1 spécifie Debug
.
dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
La commande suivante capture les messages de débogage, car la catégorie 1 spécifie Debug
.
dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
Les entrées FilterSpecs
pour {Logger Category}
et {Category Level}
représentent des conditions de filtrage des journaux supplémentaires. Séparez les entrées FilterSpecs
par un point-virgule (;
).
Exemple utilisant un interpréteur de commandes Windows :
dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
La commande précédente active :
4
) pour les erreurs (2
).Microsoft.AspNetCore.Hosting
au niveau de journalisation Informational
(4
).Arrêtez les outils dotnet-trace
en appuyant sur la touche Entrée ou sur Ctrl+C.
La trace est enregistrée sous le nom trace.nettrace
dans le dossier où la commande dotnet-trace
est exécutée.
Ouvrez la trace avec Perfview. Ouvrez le fichier trace.nettrace
et explorez les événements de trace.
Si l’application ne génère pas l’hôte avec WebApplication.CreateBuilder, ajoutez le fournisseur de source d’événements à la configuration de journalisation de l’application.
Pour plus d'informations, consultez les pages suivantes :
dotnet-trace
) (documentation .NET Core)dotnet-trace
) (documentation du dépôt GitHub dotnet/diagnostics)Utilisez l’utilitaire PerfView pour collecter et afficher les journaux. 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 Core.
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. N’oubliez pas d’inclure le *
au début de la chaîne.
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 peuvent 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 MyLogs
:
var builder = WebApplication.CreateBuilder();
builder.Logging.AddEventLog(eventLogSettings =>
{
eventLogSettings.SourceName = "MyLogs";
});
Le package de fournisseur Microsoft.Extensions.Logging.AzureAppServices
écrit les journaux dans des fichiers texte dans le système de fichiers d’une application Azure App Service, ainsi que dans un stockage Blob dans un compte de stockage Azure.
Le fournisseur de package n’est pas inclus dans le framework partagé. 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;
var builder = WebApplication.CreateBuilder();
builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
options.FileName = "azure-diagnostics-";
options.FileSizeLimit = 50 * 1024;
options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
options.BlobName = "log.txt";
});
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 est le dossier D:\\home\\LogFiles\\Application
, et le nom de fichier par défaut est 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. Le nom d’objet blob par défaut est {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt
.
Ce fournisseur journalise uniquement quand le projet s’exécute dans l’environnement Azure.
Le streaming de journaux Azure prend en charge l’affichage de l’activité des journaux en temps réel provenant du :
Pour configurer le streaming des journaux Azure :
Accédez à la page Streaming des journaux pour afficher les journaux. Les messages journalisés le sont avec l’interface ILogger
.
Le package de fournisseur Microsoft.Extensions.Logging.ApplicationInsights
écrit les 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.
Le fournisseur de journalisation est inclus en tant que dépendance de Microsoft.ApplicationInsights.AspNetCore
, qui est le package qui fournit toutes les données de télémétrie disponibles pour ASP.NET Core. Si vous utilisez ce package, vous n’avez pas besoin d’installer le package du fournisseur.
Le package Microsoft.ApplicationInsights.Web
est destiné à ASP.NET 4.x, et non à ASP.NET Core.
Pour plus d’informations, consultez les ressources suivantes :
Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :
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 :
ILoggerFactory
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.
La journalisation doit être suffisamment rapide par rapport au coût du code asynchrone en matière de performances. Si un magasin de données de journalisation est lent, n’écrivez pas de données directement dedans. Écrivez les messages de journal dans un magasin rapide, puis déplacez-les vers le magasin lent. Par exemple, lorsque vous vous connectez à SQL Server, ne le faites pas directement dans une méthode Log
, puisque les méthodes Log
sont synchrones. 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. Pour plus d’informations, consultez Guidance on how to log to a message queue for slow data stores (dotnet/AspNetCore.Docs n° 11801).
L’API de journalisation ne permet pas de modifier les niveaux de journalisation pendant l’exécution d’une application. Toutefois, certains fournisseurs de configuration sont capables de recharger la configuration, ce qui agit immédiatement sur la configuration de la journalisation. Par exemple, File Configuration Provider recharge la configuration de journalisation par défaut. Si la configuration est modifiée dans le code pendant l’exécution d’une application, celle-ci peut appeler IConfigurationRoot.Reload pour mettre à jour la configuration de journalisation de l’application.
Les interfaces et les implémentations ILogger<TCategoryName> et ILoggerFactory sont incluses dans le SDK .NET Core. Elles sont également disponibles dans les packages NuGet suivants :
Microsoft.Extensions.Logging.Abstractions
.Microsoft.Extensions.Logging
.Pour définir des règles de filtre de journaux, l’approche recommandée consiste à utiliser Configuration.
L'exemple suivant montre comment enregistrer des règles de filtre dans le code :
using Microsoft.Extensions.Logging.Console;
using Microsoft.Extensions.Logging.Debug;
var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter("System", LogLevel.Debug);
builder.Logging.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information);
builder.Logging.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace);
logging.AddFilter("System", LogLevel.Debug)
spécifie la catégorie System
et le niveau de journalisation Debug
. Le filtre est appliqué à tous les fournisseurs, car aucun fournisseur spécifique n’a été configuré.
AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
spécifie :
Debug
.Information
et niveaux supérieurs."Microsoft"
.Les bibliothèques de journalisation créent implicitement un objet d’étendue avec SpanId
, TraceId
, ParentId
,Baggage
et Tags
. Ce comportement est configuré via ActivityTrackingOptions.
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddSimpleConsole(options =>
{
options.IncludeScopes = true;
});
builder.Logging.Configure(options =>
{
options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
| ActivityTrackingOptions.TraceId
| ActivityTrackingOptions.ParentId
| ActivityTrackingOptions.Baggage
| ActivityTrackingOptions.Tags;
});
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
Si l’en-tête de requête HTTP traceparent
est défini, le ParentId
dans l’étendue du journal affiche le parent-id
W3C issu de l’en-tête entrant traceparent
, et le SpanId
dans l’étendue du journal affiche le parent-id
mis à jour pour l’étape/l’étendue sortante suivante. Pour plus d’informations, consultez Mutating the traceparent Field.
Pour créer un enregistreur d’événements personnalisé, consultez Implémenter un fournisseur de journalisation personnalisé dans .NET.
[LogProperties]
et le nouveau générateur de source de journalisation de télémétriedotnet/runtime
.Par Kirk Larkin, Juergen Gutsch et Rick Anderson
Cette rubrique décrit la journalisation dans .NET, telle qu’elle s’applique aux applications ASP.NET Core. Pour plus d’informations sur la journalisation dans .NET, consultez Journalisation dans .NET. Pour plus d’informations sur la journalisation dans les applications Blazor, consultez Journalisation Blazor ASP.NET Core.
Affichez ou téléchargez un exemple de code (procédure de téléchargement).
Les fournisseurs de journalisation permettent de stocker les journaux, à l’exception du fournisseur Console
qui permet d’afficher les journaux. 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 web ASP.NET Core par défaut :
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
Le code précédent montre la classe Program
créée à l’aide des modèles d’application web ASP.NET Core. Les sections suivantes fournissent des exemples basés sur les modèles d’application web ASP.NET Core, qui utilisent l’hôte générique. Les applications console non hôtes sont abordées plus loin dans ce document.
Pour remplacer l’ensemble par défaut de fournisseurs de journalisation ajoutés par Host.CreateDefaultBuilder
, appelez ClearProviders
puis ajoutez les fournisseurs de journalisation nécessaires. Par exemple, le code suivant :
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.ClearProviders();
logging.AddConsole();
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Pour connaître les autres fournisseurs, consultez :
Pour créer des journaux, utilisez un objet ILogger<TCategoryName> issu d’une injection de dépendances.
L’exemple suivant :
ILogger<AboutModel>
) qui utilise une catégorie de journal pour le nom complet du type AboutModel
. La catégorie du journal est une chaîne associée à chaque journal.Information
. Le niveau du journal indique la gravité de l’événement consigné.public class AboutModel : PageModel
{
private readonly ILogger _logger;
public AboutModel(ILogger<AboutModel> logger)
{
_logger = logger;
}
public string Message { get; set; }
public void OnGet()
{
Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
_logger.LogInformation(Message);
}
}
Les niveaux et les catégories sont expliqués en détail plus loin dans ce document.
Pour plus d’informations sur Blazor, consultez Journalisation Blazor ASP.NET Core.
Créer des journaux dans Main et Startup montre comment créer des journaux dans Main
et Startup
.
La configuration de la journalisation est généralement fournie par la section Logging
des fichiers appsettings.{Environment}.json
. Le fichier appsettings.Development.json
suivant est généré par les modèles d’application web ASP.NET Core :
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
}
}
Dans le code JSON précédent :
"Default"
, "Microsoft"
et "Microsoft.Hosting.Lifetime"
sont spécifiées."Microsoft"
s’applique à toutes les catégories qui commencent par "Microsoft"
. Par exemple, ce paramètre s’applique à la catégorie "Microsoft.AspNetCore.Routing.EndpointMiddleware"
."Microsoft"
journalise au niveau de journalisation Warning
et aux niveaux supérieurs."Microsoft.Hosting.Lifetime"
est plus précise que la catégorie "Microsoft"
. La catégorie "Microsoft.Hosting.Lifetime"
journalise donc au niveau « Informations » et aux niveaux supérieurs.LogLevel
s’applique donc à tous les fournisseurs de journalisation activés, à l’exception de Windows EventLog.La propriété Logging
peut avoir des propriétés LogLevel et des propriétés de fournisseur de journaux. La propriété LogLevel
spécifie le niveau de journalisation minimal pour les catégories sélectionnées. Dans le code JSON précédent, les niveaux de journalisation Information
et Warning
sont spécifiés. LogLevel
indique le niveau de gravité du journal, qui peut varier de 0 à 6 :
Trace
= 0, Debug
= 1, Information
= 2, Warning
= 3, Error
= 4, Critical
= 5 et None
= 6.
Quand LogLevel
est spécifié, la journalisation est activée pour les messages au niveau spécifié et aux niveaux supérieurs. Dans le code JSON précédent, la catégorie Default
est journalisée pour Information
et niveaux supérieurs. Par exemple, les messages Information
, Warning
, Error
et Critical
sont journalisés. Si aucun n’est LogLevel
spécifié, la journalisation est définie par défaut sur le niveau Information
. Pour plus d’informations, consultez Niveaux de journalisation.
Une propriété de fournisseur peut spécifier une propriété LogLevel
. Le LogLevel
indiqué sous un fournisseur spécifie les niveaux à journaliser pour ce fournisseur, et remplace les paramètres de journalisation ne concernant pas le fournisseur. Examinons le fichier appsettings.json
suivant :
{
"Logging": {
"LogLevel": { // All providers, LogLevel applies to all the enabled providers.
"Default": "Error", // Default logging, Error and higher.
"Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
},
"Debug": { // Debug provider.
"LogLevel": {
"Default": "Information", // Overrides preceding LogLevel:Default setting.
"Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
}
},
"EventSource": { // EventSource provider
"LogLevel": {
"Default": "Warning" // All categories of EventSource provider.
}
}
}
}
Les paramètres de Logging.{providername}.LogLevel
remplacent les paramètres de Logging.LogLevel
. Dans le code JSON précédent, le niveau de journalisation par défaut du fournisseur Debug
est défini sur Information
:
Logging:Debug:LogLevel:Default:Information
Le paramètre précédent spécifie le niveau de journalisation Information
pour chaque catégorie Logging:Debug:
, sauf Microsoft.Hosting
. Lorsqu’une catégorie spécifique est listée, celle-ci remplace la catégorie par défaut. Dans le code JSON précédent, les catégories Logging:Debug:LogLevel
"Microsoft.Hosting"
et "Default"
remplacent les paramètres de Logging:LogLevel
Le niveau de journalisation minimal peut être spécifié pour tous les éléments suivants :
Logging:EventSource:LogLevel:Default:Information
Logging:LogLevel:Microsoft:Warning
Logging:LogLevel:Default:Warning
Les journaux situés en dessous du niveau minimal ne seront pas :
Pour supprimer tous les journaux, spécifiez LogLevel.None. LogLevel.None
a une valeur de 6, ce qui est supérieur à LogLevel.Critical
(5).
Lorsqu’un fournisseur prend en charge les étendues de journal, IncludeScopes
indique si elles sont activées. Pour plus d’informations, consultez Étendues de journalisation.
Le fichier appsettings.json
suivant contient tous les fournisseurs activés par défaut :
{
"Logging": {
"LogLevel": { // No provider, LogLevel applies to all the enabled providers.
"Default": "Error",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Warning"
},
"Debug": { // Debug provider.
"LogLevel": {
"Default": "Information" // Overrides preceding LogLevel:Default setting.
}
},
"Console": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
"Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
"Microsoft.AspNetCore.Mvc.Razor": "Error",
"Default": "Information"
}
},
"EventSource": {
"LogLevel": {
"Microsoft": "Information"
}
},
"EventLog": {
"LogLevel": {
"Microsoft": "Information"
}
},
"AzureAppServicesFile": {
"IncludeScopes": true,
"LogLevel": {
"Default": "Warning"
}
},
"AzureAppServicesBlob": {
"IncludeScopes": true,
"LogLevel": {
"Microsoft": "Information"
}
},
"ApplicationInsights": {
"LogLevel": {
"Default": "Information"
}
}
}
}
Dans l’exemple précédent :
Logging.{providername}.LogLevel
remplacent les paramètres de Logging.LogLevel
. Par exemple, le niveau dans Debug.LogLevel.Default
remplace le niveau dans LogLevel.Default
.Le niveau de journalisation peut être défini par l’un des fournisseurs de configuration.
Le séparateur :
ne fonctionne pas avec les clés hiérarchiques des variables d’environnement sur toutes les plateformes. Par exemple, le séparateur :
n’est pas pris en charge par Bash. Le double trait de soulignement __
est :
:
.Les commandes suivantes permettent de :
Logging:LogLevel:Microsoft
sur la valeur Information
dans Windows.dotnet run
doit être exécutée dans le répertoire du projet après l’utilisation de set
.set Logging__LogLevel__Microsoft=Information
dotnet run
Le paramètre d’environnement précédent :
La commande setx suivante définit également la clé et la valeur d’environnement dans Windows. Contrairement à set
, les paramètres setx
sont persistants. Le commutateur /M
définit la variable dans l’environnement système. Si /M
n’est pas utilisé, une variable d’environnement utilisateur est définie.
setx Logging__LogLevel__Microsoft Information /M
Examinons le fichier appsettings.json
suivant :
"Logging": {
"Console": {
"LogLevel": {
"Microsoft.Hosting.Lifetime": "Trace"
}
}
}
La commande suivante définit la configuration précédente dans l’environnement :
setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M
Dans Azure App Service, sélectionnez Nouveau paramètre d’application dans la page Paramètres > Configuration. Les paramètres d’application Azure App Service sont :
Pour plus d’informations, consultez Azure Apps : remplacer la configuration de l’application à l’aide du portail Azure.
Pour plus d’informations sur la définition de valeurs de configuration ASP.NET Core à l’aide de variables d’environnement, consultez Variables d’environnement. Pour plus d’informations sur l’utilisation d’autres sources de configuration, notamment la ligne de commande, Azure Key Vault, Azure App Configuration, d’autres formats de fichiers, etc. consultez Configuration dans ASP.NET Core.
À la création d’un objet ILogger<TCategoryName>, l’objet ILoggerFactory sélectionne une seule règle à appliquer à cet enregistrement d’événements par fournisseur. Tous les messages écrits par une instance ILogger
sont filtrés selon les règles sélectionnées. La règle la plus précise qui peut être appliquée à chaque paire catégorie/fournisseur est sélectionnée parmi les règles disponibles.
L’algorithme suivant est utilisé pour chaque fournisseur quand un objet ILogger
est créé pour une catégorie donnée :
MinimumLevel
.Les journaux créés à l’aide des fournisseurs de journalisation par défaut sont affichés :
dotnet run
.Les journaux qui commencent par les catégories « Microsoft » proviennent du code du framework ASP.NET Core. ASP.NET Core et le code d’application utilisent la même API de journalisation et les mêmes fournisseurs.
Quand un objet ILogger
est créé, une catégorie est spécifiée. Cette catégorie est incluse dans tous les messages de journal créés par cette instance de ILogger
. La chaîne de catégorie est arbitraire, cependant, la convention veut que l’on utilise le nom de la classe. Par exemple, dans un contrôleur, le nom peut être "TodoApi.Controllers.TodoController"
. Les applications web ASP.NET Core utilisent ILogger<T>
pour obtenir automatiquement une instance ILogger
qui utilise le nom de type complet de T
en tant que catégorie :
public class PrivacyModel : PageModel
{
private readonly ILogger<PrivacyModel> _logger;
public PrivacyModel(ILogger<PrivacyModel> logger)
{
_logger = logger;
}
public void OnGet()
{
_logger.LogInformation("GET Pages.PrivacyModel called.");
}
}
Pour spécifier explicitement la catégorie, appelez ILoggerFactory.CreateLogger
:
public class ContactModel : PageModel
{
private readonly ILogger _logger;
public ContactModel(ILoggerFactory logger)
{
_logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
}
public void OnGet()
{
_logger.LogInformation("GET Pages.ContactModel called.");
}
L’appel de CreateLogger
avec un nom fixe peut être utile si vous l’utilisez dans plusieurs méthodes afin que les événements puissent être organisés par catégorie.
ILogger<T>
équivaut à appeler CreateLogger
avec le nom de type complet T
.
Le tableau suivant liste les valeurs LogLevel, la méthode d’extension de commodité Log{LogLevel}
, ainsi que des suggestions d’utilisation :
LogLevel | Valeur | Méthode | Description |
---|---|---|---|
Trace | 0 | LogTrace | Contiennent les messages les plus détaillés. Ces messages peuvent contenir des données d’application sensibles. Ils sont désactivés par défaut et ne doivent pas être activés dans un environnement de production. |
Déboguer | 1 | LogDebug | Pour le débogage et le développement. À utiliser avec prudence dans un environnement de production en raison du volume élevé de messages. |
Information | 2 | LogInformation | Effectue le suivi du flux général de l’application. Peut avoir une valeur à long terme. |
Avertissement | 3 | LogWarning | Pour les événements anormaux ou inattendus. Comprend généralement des erreurs ou des conditions qui n’entraînent pas l’échec de l’application. |
Error | 4 | LogError | Fournit des informations sur des erreurs et des exceptions qui ne peuvent pas être gérées. Ces messages indiquent un échec de l’opération ou de la demande en cours, et non l’échec de l’application. |
Critical | 5 | LogCritical | Fournit des informations sur des échecs qui nécessitent un examen immédiat. Exemples : perte de données, espace disque insuffisant. |
Aucun | 6 | Spécifie qu’une catégorie de journalisation ne doit écrire aucun message. |
Dans le tableau précédent, LogLevel
est listé du plus faible niveau de gravité au plus élevé.
Le premier paramètre de la méthode Log (LogLevel) indique le niveau de gravité du journal. Au lieu d’appeler Log(LogLevel, ...)
, la plupart des développeurs appellent les méthodes d’extension Log{LogLevel}. Les méthodes d’extension Log{LogLevel}
appellent la méthode Log et spécifient le LogLevel. Par exemple, les deux appels de journalisation suivants ont un fonctionnement équivalent et produisent le même journal :
[HttpGet]
public IActionResult Test1(int id)
{
var routeInfo = ControllerContext.ToCtxString(id);
_logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
_logger.LogInformation(MyLogEvents.TestItem, routeInfo);
return ControllerContext.MyDisplayRouteInfo();
}
MyLogEvents.TestItem
est l’ID de l’événement. MyLogEvents
fait partie de l’exemple d’application et s’affiche dans la section ID d’événement du journal.
MyDisplayRouteInfo et ToCtxString sont fournis par le package NuGet Rick.Docs.Samples.RouteInfo. Les méthodes affichent les informations de routage Controller
et Razor Page
.
Le code suivant crée des journaux Information
et Warning
:
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
return NotFound();
}
return ItemToDTO(todoItem);
}
Dans le code précédent, le premier paramètre Log{LogLevel}
(MyLogEvents.GetItem
) est l’ID de l’événement de journal. 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. Les paramètres de méthode sont expliqués dans la section Modèle de message plus loin dans ce document.
Appelez la méthode Log{LogLevel}
appropriée pour contrôler le volume de la sortie de journal pouvant être écrite sur un support de stockage spécifique. Exemple :
Trace
ou Information
produit un volume élevé de messages de journal détaillés. Pour contrôler les coûts et ne pas dépasser les limites de stockage des données, journalisez les messages de niveau Trace
et Information
dans un magasin de données à haut volume et à faible coût. Il est conseillé de limiter Trace
et Information
à certaines catégories.Warning
à Critical
doivent produire moins de messages de journal.
Warning
.Trace
ou Information
lorsque vous résolvez des problèmes. Pour limiter la sortie, définissez Trace
ou Information
uniquement pour les catégories en cours d’investigation.ASP.NET Core écrit des journaux pour les événements de framework. Par exemple, tenez compte de la sortie du journal pour :
Logging:Console:LogLevel:Microsoft:Information
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
Request finished in 149.3023ms 200 text/html; charset=utf-8
Le code JSON suivant définit Logging:Console:LogLevel:Microsoft:Information
:
{
"Logging": { // Default, all providers.
"LogLevel": {
"Microsoft": "Warning"
},
"Console": { // Console provider.
"LogLevel": {
"Microsoft": "Information"
}
}
}
}
Chaque journal peut spécifier un ID d’événement. L’exemple d’application utilise la classe MyLogEvents
pour définir les ID d’événement :
public class MyLogEvents
{
public const int GenerateItems = 1000;
public const int ListItems = 1001;
public const int GetItem = 1002;
public const int InsertItem = 1003;
public const int UpdateItem = 1004;
public const int DeleteItem = 1005;
public const int TestItem = 3000;
public const int GetItemNotFound = 4000;
public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
return NotFound();
}
return ItemToDTO(todoItem);
}
Un ID d’événement associe un jeu d’événements. Par exemple, tous les journaux liés à l’affichage d’une liste d’éléments sur une page peuvent être 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. Le fournisseur Debug n’affiche pas les ID d’événements. Le fournisseur Console affiche les ID d’événements entre crochets après la catégorie :
info: TodoApi.Controllers.TodoItemsController[1002]
Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
Get(1) NOT FOUND
Certains fournisseurs de journalisation stockent l’ID d’événement dans un champ, ce qui permet de filtrer en fonction de l’ID.
Chaque API de journalisation utilise un modèle de message. Ce dernier peut contenir des espaces réservés pour lesquels les arguments sont fournis. Utilisez des noms et non des nombres pour les espaces réservés.
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
return NotFound();
}
return ItemToDTO(todoItem);
}
C’est l’ordre des paramètres, et non leur nom d’espace réservé, qui détermine les paramètres utilisés pour fournir des valeurs d’espace réservé dans les messages de journal. Dans le code suivant, les noms de paramètres ne sont pas dans l’ordre dans le modèle de message :
var apples = 1;
var pears = 2;
var bananas = 3;
_logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);
Cependant, les paramètres sont attribués aux espaces réservés dans l’ordre : apples
, pears
, bananas
. Le message de journal reflète l’ordre des paramètres :
Parameters: 1, 2, 3
Cette approche permet aux fournisseurs de journalisation d’implémenter une journalisation sémantique ou structurée. Les arguments proprement dits, et pas seulement le modèle de message mis en forme, sont transmis au système de journalisation. Cela permet aux fournisseurs de journalisation de stocker les valeurs des paramètres sous forme de champs. Prenons l’exemple de la méthode d’enregistreur d’événements suivante :
_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);
Par exemple, lorsque vous journalisez des événements vers le Stockage Table Azure :
ID
et RequestTime
.RequestTime
spécifique, sans avoir besoin d’analyser le délai d’expiration du message texte.Les méthodes d’enregistreur d’événements ont des surcharges qui prennent un paramètre d’exception :
[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
var routeInfo = ControllerContext.ToCtxString(id);
_logger.LogInformation(MyLogEvents.TestItem, routeInfo);
try
{
if (id == 3)
{
throw new Exception("Test exception");
}
}
catch (Exception ex)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
return NotFound();
}
return ControllerContext.MyDisplayRouteInfo();
}
MyDisplayRouteInfo et ToCtxString sont fournis par le package NuGet Rick.Docs.Samples.RouteInfo. Les méthodes affichent les informations de routage Controller
et Razor Page
.
La journalisation des exceptions dépend du fournisseur.
Si le niveau de journalisation par défaut n’est pas défini, la valeur sera Information
.
Prenons l’exemple de l’application web suivante :
appsettings.json
et appsettings.Development.json
ont été supprimés ou renommés.Avec la configuration précédente, l’accès à la page de privacy ou d’home produit de nombreux messages Trace
, Debug
et Information
de catégorie Microsoft
.
Le code suivant définit le niveau de journalisation par défaut lorsque celui-ci n’est pas défini dans la configuration :
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
En règle générale, les niveaux de journalisation doivent être spécifiés dans la configuration et non dans le code.
Une fonction de filtre est appelée pour tous les fournisseurs et toutes les catégories auxquels aucune règle n’est affectée dans la configuration ou dans le code :
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.AddFilter((provider, category, logLevel) =>
{
if (provider.Contains("ConsoleLoggerProvider")
&& category.Contains("Controller")
&& logLevel >= LogLevel.Information)
{
return true;
}
else if (provider.Contains("ConsoleLoggerProvider")
&& category.Contains("Microsoft")
&& logLevel >= LogLevel.Information)
{
return true;
}
else
{
return false;
}
});
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
Le code précédent affiche les journaux de console lorsque la catégorie contient Controller
ou Microsoft
, et si le niveau de journalisation est Information
ou supérieur.
En règle générale, les niveaux de journalisation doivent être spécifiés dans la configuration et non dans le code.
Le tableau suivant contient certaines catégories utilisées par ASP.NET Core et Entity Framework Core, ainsi que des notes à propos des journaux :
Catégorie | Notes |
---|---|
Microsoft.AspNetCore | Diagnostics ASP.NET Core généraux. |
Microsoft.AspNetCore.DataProtection | Liste des clés considérées, trouvées et utilisées. |
Microsoft.AspNetCore.HostFiltering | Hôtes autorisés. |
Microsoft.AspNetCore.Hosting | Temps de traitement des requêtes HTTP et heure de démarrage. Liste des assemblys de démarrage d’hébergement chargés. |
Microsoft.AspNetCore.Mvc | Diagnostics MVC et Razor. Liaison de données, exécution de filtres, compilation de vues, sélection d’actions. |
Microsoft.AspNetCore.Routing | Informations de correspondance des itinéraires. |
Microsoft.AspNetCore.Server | Démarrage et arrêt de la connexion, et réponses persistantes. Informations du certificat HTTPS. |
Microsoft.AspNetCore.StaticFiles | Fichiers pris en charge. |
Microsoft.EntityFrameworkCore | Diagnostics Entity Framework Core généraux. Activité et configuration de la base de données, détection des modifications, migrations. |
Pour afficher d’autres catégories dans la fenêtre de console, définissez appsettings.Development.json
sur la valeur suivante :
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Trace",
"Microsoft.Hosting.Lifetime": "Information"
}
}
}
Une étendue peut regrouper un ensemble d’opérations logiques. Ce regroupement permet de joindre les mêmes données à tous les journaux créés au sein d’un ensemble. Par exemple, chaque journal créé dans le cadre du traitement d’une transaction peut contenir l’ID de la transaction.
Une étendue :
Les fournisseurs suivants prennent en charge les étendues :
Utilisez une étendue en incluant les appels de l’enregistrement d’événements dans un bloc using
:
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
TodoItem todoItem;
var transactionId = Guid.NewGuid().ToString();
using (_logger.BeginScope(new List<KeyValuePair<string, object>>
{
new KeyValuePair<string, object>("TransactionId", transactionId),
}))
{
_logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);
todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
_logger.LogWarning(MyLogEvents.GetItemNotFound,
"Get({Id}) NOT FOUND", id);
return NotFound();
}
}
return ItemToDTO(todoItem);
}
ASP.NET Core inclut les fournisseurs de journalisation suivants dans le cadre du framework partagé :
Les fournisseurs de journalisation suivants sont fournis par Microsoft, mais pas dans le cadre du framework partagé. Ils doivent être installés en tant que NuGet supplémentaire.
ASP.NET Core n’inclut pas de fournisseur de journalisation permettant d’écrire des journaux dans des fichiers. Pour écrire des journaux d’activité dans des fichiers à partir d’une application ASP.NET Core, vous pouvez utiliser un fournisseur de journalisation tiers.
Pour plus d’informations sur stdout
et sur la journalisation du débogage avec le module ASP.NET Core, consultez Résoudre les problèmes liés à ASP.NET Core sur Azure App Service et IIS et Module ASP.NET Core (ANCM) pour IIS.
Le fournisseur Console
journalise la sortie de la console. Pour plus d’informations sur l’affichage des journaux Console
durant la phase de développement, consultez Journalisation de la sortie de l’exécution dotnet et Visual Studio.
Le fournisseur Debug
écrit la sortie du journal à l’aide de la classe System.Diagnostics.Debug. Les appels à System.Diagnostics.Debug.WriteLine
sont écrits dans le fournisseur Debug
.
Sur Linux, l’emplacement du journal du fournisseur Debug
dépend de la distribution et peut être l’un des emplacements suivants :
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.
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.
Utilisez les outils dotnet-trace pour collecter une trace à partir d’une application :
Exécutez l’application avec la commande dotnet run
.
Déterminez l’identificateur de processus (PID) de l’application .NET Core :
dotnet trace ps
Recherchez le PID du processus qui porte le même nom que l’assembly de l’application.
Exécutez la commande dotnet trace
.
Syntaxe de commande générale :
dotnet trace collect -p {PID}
--providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
:FilterSpecs=\"
{Logger Category 1}:{Category Level 1};
{Logger Category 2}:{Category Level 2};
...
{Logger Category N}:{Category Level N}\"
Lorsque vous utilisez un interpréteur de commandes PowerShell, placez la valeur --providers
entre guillemets simples ('
) :
dotnet trace collect -p {PID}
--providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
:FilterSpecs=\"
{Logger Category 1}:{Category Level 1};
{Logger Category 2}:{Category Level 2};
...
{Logger Category N}:{Category Level N}\"'
Sur les plateformes autres que Windows, ajoutez l’option -f speedscope
pour remplacer le format du fichier de trace de sortie par speedscope
.
Le tableau suivant définit le mot clé :
Mot clé | Description |
---|---|
1 | Journalise les événements meta à propos de LoggingEventSource . Ne journalise pas les événements provenant de ILogger . |
2 | Active l’événement Message lors de l’appel de ILogger.Log() . Fournit les informations de façon programmatique (sans mise en forme). |
4 | Active l’événement FormatMessage lors de l’appel de ILogger.Log() . Fournit la version de chaîne mise en forme des informations. |
8 | Active l’événement MessageJson lors de l’appel de ILogger.Log() . Fournit une représentation JSON des arguments. |
Le tableau suivant liste les niveaux fournisseur :
Niveau fournisseur | Description |
---|---|
0 | LogAlways |
1 | Critical |
2 | Error |
3 | Warning |
4 | Informational |
5 | Verbose |
L’analyse d’un niveau de catégorie peut être une chaîne ou un nombre :
Valeur nommée de catégorie | Valeur numérique |
---|---|
Trace |
0 |
Debug |
1 |
Information |
2 |
Warning |
3 |
Error |
4 |
Critical |
5 |
Le niveau fournisseur et le niveau catégorie :
Si aucune FilterSpecs
n’est spécifiée, l’implémentation de EventSourceLogger
tente de convertir le niveau fournisseur en niveau catégorie, et l’applique à toutes les catégories.
Niveau fournisseur | Niveau catégorie |
---|---|
Verbose (5) |
Debug (1) |
Informational (4) |
Information (2) |
Warning (3) |
Warning (3) |
Error (2) |
Error (4) |
Critical (1) |
Critical (5) |
Si des FilterSpecs
sont fournies, toutes les catégories incluses dans la liste utiliseront le niveau catégorie qui y est encodé. Toutes les autres catégories seront filtrées.
Les exemples suivants supposent ce qui suit :
logger.LogDebug("12345")
.set PID=12345
, où 12345
est le PID réel.Prenez la commande suivante :
dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
La commande précédente :
FilterSpecs
.Prenez la commande suivante :
dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
La commande précédente :
Critical
.FilterSpecs
.La commande suivante capture les messages de débogage, car le niveau de catégorie 1 spécifie Debug
.
dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
La commande suivante capture les messages de débogage, car la catégorie 1 spécifie Debug
.
dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
Les entrées FilterSpecs
pour {Logger Category}
et {Category Level}
représentent des conditions de filtrage des journaux supplémentaires. Séparez les entrées FilterSpecs
par un point-virgule (;
).
Exemple utilisant un interpréteur de commandes Windows :
dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
La commande précédente active :
4
) pour les erreurs (2
).Microsoft.AspNetCore.Hosting
au niveau de journalisation Informational
(4
).Arrêtez les outils de trace dotnet en appuyant sur la touche Entrée ou Ctrl+C.
La trace est enregistrée sous le nom trace.nettrace dans le dossier où la commande dotnet trace
est exécutée.
Ouvrez la trace avec Perfview. Ouvrez le fichier trace.nettrace et explorez les événements de trace.
Si l’application ne génère pas l’hôte avec CreateDefaultBuilder
, ajoutez le fournisseur de source d’événements à la configuration de journalisation de l’application.
Pour plus d'informations, consultez les pages suivantes :
release/{Version}
, où {Version}
correspond à la version d’ASP.NET Core souhaitée.Utilisez l’utilitaire PerfView pour collecter et afficher les journaux. 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 Core.
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. N’oubliez pas d’inclure le *
au début de la chaîne.
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 MyLogs
:
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
{
logging.AddEventLog(eventLogSettings =>
{
eventLogSettings.SourceName = "MyLogs";
});
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
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 fournisseur de package n’est pas inclus dans le framework partagé. 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 :
public class Scopes
{
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
.ConfigureServices(serviceCollection => serviceCollection
.Configure<AzureFileLoggerOptions>(options =>
{
options.FileName = "azure-diagnostics-";
options.FileSizeLimit = 50 * 1024;
options.RetainedFileCountLimit = 5;
})
.Configure<AzureBlobLoggerOptions>(options =>
{
options.BlobName = "log.txt";
}))
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
}
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 est le dossier D:\home\LogFiles\Application, et le nom de fichier par défaut est 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. Le nom par défaut du blob est {app-name}{timestamp}/aaaa/mm/jj/hh/{guid}-applicationLog.txt.
Ce fournisseur journalise uniquement quand le projet s’exécute dans l’environnement Azure.
Le streaming de journaux Azure prend en charge l’affichage de l’activité des journaux en temps réel provenant du :
Pour configurer le streaming des journaux Azure :
Accédez à la page Streaming des journaux pour afficher les journaux. Les messages journalisés le sont avec l’interface ILogger
.
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.
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. Si vous utilisez ce package, vous n’avez pas besoin d’installer le package du fournisseur.
Le package Microsoft.ApplicationInsights.Web est destiné à ASP.NET 4.x, et non à ASP.NET Core.
Pour plus d’informations, consultez les ressources suivantes :
Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :
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 :
ILoggerFactory
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.
Pour obtenir un exemple d’utilisation de l’hôte générique dans une application console non web, consultez le fichier Program.cs
de l’exemple d’application Background Tasks (Tâches d’arrière-plan avec des services hébergés dans ASP.NET Core).
Le code de journalisation pour les applications sans hôte générique diffère de la façon dont les fournisseurs sont ajoutés et enregistreurs d’événements sont créés.
Dans une application de console non hôte, appelez la méthode d’extension Add{provider name}
du fournisseur lors de la création d’un LoggerFactory
:
class Program
{
static void Main(string[] args)
{
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");
}
}
Pour créer des journaux, utilisez un objet ILogger<TCategoryName>. Utilisez LoggerFactory
pour créer un ILogger
.
L’exemple suivant crée un enregistreur d’événements de catégorie LoggingConsoleApp.Program
.
class Program
{
static void Main(string[] args)
{
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");
}
}
Dans l’exemple suivant, l’enregistreur d’événements est utilisé pour créer des journaux de niveau Information
. Le niveau du journal indique la gravité de l’événement consigné.
class Program
{
static void Main(string[] args)
{
using var loggerFactory = LoggerFactory.Create(builder =>
{
builder
.AddFilter("Microsoft", LogLevel.Warning)
.AddFilter("System", LogLevel.Warning)
.AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
.AddConsole()
.AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");
}
}
Les niveaux et les catégories sont expliqués en détail dans ce document.
La journalisation pendant la construction de l’hôte n’est pas prise en charge directement. Toutefois, un enregistreur d’événements distinct peut être utilisé. Dans l’exemple suivant, un enregistreur d’événements Serilog est utilisé pour journaliser dans CreateHostBuilder
. AddSerilog
utilise la configuration statique spécifiée dans 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();
}
}
}
L’injection de constructeur d’un enregistreur d’événements dans Startup
fonctionne dans les versions antérieures d’ASP.NET Core, car un conteneur d’injection de dépendances distinct est créé pour l’hôte web. Pour plus d’informations sur la raison de la création d’un seul conteneur pour l’hôte générique, consultez l’annonce de changement cassant.
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 :
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddRazorPages();
services.AddSingleton<IMyService>((container) =>
{
var logger = container.GetRequiredService<ILogger<MyService>>();
return new MyService() { Logger = logger };
});
}
Le code en surbrillance précédent est une Func<T,TResult> qui s’exécute la première fois que le conteneur d’injection de dépendances doit construire une instance de MyService
. Vous pouvez accéder à tous les services inscrits de cette manière.
Le code suivant journalise dans Main
en obtenant une instance ILogger
à partir d’une injection de dépendances après avoir créé l’hôte :
public static void Main(string[] args)
{
var host = CreateHostBuilder(args).Build();
var logger = host.Services.GetRequiredService<ILogger<Program>>();
logger.LogInformation("Host created.");
host.Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Le code suivant écrit les journaux dans Startup.Configure
:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
ILogger<Startup> logger)
{
if (env.IsDevelopment())
{
logger.LogInformation("In Development.");
app.UseDeveloperExceptionPage();
}
else
{
logger.LogInformation("Not Development.");
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapRazorPages();
});
}
L’écriture de journaux avant la fin de l’installation du conteneur d’injection de dépendances dans la méthode Startup.ConfigureServices
n’est pas prise en charge :
Startup
n’est pas prise en charge.Startup.ConfigureServices
n’est pas prise en charge.La raison de cette restriction est que la journalisation dépend de l’injection de dépendances et de la configuration qui, à son tour, dépend de l’injection de dépendances. Le conteneur d’injection de dépendances n’est pas configuré avant que ConfigureServices
soit terminé.
Pour plus d’informations sur la configuration d’un service qui dépend de ILogger<T>
, ou pour savoir pourquoi l’injection de constructeur d’un enregistreur d’événements dans Startup
fonctionnait dans les versions antérieures, consultez Configurer un service qui dépend de ILogger
La journalisation doit être suffisamment rapide par rapport au coût du code asynchrone en matière de performances. Si un magasin de données de journalisation est lent, n’écrivez pas de données directement dedans. Écrivez les messages de journal dans un magasin rapide, puis déplacez-les vers le magasin lent. Par exemple, lorsque vous vous connectez à SQL Server, ne le faites pas directement dans une méthode Log
, puisque les méthodes Log
sont synchrones. 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. Pour plus d’informations, consultez ce problème GitHub.
L’API de journalisation ne permet pas de modifier les niveaux de journalisation pendant l’exécution d’une application. Toutefois, certains fournisseurs de configuration sont capables de recharger la configuration, ce qui agit immédiatement sur la configuration de la journalisation. Par exemple, File Configuration Provider recharge la configuration de journalisation par défaut. Si la configuration est modifiée dans le code pendant l’exécution d’une application, celle-ci peut appeler IConfigurationRoot.Reload pour mettre à jour la configuration de journalisation de l’application.
Les interfaces et les implémentations ILogger<TCategoryName> et ILoggerFactory sont incluses dans le SDK .NET Core. Elles sont également disponibles dans les packages NuGet suivants :
Pour définir des règles de filtre de journaux, l’approche recommandée consiste à utiliser Configuration.
L'exemple suivant montre comment enregistrer des règles de filtre dans le code :
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureLogging(logging =>
logging.AddFilter("System", LogLevel.Debug)
.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
logging.AddFilter("System", LogLevel.Debug)
spécifie la catégorie System
et le niveau de journalisation Debug
. Le filtre est appliqué à tous les fournisseurs, car aucun fournisseur spécifique n’a été configuré.
AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
spécifie :
Debug
.Information
et niveaux supérieurs."Microsoft"
.Les bibliothèques de journalisation créent implicitement un objet d’étendue avec SpanId
, TraceId
et ParentId
. Ce comportement est configuré via ActivityTrackingOptions.
var loggerFactory = LoggerFactory.Create(logging =>
{
logging.Configure(options =>
{
options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
| ActivityTrackingOptions.TraceId
| ActivityTrackingOptions.ParentId;
}).AddSimpleConsole(options =>
{
options.IncludeScopes = true;
});
});
Si l’en-tête de requête HTTP traceparent
est défini, le ParentId
dans l’étendue du journal affiche le parent-id
W3C issu de l’en-tête entrant traceparent
, et le SpanId
dans l’étendue du journal affiche le parent-id
mis à jour pour l’étape/l’étendue sortante suivante. Pour plus d’informations, consultez Mutating the traceparent Field.
Pour créer un enregistreur d’événements personnalisé, consultez Implémenter un fournisseur de journalisation personnalisé dans .NET.
Commentaires sur ASP.NET Core
ASP.NET Core est un projet open source. Sélectionnez un lien pour fournir des commentaires :
Événement
Championnats du monde Power BI DataViz
14 févr., 16 h - 31 mars, 16 h
Avec 4 chances d’entrer, vous pourriez gagner un package de conférence et le rendre à la Live Grand Finale à Las Vegas
En savoir plus