Serilog dans ASP.NET Core 3.1-La journalisation structurée simplifiée

Quand j’ai découvert Serilog, il n’y avait pas de guides/tutoriels appropriés pour implémenter la même chose dans mes applications. Pour une bibliothèque aussi géniale que Serilog, il est dommage de ne pas avoir de guide détaillé bien documenté pour les développeurs (la documentation Serilog est excellente, mais je pense que cela peut être exagéré pour beaucoup). C’est la principale raison pour laquelle j’écris cet article / guide détaillé. A la fin de cet article, je vous assure que vous aurez une connaissance quasi complète de Serilog. Voici les sujets que je vais abord

Table des matières

Qu’est-ce que Serilog ?

Serilog est une bibliothèque de journalisation tierce qui se connecte à l’ILogger par défaut de notre application avec ses propres implémentations. Il permet aux développeurs de consigner les événements dans diverses destinations telles que la console, le fichier, la base de données, etc. Désormais, si vous utilisez déjà une base de données dans votre application ASP.NET Core, la journalisation des événements dans une base de données peut être une bonne option. Serilog prend en charge la journalisation structurée, ce qui permet d’enregistrer plus de détails et d’informations sur l’événement. Avec une journalisation structurée en place, vous pouvez utiliser ces journaux pour déboguer de manière très logique.

Configuration du projet ASP.NET Core 3.1

Pour cette démonstration, implémentons Serilog sur une application Web ASP.NET Core 3.1 (Razor Pages). Étant donné que nous nous concentrons sur la journalisation et la compréhension de divers concepts connexes, nous garderons la configuration du projet simple et directe. J’utiliserai Visual Studio 2019 Community comme IDE.

Journalisation avec le journal par défaut

Comme je l’ai mentionné précédemment, les applications ASP.NET Core sont livrées avec un système de journalisation intégré par défaut qui inclut certaines fonctions de journalisation de base. Pour comprendre la journalisation, voyons comment fonctionne l’enregistreur de base. Une fois que vous avez créé votre solution WebApplication, accédez à Pages / Index.cshtml / Index.cshtml.cs. Vous pouvez voir l’injection de l’entrepreneur de l’interface ILogger. Il s’agit de l’enregistreur par défaut de Microsoft.

Dans la méthode OnGet du IndexModel, ajoutons un moyen de démontrer la connexion et utilisons également le bloc try-catch . Ici, je vais lancer une exception factice afin que nous puissions mieux comprendre la journalisation. Notez également que nous ne changerons rien sur la classe plus loin dans cette démonstration.

public void OnGet()
{
  _logger.LogInformation("Requested the Index Page");
  int count;
  try {
    for (count = 0; count <= 5; count++) {
      if (count == 3) {
        throw new Exception("RandomException");
      }
    }
  } 
  catch (Exception ex) {
    _logger.LogError(ex, "Exception Caught");
  }
}
}

La méthode OnGet est déclenchée chaque fois que vous demandez la page d’index (page d’accueil). Ainsi, comme le suggère le code, j’enregistre un message indiquant « Demandé la page d’index » chaque fois que vous demandez cette page. Après cela, il exécute une boucle 5 fois, et si le nombre d’itérations est de 3, il lève une exception factice « RandomException » qui à son tour est capturée dans le bloc catch. Ceci est consigné comme une erreur. De cette façon, nous avons une fonction qui imite une fonction pratique au niveau de la production.

Avant de tester la journalisation, passons au serveur Web Kestrel depuis IIS Express sur Visual Studio.

Qu’est-ce que le serveur Web Kestrel ?

Kestrel est un serveur Web open source fourni par défaut avec les applications ASP.NET Core. Nous avons spécifiquement besoin du serveur Kestrel pour cette démonstration car il ouvre une console qui contient tous les événements enregistrés.

Comment passer au serveur Web Kestrel ?

Par défaut, vous pouvez avoir IIS Express comme serveur sélectionné. Vous pouvez basculer vers Kestrel Web Server en cliquant sur l’icône déroulante à côté d’IIS Express et en choisissant l’option avec le nom de votre application. Dans notre cas, il s’agit de Serilog.WebApplication. Je vais le choisir et exécuter l’application en utilisant Control + F5 (je démarre l’application sans déboguer pour gagner du temps ici).

Lorsque vous exécutez votre application, une console s’ouvre avec votre application Web. Dans cette console, vous voyez certains journaux de l’application. À la fin, nous voyons nos messages de journal personnalisés et nos exceptions (j’ai surligné nos messages concernés en jaune). Essayez d’actualiser la page sur votre navigateur Web, vous verrez un autre ensemble de messages similaires sur la console. Il s’agit de la journalisation par défaut fournie avec votre application.

Niveaux de journalisation

Je voulais également que vous connaissiez les différents niveaux de journalisation. C’est le concept fondamental de la journalisation. Lorsque nous avons écrit ‘_logger.LogInformation(« Requested the Index Page »);’, nous avons mentionné à l’application qu’il s’agit d’un journal avec le niveau de journal défini sur Information. Les niveaux de journal ont du sens car ils vous permettent de définir le type de journal. Est-ce un journal critique ? juste un message de débogage ? un message d’avertissement?

Il y a 7 niveaux de log inclus :

• Trace – Messages détaillés avec des données d’application sensibles.
• Debug – Utile pour l’environnement de développement.
• Information – Messages généraux, comme nous l’avons mentionné plus tôt.
• Avertissement – ​​Pour les événements inattendus.
• Erreur – Pour les exceptions et les erreurs.
• Critique – Pour les pannes qui peuvent nécessiter une attention immédiate.

Paramètres de journalisation par défaut

Les paramètres par défaut de notre enregistreur sont mentionnés dans appsettings.json. Ces paramètres vous permettent de définir à quel niveau de journaux vous avez besoin d’un composant particulier. Par exemple, tous les messages de journal générés par l’application (Microsoft) avec les niveaux Avertissement et supérieurs sont consignés dans la console. C’est l’idée de base des paramètres de journalisation.

"Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }

Cela dit, commençons l’implémentation réelle de Serilog dans notre application ASP.NET Core.

Enrichisseurs Serilog

Pour activer la journalisation structurée et libérer tout le potentiel de Serilog, nous utilisons des enrichisseurs. Ces enrichisseurs vous donnent des détails supplémentaires tels que le nom de la machine, le ProcessId, le Thread Id lorsque l’événement de journal s’est produit pour de meilleurs diagnostics. Cela simplifie la vie d’un développeur. Nous utiliserons les enrichisseurs plus loin dans ce guide.

Sinks Serilog

Les ‘Sinks’ Serilog, en termes plus simples, se rapportent aux destinations d’enregistrement des données. Dans les packages que nous allons installer sur notre application ASP.NET Core, les récepteurs pour la console et le fichier sont inclus par défaut. Cela signifie que nous pouvons écrire des journaux sur la console et le système de fichiers sans ajouter de packages supplémentaires. Serilog prend en charge diverses autres destinations telles que MSSQL, SQLite, SEQ et plus encore.

Implémentation de Serilog dans ASP.NET Core 3.1

Commençons à implémenter Serilog dans notre application ASP.NET Core 3.1 et faisons-en l’enregistreur par défaut à l’échelle de l’application. Voici un guide rapide étape par étape sur l’utilisation de Serilog dans les applications ASP.NET Core.

Installation des packages requis

Pour l’instant, ce sont les packages dont vous avez besoin. Installez-les via le gestionnaire de packages NuGet ou la console.

Install-Package Serilog.AspNetCore
Install-Package Serilog.Settings.Configuration
Install-Package Serilog.Enrichers.Environment
Install-Package Serilog.Enrichers.Process
Install-Package Serilog.Enrichers.Thread

Le package #1 contient les composants de base de Serilog. Il s’agit d’une version ASP.NET Core du package qui comprend des fonctionnalités supplémentaires pour notre application.
Le package #2 permet à Serilog de lire les paramètres de notre fichier de configuration, c’est-à-dire appsettings.json.
Les packages #3,4,5 sont les enrichisseurs qui obtiennent des détails sur l’environnement, le processus, le thread, etc.

Maintenant que nous avons installé tous les packages Serilog nécessaires, allons-y et configurons Serilog.

Configuration de Serilog dans les applications ASP.NET Core

Notre intention est d’utiliser Serilog au lieu de l’enregistreur par défaut. Pour cela, nous devrons configurer Serilog au point d’entrée de notre application ASP.NET Core, c’est-à-dire le fichier Program.cs. Accédez à Program.cs et apportez les modifications suivantes.

public static void Main(string[] args) 
{
  // Read Configuration from appSettings
  var config =
      new ConfigurationBuilder().AddJsonFile("appsettings.json").Build();
  // Initialize Logger
  Log.Logger =
      new LoggerConfiguration().ReadFrom.Configuration(config).CreateLogger();
  try {
    Log.Information("Application Starting.");
    CreateHostBuilder(args).Build().Run();
  } 
catch (Exception ex) {
    Log.Fatal(ex, "The Application failed to start.");
  } 
finally {
    Log.CloseAndFlush();
  }
}

Explication.
La ligne #4,5,6 lit un fichier de configuration (appsettings.json) et récupère l’objet Configuration pour une utilisation ultérieure.
Ligne #9,10,11 Initialise le Serilog à l’aide des paramètres de appsettings.json
La ligne #23 permet à l’enregistreur de consigner tous les messages en attente pendant la fermeture de l’application.

 public static IHostBuilder CreateHostBuilder ( chaîne [] args ) = > 
            Héberger. CreateDefaultBuilder ( args )
                . UseSerilog () // Utilise Serilog au lieu du .NET Logger par défaut 
                . ConfigureWebHostDefaults ( webBuilder = >
                {
                    WebBuilder. UseStartup < Démarrage >() ;
                }) ;

La ligne 3 oblige l’application à utiliser Serilog au lieu de l’enregistreur par défaut.

REMARQUE – Il est important de noter que, dans ce didacticiel, je vous montre une manière plus propre d’implémenter Serilog. Il existe des possibilités pour définir la configuration Serilog en code (C#). Mais le problème est que vous ne pouvez pas modifier ces paramètres lors de l’exécution. Il est donc préférable de définir ces paramètres dans appsettings.json.

Maintenant que notre application est configurée pour prendre en charge Serilog en tant qu’enregistreur par défaut, définissons les paramètres Serilog dans notre appsettings.json.

Mise en place de Serilog

Accédez à appsettings.json et supprimez les paramètres de journalisation par défaut et remplacez-les par ce qui suit.

{
  "AllowedHosts": "*",
  "Serilog": 
  {
    "Using": [],
    "MinimumLevel": {
      "Default": "Information",
      "Override": 
      {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "Console"
      },
      {
        "Name": "File",
        "Args": {
          "path": "D:\\Logs\\log.txt",
          "outputTemplate": "{Timestamp} {Message}{NewLine:1}{Exception:1}"
        }
      }
    ],
    "Enrich": [
      "FromLogContext",
      "WithMachineName",
      "WithProcessId",
      "WithThreadId"
    ],
    "Properties": {
      "ApplicationName": "Serilog.WebApplication"
    }
  }
}

Explication.
Il s’agit des paramètres de Serilog définis dans appsettings.Json. Comme je l’avais mentionné plus tôt, à partir de maintenant, nous ne modifierons que les paramètres ici et ne toucherons pas au code C#.

La ligne 3 marque le début des paramètres Serilog.
Les lignes #6 à #13 définissent le niveau minimum de journalisation pour divers composants et par défaut. Vous pouvez voir que par défaut, nous enregistrons tous les niveaux au-dessus du niveau de journalisation des informations. Mais pour des composants spécifiques comme Microsoft, nous devons nous connecter uniquement pour les niveaux d’avertissement et supérieurs, afin que nous n’ayons pas un billion de lignes de journal dans nos récepteurs.

Les lignes 14 à 25 marquent les paramètres du récepteur Serilog. Pour l’instant, nous avons écrit les paramètres pour les récepteurs de fichiers et de console uniquement. Nous allons l’étendre plus loin dans ce guide.
La ligne #22 est l’endroit où vous pouvez définir le modèle de la sortie du journal.
Les lignes 26 à 31 définissent les enrichisseurs pour Serilog afin de fournir plus de détails.
Les lignes 32 à 34 permettent de définir des propriétés personnalisées qui apparaîtront dans nos données de journal structurées.

J’espère que cette partie est claire. Avançons et exécutons l’application. Assurez-vous que Kestrel est votre serveur Web par défaut.

Connexion à la console avec Serilog.

Nous n’avons pas besoin de modifications supplémentaires pour nous connecter à la console. Vous pouvez voir que notre journal est maintenant beaucoup plus propre et précis.

Connexion au fichier avec Serilog.

Maintenant, vérifions le dossier que nous avions défini précédemment. Nous pouvons voir un nouveau fichier log.txt créé par Serilog.

Ok, nous avons tellement parlé de la journalisation structurée et des enrichisseurs. Mais où sont-ils ? Les récepteurs de console et de fichier (fichiers texte) ne prennent pas en charge la journalisation structurée. Passons au schéma suivant pour obtenir une journalisation structurée.

Journalisation structurée avec Serilog.

Pour activer la journalisation structurée avec le récepteur de fichiers, nous devons ajouter un formateur JSON en tant que paramètre aux paramètres.Modifiant notre appSettings.json/Serilog. Ajoutez le code ci-dessous.

{
        "Name": "File",
        "Args": {
          "path": "D:\\Logs\\structuredLog.json",
          "formatter": "Serilog.Formatting.Json.JsonFormatter, Serilog"
        }
 }

Ligne #2 spécifier que le type de journalisation est un fichier.
La ligne #4 définit le chemin du fichier JSON.
La ligne #5 place le formateur JSON de Serilog pour permettre la journalisation structurée.

Maintenant, relancez simplement l’application. Accédez au chemin défini, vous verrez un nouveau fichier JSON. Ouvrez ce fichier avec un éditeur de code capable de formater les JSON, afin de faciliter la lecture des données. J’ai utilisé Visual Studio Code pour ouvrir le fichier journal. Voici une capture d’écran du journal.

Il s’agit du journal structuré d’un événement de journal unique, l’événement d’erreur. Vous pouvez voir la quantité de données qui nous sont fournies par Serilog. Notez également que nous avons le nom de la machine, le ProcessId et de nombreux détails qui peuvent aider à déboguer l’application à plus long terme. Notre propriété personnalisée, ApplicationName apparaît également dans notre fichier journal. Assez cool, ouais?

Connexion à la base de données avec Serilog.

Maintenant, c’est ce que vous voudriez probablement utiliser pour les applications dans l’environnement de production. Il est beaucoup plus logique de se connecter à une base de données relationnelle, de sorte que, ultérieurement, vous puissiez utiliser certaines requêtes pour récupérer intelligemment les détails du journal par AppliationName, LogLevel, etc.

Dans ce didacticiel, je vais vous montrer comment vous connecter à la base de données Microsoft SQL Server. Pour cela, nous devons installer un package supplémentaire (un nouveau Sink !). Il est également possible de se connecter à plusieurs bases de données (vous devrez installer le package Serilog Sink spécifique).

Install-Package Serilog.Sinks.MSSqlServer

{
        "Nom" : "MSSqlServer" ,
        "Args" : {
          "connectionString" : "<votre chaîne de connexion / connexion nommée ici>" ,
          "sinkOptionsSection" : {
            "tableName" : "Journaux" ,
            "schemaName" : "EventLogging" ,
            "autoCreateSqlTable" : vrai
          } ,
          "restrictedToMinimumLevel" : "Attention"
        }
      }

La ligne #2 a défini le récepteur comme MSSQLServer Sink.
La ligne #4 est l’endroit où vous voudriez mettre la chaîne de connexion / chaîne de connexion nommée pour les journaux à insérer.
Ligne #6 le nom de la table.
Ligne #7 le nom du schéma.
La ligne #8 est une fonctionnalité intéressante où Serilog crée la table pour vous si elle n’existe pas.
La ligne #10 limite le niveau de niveau de journalisation minimum. Nous ne voulons pas tout enregistrer dans la base de données pendant la production. Seuls les erreurs et les journaux fatals suffisent.

Laissez-moi lancer l’application. Cela peut prendre quelques secondes de plus que d’habitude car Serilog configure votre base de données en arrière-plan. Après l’exécution de l’application. Ouvrez SQL Management Studio et vérifiez la base de données mentionnée dans votre chaîne de connexion. Vous trouverez une nouvelle table « Eventlogging.Logs ». C’est celui créé par Serilog. Exécutez une commande Select * sur cette table.

Notez que notre récepteur MSSqlServer n’enregistre que les événements hautement prioritaires, c’est-à-dire les erreurs/exceptions/fatales. Cela peut également être réglé pour n’importe quel évier en fonction de vos besoins.

Super! Nous avons maintenant appris une manière propre d’implémenter Serilog / Logging dans votre application ASP.NET Core.

Sommaire

Dans cet article, nous avons abordé les bases de la journalisation, le comportement de l’enregistreur .NET par défaut, divers concepts de journalisation, la bibliothèque Serilog et son implémentation, ainsi que les différents récepteurs Serilog. Laissez derrière vous vos questions, suggestions dans la section des commentaires ci-dessous. De plus, si vous pensez avoir appris quelque chose de nouveau grâce à cet article, n’oubliez pas de le partager au sein de votre communauté de développeurs. Bon codage !

Derniers articles

• Hangfire avec ASP.NET Core
• Premiers pas avec AutoMapper dans ASP.NET Core
• Serilog dans ASP.NET Core 3.1-La journalisation structurée simplifiée