Journal d'écriture des événements
Les événements de journal sont écrits dans les récepteurs à l'aide de la classe statique Log ou des méthodes d'un ILogger. Ces exemples utiliseront Log pour des raisons de concision syntaxique, mais les mêmes méthodes présentées ci-dessous sont également disponibles sur l'interface.
- Log.Warning("Quota de disque {Quota} Mo dépassé par {User}", quota, user);
L'événement d'avertissement créé à partir de cette méthode de journal aura deux propriétés associées, Quota et User. En supposant que quota est un entier et user une chaîne de caractères, le message affiché peut ressembler à celui ci-dessous :
Quota de disque 1024 Mo dépassé par "smaltais"(Serilog affiche les valeurs de chaîne de caractères entre guillemets pour indiquer de manière plus transparente le type de données sous-jacent et pour faire ressortir la valeur de la propriété du texte du message environnant.)
Syntaxe du gabarit de message
La chaîne de caractères au-dessus de «Quota de disque {Quota} dépassé par {User}» est un gabarit de message Serilog. Les modèles de message sont un sur-ensemble de chaînes de caractères de format .NET standard, donc toute chaîne de caractères de format acceptable pour string.Format() sera également correctement traitée par Serilog :
- Les noms de propriété sont écrits entre crochets { et }
- Les noms de propriété doivent être des identificateurs C# valides, par exemple FooBar, mais pas Foo.Bar ou Foo-Bar
- Les crochets peuvent être échappés en les doublant, par exemple {{ sera rendu comme {
- Les formats utilisant des noms de propriété numériques, comme {0} et {1} exclusivement, seront mis en correspondance avec les paramètres de la méthode log en traitant les noms de propriété comme des index; ceci est identique au comportement de string.Format().
- Si l'un des noms de propriété n'est pas numérique, tous les noms de propriété seront mis en correspondance de gauche à droite avec les paramètres de la méthode log
- Les noms de propriété peuvent être préfixés par un opérateur facultatif, @ ou $, pour contrôler la manière dont la propriété est sérialisée.
- Les noms de propriété peuvent être suffixés par un format facultatif, par exemple :000, pour contrôler la manière dont la propriété est rendue ; ces chaînes de caractères de format se comportent exactement comme leurs homologues dans la syntaxe string.Format()
Recommandations de gabarits de messages
Règles de style fluides : les bons événements Serilog utilisent les noms des propriétés comme contenu dans le message, comme dans l'exemple d'utilisateur ci-dessus. Cela améliore la lisibilité et rend les événements plus compacts.
Phrases vs. Fragments : les messages d'événements de journal sont des fragments, pas des phrases ; pour plus de cohérence avec d'autres bibliothèques utilisant Serilog, évitez un point final/un point final lorsque cela est possible.
Gabarits vs. Messages : les événements Serilog ont un gabarit de message associé, pas un message. En interne, Serilog analyse et met en cache chaque modèle (jusqu'à une limite de taille fixe). Traiter le paramètre de chaîne des méthodes de journal comme un message, comme dans le cas ci-dessous, dégradera les performances et consommera de la mémoire cache.
- // Ne le faites pas:
- Log.Information("L'heure est " + DateTime.Now);
Utilisez plutôt toujours les propriétés du gabarit pour inclure des variables dans les messages :
- // Faire:
- Log.Information("L'heure est {Now}", DateTime.Now);
Nommage des propriétés - Les noms de propriétés doivent utiliser PascalCase pour assurer la cohérence avec les autres codes et bibliothèques de l'écosystème Serilog.
La syntaxe du modèle de message est spécifiée sur messagetemplates.org.
Niveaux des événements du journal
Serilog utilise les niveaux comme principal moyen d'attribuer de l'importance aux événements du journal. Les niveaux, classés par ordre croissant d'importance, sont les suivants :
| Niveau | Description |
|---|---|
| Verbose | Traçage des informations et débogage des détails ; généralement activé uniquement dans des situations inhabituelles. |
| Debug | Flux de contrôle interne et vidages d'état de diagnostic pour faciliter l'identification des problèmes reconnus. |
| Information | Événements intéressants ou pertinents pour les observateurs extérieurs ; niveau de journalisation minimum activé par défaut. |
| Warning | Indicateurs de problèmes possibles ou de dégradation du service/des fonctionnalités. |
| Error | Indiquer une défaillance au sein de l'application ou du système connecté. |
| Fatal | Erreurs critiques provoquant l'échec complet de l'application |
Le rôle du niveau Information
Le niveau Information est différent des autres niveaux spécifiés : il n'a pas de sémantique spécifiée et exprime à bien des égards l'absence d'autres niveaux.
Étant donné que Serilog permet de traiter ou d'analyser le flux d'événements de l'application, le niveau Information peut être considéré comme un synonyme d'événement. Autrement dit, la plupart des données d'événements d'application intéressantes doivent être enregistrées à ce niveau.
Détection de niveau
Dans la plupart des cas, les applications doivent écrire des événements sans vérifier le niveau de journalisation actif. La vérification de niveau est extrêmement peu coûteuse et la surcharge liée à l'appel de méthodes de journalisation désactivées est très faible.
Dans les cas rares et sensibles aux performances, le modèle recommandé pour la détection de niveau consiste à stocker les résultats de la détection de niveau dans un champ, par exemple :
- readonly bool _isDebug = Log.IsEnabled(LogEventLevel.Debug);
Le champ _isDebug peut être vérifié efficacement avant d'écrire les événements du journal :
- if (_isDebug) Log.Debug("Quelqu'un est bloqué en train de déboguer...");
Niveaux dynamiques
De nombreuses applications plus grandes/distribuées doivent s'exécuter à un niveau de journalisation assez restreint, par exemple, Information (ma préférence) ou Warning, et n'activer l'instrumentation sur Debug ou Verbose que lorsqu'un problème a été détecté et que la surcharge liée à la collecte d'un peu plus de données est justifiée.
Si une application a besoin d'un changement de niveau dynamique, la première étape consiste à créer une instance de LoggingLevelSwitch lors de la configuration du journal de bord :
- var levelSwitch=new LoggingLevelSwitch();
Cet objet définit par défaut le niveau minimum actuel sur Information. Pour rendre la journalisation plus restreinte, définissez donc son niveau minimum à l'avance :
- levelSwitch.MinimumLevel=LogEventLevel.Warning;
Lors de la configuration de l'enregistreur, fournissez le commutateur à l'aide de MinimumLevel.ControlledBy() :
- var log = new LoggerConfiguration()
- .MinimumLevel.ControlledBy(levelSwitch)
- .WriteTo.ColoredConsole()
- .CreateLogger();
Désormais, les événements écrits dans le journal seront filtrés en fonction de la propriété MinimumLevel du commutateur.
Pour augmenter ou diminuer le niveau au moment de l'exécution, peut-être en réponse à une commande envoyée sur le réseau, modifiez la propriété :
- levelSwitch.MinimumLevel = LogEventLevel.Verbose;
- log.Verbose("Cela sera désormais enregistré");
Contextes sources
Serilog, comme la plupart des cadres d'applications de journalisation .NET, permet d'étiqueter les événements avec leur source, généralement le nom de la classe les écrivant :
- var myLog = Log.ForContext<MyClass>();
- myLog.Information("Bonjour!");
L'événement écrit inclura une propriété SourceContext avec la valeur «MyNamespace.MyClass» pouvant être utilisée ultérieurement pour filtrer les événements bruyants ou les écrire de manière sélective dans des récepteurs particuliers.
Toutes les propriétés attachées à un événement n'ont pas besoin d'être représentées dans le modèle de message ou le format de sortie; toutes les propriétés sont transportées dans un dictionnaire sur l'objet LogEvent sous-jacent.
Corrélation
Tout comme ForContext<T>() balise les événements de journal avec la classe les ayant écrits, d'autres surcharges de ForContext() permettent de baliser les événements de journal avec des identificateurs prenant en charge ultérieurement la corrélation des événements écrits avec cet identificateur.
- var job = GetNextJob();
- var jobLog = Log.ForContext("JobId", job.Id);
- jobLog.Information("Exécution d'un nouveau travail");
- job.Run();
- jobLog.Information("Fini");
Ici, les deux événements de journal porteront la propriété JobId, y compris l'identifiant de la tâche.
Astuce : lors de la journalisation vers des récepteurs utilisant un format texte, comme Serilog.Sinks.Console, vous pouvez inclure {Properties} dans le modèle de sortie pour afficher toutes les propriétés contextuelles qui ne sont pas incluses autrement.