Données structurées
Serilog est une sorte de sérialiseur. Dans de nombreux cas, il a un bon comportement par défaut convenant à son objectif, mais il est parfois nécessaire d'indiquer à Serilog comment entreposer les propriétés attachées à un événement de journal.
Serilog utilise quelques termes inhabituels pour désigner la manière dont les objets .NET sont cartographiés à sa représentation de propriété interne (indépendante du récepteur). Ceux-ci sont expliqués plus en détail ci-dessous, vous pouvez donc ignorer cette section si vous prévoyez de lire la page entière.
- La stringification est le processus consistant à prendre une propriété .NET fournie et à appeler sa méthode ToString() afin que la représentation atteignant les récepteurs soit une simple chaîne de caractères.
- La déstructuration est le processus consistant à prendre un objet .NET complexe et à le convertir en une structure, pouvant ensuite être représentée comme, par exemple, un objet JSON ou un blob XML.
- Les scalaires sont des types .NET pouvant être représentés comme des valeurs atomiques; la plupart des types de valeur comme int correspondent à cette description, mais c'est également le cas de certains types de référence comme Uri et string.
Pourquoi contrôler la représentation ?
Il existe potentiellement de nombreuses façons d'enregistrer un objet dans le journal. La plupart des types peuvent être joliment représentés sous forme de chaînes ou de valeurs simples, mais certains sont plus logiques à enregistrer sous forme de collections, et d'autres sous forme de structures avec des propriétés nommées.
La représentation d'entreposage d'une propriété d'événement de journal fait une grande différence quant à sa taille dans le journal, ainsi qu'à la mémoire et au traitement nécessaires pour l'y amener.
En gardant cela à l'esprit, examinons comment Serilog est configuré pour fonctionner dans les cas simples.
Comportement par défaut
Lorsque des propriétés sont spécifiées dans les événements du journal, Serilog fait de son mieux pour déterminer la représentation correcte.
Valeurs scalaires simples
- var count = 456;
- Log.Information("{Count} enregistrements récupérés", count);
Il y a peu d'ambiguïté quant à la manière dont la propriété Count doit être entreposée dans ce cas. Étant une simple valeur entière, Serilog choisira cela comme représentation.
- { "Count": 456 }
Ces exemples utilisent JSON, mais les mêmes principes s'appliquent également à d'autres formats.
Par défaut, Serilog reconnaît la liste suivante comme types scalaires de base, quelles que soient les autres politiques appliquées :
| Types scalaires | Type de données |
|---|---|
| Booléennes | bool |
| Numériques | byte, short, ushort, int, uint, long, ulong, float, double, decimal |
| Chaîne de caractères | string, byte[] |
| Temporelles | DateTime, DateTimeOffset, TimeSpan |
| Autres | Guid, Uri |
| Nullables | Vversions nullables de l'un des types ci-dessus |
Collections
Si l'objet transmis en tant que propriété est IEnumerable, Serilog traitera cette propriété comme une collection.
- var fruit = new[] { "Pomme", "Poire", "Orange" };
- Log.Information("Dans mon bol j'ai {Fruit}", fruit);
L'équivalent JSON inclut un tableau :
{ "Fruit": ["Pomme", "Poire", "Orange"] }Serilog fait ce choix car la plupart des types énumérables sont intéressants pour leurs éléments et se présentent mal sous forme de structures ou de chaînes de caractères.
Serilog reconnaît également Dictionary<TKey,TValue>, à condition que le type de clef soit l'un des types scalaires répertoriés ci-dessus.
Les formateurs prenant en charge les dictionnaires peuvent enregistrer la propriété comme telle :
{ "Fruit": { "Pomme": 1, "Poire": 5 }}IDictionary<TKey,TValue> - les objets implémentant des interfaces de dictionnaire ne sont pas sérialisés en tant que dictionnaires. Tout d'abord parce qu'il est moins efficace dans .NET de vérifier la compatibilité des interfaces génériques, et ensuite parce qu'un seul objet peut implémenter plusieurs interfaces de dictionnaire génériques, ce qui crée une ambiguïté.
Objets
Outre les types ci-dessus, étant spécialement gérés par Serilog, il est difficile de faire des choix intelligents sur la manière dont les données doivent être rendues et conservées. Les objets n'étant pas explicitement destinés à la sérialisation ont tendance à se sérialiser très mal.
- SqlConnection conn = ...;
- Log.Information("Connecté à {Connection}", conn);
Comment sérialiser une connexion SqlConnection ? Lorsque Serilog ne reconnaît pas le type et qu'aucun opérateur n'est spécifié (voir ci-dessous), l'objet sera rendu à l'aide de ToString().
Préserver la structure de l'objet
Il existe de nombreux cas où, compte tenu des capacités, il est judicieux de sérialiser une propriété d'événement de journal en tant qu'objet structuré. Les DTO (objets de transfert de données), les messages, les événements et les modèles sont souvent mieux enregistrés en les décomposant en propriétés avec des valeurs.
Pour cette tâche, Serilog fournit l'opérateur de déstructuration @ :
- var sensorInput = new { Latitude = 25, Longitude = 134 };
- Log.Information("Traitement {@SensorInput}", sensorInput);
(Le terme «déstructuration» est emprunté à divers langages de programmation; il s'agit d'un style de correspondance de motifs utilisé pour extraire des valeurs de données structurées. L'utilisation de Serilog n'est pour l'instant que théoriquement liée à cet opérateur, mais d'éventuelles extensions futures de cet opérateur pourraient correspondre plus précisément à la définition plus large.)
Personnalisation des données entreposées
Souvent, seule une sélection de propriétés sur un objet complexe présente un intérêt. Pour personnaliser la façon dont Serilog conserve un type complexe déstructuré, utilisez l'objet de configuration Destructure sur LoggerConfiguration :
Cet exemple transforme les objets de type HttpRequest pour ne conserver que les propriétés RawUrl et Method. Un certain nombre de stratégies différentes pour la déstructuration sont disponibles, et des stratégies personnalisées peuvent être créées en implémentant IDestructuringPolicy.
Remarque : la fonction fournie à Destructure.ByTransforming() doit renvoyer un type différent de celui transmis, sinon elle sera appelée de manière récursive. Utilisez plutôt une IDestructuringPolicy personnalisée pour implémenter des transformations conditionnelles.
Opérateurs et formats
Bien que les opérateurs et les formats affectent la représentation d'une propriété, il est important de comprendre leurs rôles distincts. Les opérateurs sont appliqués au moment où la propriété est capturée, pour conserver ou structurer les données d'une manière ou d'une autre. Les formats ne sont utilisés que lors de l'affichage des propriétés sous forme de texte et n'ont aucun impact sur la représentation sérialisée.
Formatage des collections et des structures
Lorsque des chaînes de caractères de format sont spécifiées pour des propriétés complexes, elles sont généralement ignorées. Seuls les énumérables prennent en compte les chaînes de format, en les transmettant à leurs éléments lors du rendu pour l'affichage.
Forcer la transformation en chaîne de caractères
Parfois, le type d'un objet en cours de journalisation peut ne pas être connu avec précision ou peut varier d'une manière qui n'est pas souhaitable à conserver dans les événements du journal. Dans ces cas, l'opérateur de transformation en chaîne $ convertit la valeur de la propriété en chaîne avant que tout autre traitement n'ait lieu, quel que soit son type ou les interfaces implémentées.
- var unknown = new[] { 1, 2, 3 }
- Log.Information("Reçue {$Data}", unknown);
Bien qu'il s'agisse d'un type énumérable, la variable inconnue est capturée et rendue sous forme de chaîne de caractères :
Reçue "System.Int32[]"