Notions de base sur la configuration
Le Serilog utilise une API en C# simple pour configurer la journalisation. Lorsqu'une configuration externe est souhaitable, elle peut être intégrée (avec parcimonie) à l'aide du paquet Serilog.Settings.AppSettings ou du paquet Serilog.Settings.Configuration.
Création d'un journal de bord
Les journal de bord sont créés à l'aide d'un objet LoggerConfiguration :
- Log.Logger = new LoggerConfiguration().CreateLogger();
- Log.Information("Personne ne m'écoute !");
-
- // Enfin, une fois juste avant la sortie de l'application...
- Log.CloseAndFlush();
L'exemple ci-dessus va créer un journal de bord n'enregistrant aucun événement nulle part. Pour voir les événements du journal, un récepteur doit être configuré.
Sinks
Les récepteurs (Sinks) d'événements de journal enregistrent généralement les événements de journal dans une représentation externe, généralement la console, un fichier ou un magasin de données. Les récepteurs Serilog sont distribués via NuGet.
Cet exemple utilisera le paquet de récepteur de console, affichant joliment les données de journal, et le paquet de récepteur de fichier, écrivant les événements de journal dans un ensemble de fichiers texte horodatés :
|
dotnet add package Serilog.Sinks.Console dotnet add package Serilog.Sinks.File |
Les récepteurs sont configurés à l'aide de l'objet de configuration WriteTo.
- Log.Logger = new LoggerConfiguration()
- .WriteTo.Console()
- .CreateLogger();
-
- Log.Information("Ah, vous voilà !");
Plusieurs récepteurs peuvent être actifs en même temps. L'ajout de récepteurs supplémentaires est aussi simple que l'enchaînement de blocs WriteTo :
- Log.Logger = new LoggerConfiguration()
- .WriteTo.Console()
- .WriteTo.File("log-.txt", rollingInterval: RollingInterval.Day)
- .CreateLogger();
Gabarits de sortie
Les récepteurs basés sur du texte utilisent des modèles de sortie pour contrôler le formatage. Cela peut être modifié via le paramètre outputTemplate :
- .WriteTo.File("log.txt",
- outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}
Le gabarit par défaut, illustré dans l'exemple ci-dessus, utilise des propriétés intégrées telles que Timestamp et Level. Les propriétés des événements, y compris celles attachées à l'aide d'enrichisseurs, peuvent également apparaître dans le gabarit de sortie.
Les options de format {Message:lj} entraînent la sortie des données intégrées dans le message au format JSON (j), à l'exception des littéraux de chaîne de caractères, étant sortis tels quels.
Pour des noms de niveau plus compacts, utilisez un format tel que {Level:u3} ou {Level:w3} pour les noms de niveau à trois caractères majuscules ou minuscules, respectivement.
Ajoutez {Properties:j} au modèle de sortie pour inclure des informations contextuelles supplémentaires.
Niveau minimum
Serilog implémente le concept commun de «niveau minimum» pour le traitement des événements de journal :
- Log.Logger = new LoggerConfiguration()
- .MinimumLevel.Debug()
- .WriteTo.Console()
- .CreateLogger();
L'objet de configuration MinimumLevel permet de spécifier l'un des niveaux d'événements de journal comme minimum. Dans l'exemple ci-dessus, les événements de journal avec le niveau Debug et supérieur seront traités et finalement écrits sur la console.
| Niveau | Utilisation |
|---|---|
| Verbose | Verbose est le niveau le plus détaillé, rarement (voire jamais) activé pour une application de production. |
| Debug | Le débogage est utilisé pour les événements système internes qui ne sont pas nécessairement observables de l'extérieur, mais utiles pour déterminer comment quelque chose s'est produit. |
| Information | Les événements d'information décrivent les événements se produisant dans le système et correspondant à ses responsabilités et fonctions. Il s'agit généralement des actions observables que le système peut effectuer. |
| Warning | Lorsque le service est dégradé, menacé ou se comporte en dehors de ses paramètres attendus, des événements de niveau d'avertissement sont utilisés. |
| Error | Lorsque la fonctionnalité n'est pas disponible ou que les attentes ne sont pas satisfaites, un événement d'erreur est utilisé. |
| Fatal | Le niveau le plus critique, les événements fatals nécessitent une attention immédiate. |
Niveau par défaut : si aucun niveau minimum n'est spécifié, les événements de niveau Information et supérieurs seront traités.
Remplacement par sink
Parfois, il est souhaitable d'écrire des journaux détaillés sur un support, mais des journaux moins détaillés sur un autre.
- Log.Logger = new LoggerConfiguration()
- .MinimumLevel.Debug()
- .WriteTo.File("log.txt")
- .WriteTo.Console(restrictedToMinimumLevel: LogEventLevel.Information)
- .CreateLogger();
Dans cet exemple, les journaux de débogage seront écrits dans le fichier de roulement, tandis que seuls les journaux de niveau Information et supérieur seront écrits dans la console.
Tous les récepteurs fournis prennent en charge le paramètre de configuration restrictedToMinimumLevel.
Minimums du journal et du récepteur : il est important de comprendre que le niveau de journalisation ne peut être augmenté que pour les récepteurs, et non abaissé. Ainsi, si le MinimumLevel du journal est défini sur Information, un récepteur avec Debug comme niveau spécifié ne verra toujours que les événements de niveau Information. Cela est dû au fait que la configuration au niveau du journal contrôle les instructions de journalisation entraînant la création d'événements, tandis que la configuration au niveau du récepteur ne filtre que ceux-ci. Pour créer un seul journal avec un niveau plus détaillé, utilisez une LoggerConfiguration distincte.
Enrichisseurs
Les enrichisseurs sont des composantes simples ajoutant, supprimant ou modifiant les propriétés attachées à un événement de journal. Cela peut être utilisé pour attacher un identificateur de processus léger à chaque événement, par exemple :
Les enrichisseurs sont ajoutés à l'aide de l'objet de configuration Enrich :
La configuration ci-dessus montre comment une propriété ajoutée par un enrichisseur peut être utilisée dans la mise en forme de sortie.
Si la valeur de la propriété enrichie est constante tout au long de l'exécution de l'application, la méthode de raccourci WithProperty peut être utilisée pour simplifier la configuration.
- Log.Logger = new LoggerConfiguration()
- .Enrich.WithProperty("Version", "1.0.0")
- .WriteTo.Console()
- .CreateLogger();
Les enrichisseurs et les propriétés qu'ils attachent sont généralement plus utiles avec les récepteurs utilisant un entreposage structuré, où les valeurs de propriété peuvent être visualisées et filtrées.
Filtres
Les événements peuvent être enregistrés de manière sélective par filtrage. Les filtres ne sont que des prédicats sur LogEvent, avec certains scénarios courants gérés par la classe Matching :
Sous-journal de bord
Parfois, un niveau de contrôle plus fin sur ce qui est vu par un récepteur est nécessaire. Pour cela, Serilog permet à un pipeline de journalisation complet d'agir comme un récepteur :
- Log.Logger = new LoggerConfiguration()
- .WriteTo.Console()
- .WriteTo.Logger(lc => lc
- .Filter.ByIncludingOnly(...)
- .WriteTo.File("log.txt"))
- .CreateLogger();
Pour les scénarios mal gérés par les sous-journal de bord, il est possible de créer plusieurs pipelines indépendants de niveau supérieur. Un seul pipeline peut être attribué à Log.Logger, mais votre application peut utiliser autant d'instances ILogger supplémentaires que nécessaire.
Notez que les stratégies de déstructuration n'auront aucun effet si elles sont spécifiées dans le rappel WriteTo.Logger(), car les sous-enregistreurs fonctionnent avec des LogEvents déjà créés.