Journalisation dans .NET Core et ASP.NET Core
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 :
- Console
- Déboguer
- EventSource
- EventLog : Windows uniquement
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 :
- Crée un enregistreur d’événements (
ILogger<AboutModel>
) qui utilise une catégorie de journal pour le nom complet du typeAboutModel
. La catégorie du journal est une chaîne associée à chaque journal. - Appelle LogInformation pour journaliser au niveau 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 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 :
- Les catégories
"Default"
et"Microsoft.AspNetCore"
sont spécifiées. - La catégorie
"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"
. - La catégorie
"Microsoft.AspNetCore"
journalise au niveau de journalisationWarning
et aux niveaux supérieurs. - Aucun fournisseur de journaux n’est spécifié.
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 :
- Certains fournisseurs : par exemple,
Logging:EventSource:LogLevel:Default:Information
- Certaines catégories : par exemple,
Logging:LogLevel:Microsoft:Warning
- Tous les fournisseurs et toutes les catégories :
Logging:LogLevel:Default:Warning
Les journaux situés en dessous du niveau minimal ne seront pas :
- Passés au fournisseur.
- Journalisés ou affichés.
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 :
- Les catégories et les niveaux ne sont pas des valeurs suggérées. L’exemple est fourni pour afficher la totalité des fournisseurs par défaut.
- Les paramètres de
Logging.{PROVIDER NAME}.LogLevel
remplacent les paramètres deLogging.LogLevel
, où l’espace réservé{PROVIDER NAME}
correspond au nom du fournisseur. Par exemple, le niveau dansDebug.LogLevel.Default
remplace le niveau dansLogLevel.Default
. - Chaque alias de fournisseur par défaut est utilisé. Chaque fournisseur définit un alias qui peut être utilisé dans la configuration à la place du nom de type complet. Les alias de fournisseurs intégrés sont les suivants :
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();
Définir le niveau de journalisation à l’aide de la ligne de commande, de variables d’environnement et d’autres méthodes de configuration
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 :
- Pris en charge par toutes les plateformes.
- Remplacé automatiquement par deux-points
:
.
Les commandes suivantes permettent de :
- Définissez la clé d’environnement
Logging:LogLevel:Microsoft
sur la valeurInformation
dans Windows. - Testez les paramètres lorsque vous utilisez une application créée avec les modèles d’application web ASP.NET Core. La commande
dotnet run
doit être exécutée dans le répertoire du projet après l’utilisation deset
.
set Logging__LogLevel__Microsoft=Information
dotnet run
Le paramètre d’environnement précédent :
- Est uniquement défini dans les processus lancés à partir de la fenêtre de commande dans laquelle il a été défini.
- Ne sera pas lu par les navigateurs lancés avec Visual Studio.
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 :
- Chiffrés au rest et transmis sur un canal chiffré
- Exposés en tant que variables d’environnement
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 :
- Sélectionnez toutes les règles qui correspondent au fournisseur ou à son alias. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles avec un fournisseur vide.
- À partir du résultat de l’étape précédente, sélectionnez les règles ayant le plus long préfixe de catégorie correspondant. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.
- Si plusieurs règles sont sélectionnées, prenez la dernière.
- Si aucune règle n’est sélectionnée, utilisez
MinimumLevel
.
Les journaux créés à l’aide des fournisseurs de journalisation par défaut sont affichés :
- Dans Visual Studio
- Dans la fenêtre de sortie Débogage lors du débogage.
- Dans la fenêtre ASP.NET Core Web Server.
- Dans la fenêtre de console lorsque l’application est exécutée avec
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 :
- En production :
- La journalisation aux niveaux
Trace
,Debug
ouInformation
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, journaliserTrace
,Debug
ouInformation
messages de niveau vers un magasin de données à faible coût et à volume élevé. Envisagez de limiterTrace
,Debug
ouInformation
à des catégories spécifiques. - La journalisation aux niveaux allant de
Warning
àCritical
doivent produire moins de messages de journal.- Les coûts et les limites de stockage ne posent généralement pas problème.
- Peu de journaux permettent une plus grande flexibilité au niveau du choix du magasin de données.
- La journalisation aux niveaux
- Lors du développement :
- Réglez sur
Warning
. - Ajoutez
Trace
,Debug
ouInformation
messages lors de la résolution des problèmes. Pour limiter la sortie, définissezTrace
,Debug
ouInformation
uniquement pour les catégories en cours d’examen.
- Réglez sur
ASP.NET Core écrit des journaux pour les événements de framework. Par exemple, tenez compte de la sortie du journal pour :
- Une application Razor Pages créée avec les modèles ASP.NET Core.
- Journalisation définie sur
Logging:Console:LogLevel:Microsoft:Information
. - Navigation vers la page Privacy :
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 :
- Chaque entité de table Azure peut avoir des propriétés
ID
etRequestTime
. - Les tables avec des propriétés simplifient les requêtes qui sont exécutées sur des données journalisées. Par exemple, vous pouvez rechercher tous les journaux compris dans une plage
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 :
- Créée avec les modèles d’application web ASP.NET.
appsettings.json
etappsettings.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 :
- Est un type IDisposable retourné par la méthode BeginScope.
- Dure jusqu’à sa suppression.
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 parspeedscope
.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 deILogger
.2 Active l’événement Message
lors de l’appel deILogger.Log()
. Fournit les informations de façon programmatique (sans mise en forme).4 Active l’événement FormatMessage
lors de l’appel deILogger.Log()
. Fournit la version de chaîne mise en forme des informations.8 Active l’événement MessageJson
lors de l’appel deILogger.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 :
- Sont dans l’ordre inverse.
- Les constantes de chaîne ne sont pas toutes identiques.
Si aucune
FilterSpecs
n’est spécifiée, l’implémentation deEventSourceLogger
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 :
- Une application s’exécute et appelle
logger.LogDebug("12345")
. - L’ID de processus (PID) a été défini via
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 :
- Capture les messages de débogage.
- Ne s’applique pas aux
FilterSpecs
. - Spécifie le niveau 5 qui mappe la catégorie Débogage.
Prenez la commande suivante :
dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
La commande précédente :
- Ne capture pas les messages de débogage, car le niveau de catégorie 5 est
Critical
. - Fournit des
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éesFilterSpecs
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 :
- L’enregistreur d’événements source afin de produire des chaînes mises en forme (
4
) pour les erreurs (2
). - La journalisation
Microsoft.AspNetCore.Hosting
au niveau de journalisationInformational
(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 commandedotnet-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 :
- Trace de l’utilitaire d’analyse des performances (
dotnet-trace
) (documentation .NET Core) - Trace de l’utilitaire d’analyse des performances (
dotnet-trace
) (documentation du dépôt GitHub dotnet/diagnostics) - LoggingEventSource
- EventLevel
- Perfview : utile pour afficher les traces de source d’événements.
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.
- Journalisation des applications (système de fichiers)
- Journalisation des applications (objet blob)
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 :
- Serveur d'applications
- Serveur web
- Suivi des demandes ayant échoué
Pour configurer le streaming des journaux Azure :
- Accédez à la page Journaux App Service dans le portail de l’application.
- Définissez Journal des applications (Système de fichiers) sur Activé.
- Choisissez le niveau du journal. Ce paramètre s’applique uniquement au streaming de journaux Azure.
Accédez à la page Streaming des journaux pour afficher les journaux. Les messages journalisés le sont avec l’interface ILogger
.
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 :
- Vue d’ensemble d’Application Insights
- Application Insights pour les applications ASP.NET Core : commencez ici si vous souhaitez implémenter la gamme complète des données de télémétrie d’Application Insights en même temps que la journalisation.
- Journaux ApplicationInsightsLoggerProvider pour .NET Core ILogger : commencez ici si vous souhaitez implémenter le fournisseur de journalisation sans le rest des données de télémétrie Application Insights.
- Adaptateurs de journalisation Application Insights
- Tutoriel interactif Installer, configurer et initialiser le kit SDK Application Insights.
Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :
- elmah.io (dépôt GitHub)
- Gelf (Dépôt GitHub)
- JSNLog (dépôt GitHub)
- KissLog.net (référentiel GitHub)
- Log4Net (dépôt GitHub)
- NLog (dépôt GitHub)
- PLogger (dépôt GitHub)
- Sentry (dépôt GitHub)
- Serilog (dépôt GitHub)
- Stackdriver (Github repo)
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 :
- Ajoutez un package NuGet à votre projet.
- Appelez une méthode d’extension
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 :
- Les interfaces se trouvent dans
Microsoft.Extensions.Logging.Abstractions
. - Les implémentations par défaut se trouvent dans
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 :
- Le fournisseur de journalisation
Debug
. - Le niveau de journalisation
Information
et niveaux supérieurs. - Toutes les catégories commençant par
"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.
- Amélioration des performances de journalisation avec des générateurs sources
- Derrière
[LogProperties]
et le nouveau générateur de source de journalisation de télémétrie - Source Microsoft.Extensions.Logging sur GitHub
- Affichez ou téléchargez un exemple de code (procédure de téléchargement).
- Journalisation haute performance
- Les bogues de journalisation doivent être créés dans le dépôt GitHub
dotnet/runtime
. - Journalisation ASP.NET Core Blazor
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 :
- Utilisent l’hôte générique.
- Appelle CreateDefaultBuilder, qui ajoute les fournisseurs de journalisation suivants :
- Console
- Déboguer
- EventSource
- EventLog : Windows uniquement
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 :
- Appels à ClearProviders pour supprimer toutes les instances ILoggerProvider du générateur.
- Ajoute le fournisseur de journalisation Console.
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 :
- Crée un enregistreur d’événements (
ILogger<AboutModel>
) qui utilise une catégorie de journal pour le nom complet du typeAboutModel
. La catégorie du journal est une chaîne associée à chaque journal. - Appelle LogInformation pour journaliser au niveau
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 :
- Les catégories
"Default"
,"Microsoft"
et"Microsoft.Hosting.Lifetime"
sont spécifiées. - La catégorie
"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"
. - La catégorie
"Microsoft"
journalise au niveau de journalisationWarning
et aux niveaux supérieurs. - La catégorie
"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. - Aucun fournisseur de journaux n’est spécifié.
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 :
- Certains fournisseurs : par exemple,
Logging:EventSource:LogLevel:Default:Information
- Certaines catégories : par exemple,
Logging:LogLevel:Microsoft:Warning
- Tous les fournisseurs et toutes les catégories :
Logging:LogLevel:Default:Warning
Les journaux situés en dessous du niveau minimal ne seront pas :
- Passés au fournisseur.
- Journalisés ou affichés.
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 :
- Les catégories et les niveaux ne sont pas des valeurs suggérées. L’exemple est fourni pour afficher tous les fournisseurs par défaut.
- Les paramètres de
Logging.{providername}.LogLevel
remplacent les paramètres deLogging.LogLevel
. Par exemple, le niveau dansDebug.LogLevel.Default
remplace le niveau dansLogLevel.Default
. - Chaque alias de fournisseur par défaut est utilisé. Chaque fournisseur définit un alias qui peut être utilisé dans la configuration à la place du nom de type complet. Les alias de fournisseurs intégrés sont les suivants :
- Console
- Déboguer
- EventSource
- EventLog
- AzureAppServicesFile
- AzureAppServicesBlob
- ApplicationInsights
Définir le niveau de journalisation à l’aide de la ligne de commande, de variables d’environnement et d’autres méthodes de configuration
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 :
- Pris en charge par toutes les plateformes.
- Remplacé automatiquement par deux-points
:
.
Les commandes suivantes permettent de :
- Définissez la clé d’environnement
Logging:LogLevel:Microsoft
sur la valeurInformation
dans Windows. - Testez les paramètres lorsque vous utilisez une application créée avec les modèles d’application web ASP.NET Core. La commande
dotnet run
doit être exécutée dans le répertoire du projet après l’utilisation deset
.
set Logging__LogLevel__Microsoft=Information
dotnet run
Le paramètre d’environnement précédent :
- Est uniquement défini dans les processus lancés à partir de la fenêtre de commande dans laquelle il a été défini.
- Ne sera pas lu par les navigateurs lancés avec Visual Studio.
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 :
- Chiffrés au rest et transmis sur un canal chiffré
- Exposés en tant que variables d’environnement
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 :
- Sélectionnez toutes les règles qui correspondent au fournisseur ou à son alias. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles avec un fournisseur vide.
- À partir du résultat de l’étape précédente, sélectionnez les règles ayant le plus long préfixe de catégorie correspondant. Si aucune correspondance n’est trouvée, sélectionnez toutes les règles qui ne spécifient pas de catégorie.
- Si plusieurs règles sont sélectionnées, prenez la dernière.
- Si aucune règle n’est sélectionnée, utilisez
MinimumLevel
.
Les journaux créés à l’aide des fournisseurs de journalisation par défaut sont affichés :
- Dans Visual Studio
- Dans la fenêtre de sortie Débogage lors du débogage.
- Dans la fenêtre ASP.NET Core Web Server.
- Dans la fenêtre de console lorsque l’application est exécutée avec
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 :
- En production :
- La journalisation aux niveaux
Trace
ouInformation
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 niveauTrace
etInformation
dans un magasin de données à haut volume et à faible coût. Il est conseillé de limiterTrace
etInformation
à certaines catégories. - La journalisation aux niveaux allant de
Warning
àCritical
doivent produire moins de messages de journal.- Les coûts et les limites de stockage ne posent généralement pas problème.
- Peu de journaux permettent une plus grande flexibilité au niveau du choix du magasin de données.
- La journalisation aux niveaux
- Lors du développement :
- Réglez sur
Warning
. - Ajoutez les messages
Trace
ouInformation
lorsque vous résolvez des problèmes. Pour limiter la sortie, définissezTrace
ouInformation
uniquement pour les catégories en cours d’investigation.
- Réglez sur
ASP.NET Core écrit des journaux pour les événements de framework. Par exemple, tenez compte de la sortie du journal pour :
- Une application Razor Pages créée avec les modèles ASP.NET Core.
- Journalisation définie sur
Logging:Console:LogLevel:Microsoft:Information
- Navigation vers la page Privacy :
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 :
- Chaque entité de table Azure peut avoir des propriétés
ID
etRequestTime
. - Les tables avec des propriétés simplifient les requêtes qui sont exécutées sur des données journalisées. Par exemple, vous pouvez rechercher tous les journaux compris dans une plage
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 :
- Créée avec les modèles d’application web ASP.NET.
appsettings.json
etappsettings.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 :
- Est un type IDisposable retourné par la méthode BeginScope.
- Dure jusqu’à sa suppression.
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.
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 parspeedscope
.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 deILogger
.2 Active l’événement Message
lors de l’appel deILogger.Log()
. Fournit les informations de façon programmatique (sans mise en forme).4 Active l’événement FormatMessage
lors de l’appel deILogger.Log()
. Fournit la version de chaîne mise en forme des informations.8 Active l’événement MessageJson
lors de l’appel deILogger.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 :
- Sont dans l’ordre inverse.
- Les constantes de chaîne ne sont pas toutes identiques.
Si aucune
FilterSpecs
n’est spécifiée, l’implémentation deEventSourceLogger
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 :
- Une application s’exécute et appelle
logger.LogDebug("12345")
. - L’ID de processus (PID) a été défini via
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 :
- Capture les messages de débogage.
- Ne s’applique pas aux
FilterSpecs
. - Spécifie le niveau 5 qui mappe la catégorie Débogage.
Prenez la commande suivante :
dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
La commande précédente :
- Ne capture pas les messages de débogage, car le niveau de catégorie 5 est
Critical
. - Fournit des
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éesFilterSpecs
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 :
- L’enregistreur d’événements source afin de produire des chaînes mises en forme (
4
) pour les erreurs (2
). - La journalisation
Microsoft.AspNetCore.Hosting
au niveau de journalisationInformational
(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 :
- Trace de l’utilitaire d’analyse des performances (dotnet-trace) (documentation .NET Core)
- Trace de l’utilitaire d’analyse des performances (dotnet-trace) (documentation du dépôt GitHub dotnet/diagnostics)
- Classe LoggingEventSource (navigateur d’API .NET)
- EventLevel
- Source de référence LoggingEventSource (3.0) : si vous souhaitez obtenir une source de référence pour une autre version, définissez la branche sur
release/{Version}
, où{Version}
correspond à la version d’ASP.NET Core souhaitée. - Perfview : utile pour afficher les traces de source d’événements.
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.
- Journalisation des applications (système de fichiers)
- Journalisation des applications (objet blob)
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 :
- Serveur d'applications
- Serveur web
- Suivi des demandes ayant échoué
Pour configurer le streaming des journaux Azure :
- Accédez à la page Journaux App Service dans le portail de l’application.
- Définissez Journal des applications (Système de fichiers) sur Activé.
- Choisissez le niveau du journal. Ce paramètre s’applique uniquement au streaming de journaux Azure.
Accédez à la page Streaming des journaux pour afficher les journaux. Les messages journalisés le sont avec l’interface ILogger
.
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 :
- Vue d’ensemble d’Application Insights
- Application Insights pour les applications ASP.NET Core : commencez ici si vous souhaitez implémenter la gamme complète des données de télémétrie d’Application Insights en même temps que la journalisation.
- Journaux ApplicationInsightsLoggerProvider pour .NET Core ILogger : commencez ici si vous souhaitez implémenter le fournisseur de journalisation sans le rest des données de Application Insights Telemetry.
- Adaptateurs de journalisation Application Insights.
- Tutoriel interactif Installer, configurer et initialiser le kit SDK Application Insights.
Frameworks de journalisation tiers qui sont pris en charge dans ASP.NET Core :
- elmah.io (dépôt GitHub)
- Gelf (Dépôt GitHub)
- JSNLog (dépôt GitHub)
- KissLog.net (référentiel GitHub)
- Log4Net (dépôt GitHub)
- NLog (dépôt GitHub)
- PLogger (dépôt GitHub)
- Sentry (dépôt GitHub)
- Serilog (dépôt GitHub)
- Stackdriver (Github repo)
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 :
- Ajoutez un package NuGet à votre projet.
- Appelez une méthode d’extension
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 :
- L’injection d’un enregistreur d’événements dans le constructeur
Startup
n’est pas prise en charge. - L’injection d’un enregistreur d’événements dans la signature de méthode
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 :
- Les interfaces se trouvent dans Microsoft.Extensions.Logging.Abstractions.
- Les implémentations par défaut se trouvent dans 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 :
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 :
- Le fournisseur de journalisation
Debug
. - Le niveau de journalisation
Information
et niveaux supérieurs. - Toutes les catégories commençant par
"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.
- Journalisation haute performance
- Les bogues de journalisation doivent être créés dans le dépôt github.com/dotnet/runtime/.
- Journalisation ASP.NET Core Blazor
Commentaires sur ASP.NET Core
ASP.NET Core est un projet open source. Sélectionnez un lien pour fournir des commentaires :