Exigences minimales pour un logger maison, avec une checklist de tests d'intégration

Si vous pouvez utiliser un framework de journalisation existant, c’est le choix le plus sûr. Il existe néanmoins des situations où les contraintes de l’application ou les circonstances opérationnelles rendent un logger maison incontournable. La première question qui se pose alors est de savoir jusqu’où pousser l’implémentation pour obtenir une conception « ni trop sommaire, ni trop lourde ».

Dans cet article, nous limitons le périmètre aux journaux applicatifs utilisés pour l’investigation des incidents. Plutôt que d’embarquer d’un coup les pistes d’audit, le traçage distribué, une plateforme de métriques et l’agrégation cloud, nous définissons d’abord une configuration minimale utile sur le terrain, puis nous détaillons les axes de tests d’intégration nécessaires pour rendre cette configuration réellement fiable.

D’abord, la conclusion

Voici les points essentiels à couvrir dans la première version.

• Utiliser UTF-8 en JSON Lines comme format
• Ne jamais rompre la règle d’un enregistrement par ligne
• Les champs obligatoires sont timestamp, level, category, message, des fields structurés, sessionId et processId
• La base est un fichier par processus
• Écriture synchrone à faible volume, single writer + bounded queue à volume plus élevé
• Flush synchrone pour Error / Critical et pour les enregistrements de début/fin de session
• Intégrer la rotation et la rétention dès la v1
• Lorsque la destination des journaux est indisponible, ne pas détourner silencieusement vers un autre emplacement

En se limitant à peu près à ce niveau, l’implémentation comme l’exploitation ont beaucoup moins de risques de s’effondrer.

D’abord, restreindre le périmètre

Les loggers maison ont tendance à devenir compliqués parce qu’on cherche dès le départ à tout gérer. Essayez de réunir dans un seul mécanisme les journaux de diagnostic, les journaux d’audit, la mesure de performance, le traçage distribué et l’analyse du comportement utilisateur, et les exigences explosent d’un coup.

Ici, la cible est le journal de diagnostic utilisé pour isoler les pannes applicatives. Autrement dit, on privilégie la capacité à retracer après coup « quand », « dans quel traitement », « ce qui s’est passé » et « quel était le contexte à ce moment-là ». Ce seul recentrage rend les décisions de conception initiales bien plus faciles.

Les exigences minimales

1. Le format est UTF-8 JSON Lines

On peut conserver les journaux sous forme de texte brut concaténé, mais cela devient difficile à traiter mécaniquement par la suite. À l’inverse, partir d’un format binaire propriétaire lourd nuit à l’observabilité en exploitation.

Le compromis pratique est UTF-8 en JSON Lines. Avec un enregistrement par ligne, le fichier reste lisible comme du texte et facile à analyser ensuite avec des scripts et des outils. Même si une écriture est interrompue en cours de route, il est facile d’isoler la ligne corrompue — un avantage concret sur le terrain.

2. Fixer les champs obligatoires dès le départ

L’ensemble minimal de champs à réunir est le suivant, au nombre de sept.

• timestamp
• level
• category
• message
• fields
• sessionId
• processId

Un journal réduit à une simple chaîne message pose problème dès que les critères de recherche se multiplient par la suite. À l’inverse, trop de champs alourdit brusquement la charge côté appelant. Il est plus sûr de fixer l’ensemble à peu près à cette taille au départ, et de n’envisager des ajouts que lorsqu’ils deviennent réellement nécessaires.

3. Faire d’un fichier par processus la base

Une conception où plusieurs processus ajoutent des lignes au même fichier comporte plus de risques d’incident qu’il n’y paraît. L’exclusion mutuelle, les écritures partielles, le moment de la rotation et la gestion des arrêts anormaux deviennent tous difficiles en même temps.

Commencez par établir un fichier par processus comme base. Si vous souhaitez regrouper plusieurs processus, il est plus sûr d’agréger en aval, ou de mettre en place explicitement un processus d’agrégation dédié.

4. Adapter la stratégie d’écriture à la charge

Tant que le volume de journaux est faible, les écritures synchrones sont plus simples à comprendre et facilitent l’investigation en cas d’incident. Forcer un passage à l’asynchrone risque de perdre les journaux écrits juste avant l’arrêt, ou de laisser flous les conditions de flush en cas d’exception.

À l’inverse, si le volume de journaux augmente et que les E/S synchrones deviennent le goulot d’étranglement, adoptez single writer + bounded queue. L’important, dans ce cas, est de décider à l’avance la politique de débordement. Ne laissez pas dans le flou si l’on écarte les anciens journaux, si l’on abandonne les nouveaux, ou si l’on émet un avertissement.

5. Décider les conditions de flush

Effectuer un flush synchrone pour Error et Critical, ainsi que pour les journaux de début et de fin de session, se révèle précieux lors des investigations d’incident. Flusher systématiquement jusqu’aux Info courants ralentit le système ; ne pas traiter tout de la même façon est donc le choix réaliste.

6. Intégrer la rotation et la rétention dès la v1

La rotation est souvent considérée comme quelque chose à « ajouter plus tard », mais c’est une fonctionnalité dont l’absence pose brutalement problème une fois en exploitation. Le mécanisme peut être n’importe lequel — par taille, quotidien, à chaque démarrage — mais il faut au minimum être dans un état où « la croissance n’est pas illimitée » et où « le nombre de fichiers conservés » est décidé.

7. Pas de repli de stockage improvisé en cas d’échec d’écriture

Une conception qui écrit silencieusement ailleurs lorsque la destination des journaux est indisponible complique l’investigation ultérieure. Le simple fait que les journaux ne soient pas « à l’endroit où ils devraient être » retarde la réaction initiale de l’équipe d’exploitation face à un incident.

Si l’enregistrement échoue, faites apparaître l’échec via un canal explicitement visible : notification dans l’application, journal d’événements, sortie d’erreur standard, etc. Évitez au minimum l’état où « personne ne sait où sont passés les journaux ».

Une configuration minimale pour la v1

Pour la première version, ce qui suit suffit souvent.

• UTF-8 JSON Lines
• Un fichier par processus
• Des noms de fichiers par session
• Rotation basée sur la taille ou par démarrage
• Une limite supérieure sur le nombre de fichiers conservés
• Flush synchrone pour Error / Critical
• Une API acceptant des fields structurés

Au-delà, il vaut mieux n’ajouter des fonctionnalités qu’après que l’exploitation réelle a révélé « ce qui a vraiment posé problème » : le logger reste ainsi plus facile à maintenir.

Anti-patterns courants

Voici les cas typiques à éviter.

• Tout entasser dans la chaîne message
• Partager le même fichier entre plusieurs processus
• Passer entièrement à l’asynchrone sans avoir décidé les conditions de flush
• Repousser la rotation et la rétention à plus tard
• Détourner silencieusement vers un autre dossier en cas d’échec d’écriture
• Intégrer dès la v1 la transmission réseau ou le stockage en base de données locale

Chacun de ces points paraît pratique au premier abord, mais ce sont tous des éléments qui alourdissent l’isolation des pannes et l’exploitation.

Penser les tests d’intégration avec des fichiers, des threads et des processus réels

Un logger est un composant que les tests unitaires seuls ne suffisent pas à rassurer. Vérifier uniquement le formatage des chaînes et la sérialisation JSON passe à côté de ce qui cause réellement des problèmes en production : les E/S, la concurrence, la rotation, le flush à l’arrêt et les erreurs de permission.

Les tests d’intégration doivent donc être vérifiés avec des fichiers réels, des threads réels et, si nécessaire, des processus réels. Au minimum, on veut éviter l’état où le logger « fonctionne au quotidien, mais ne peut pas être fiable pendant un incident ».

Éléments de tests d’intégration à faire passer

Santé d’une écriture unique

• Chaque ligne correspond-elle exactement à un enregistrement JSON ?
• Peut-on relire le fichier en UTF-8 ?
• Les champs obligatoires sont-ils présents à chaque fois ?
• Un retour à la ligne intégré n’a-t-il pas fragmenté un enregistrement sur plusieurs lignes ?

Concurrence au sein d’un même processus

• Les enregistrements restent-ils intacts quand plusieurs threads écrivent simultanément ?
• Le nombre d’enregistrements n’est-il ni manquant ni excédentaire ?
• Avec une queue en usage, l’ordre et les pertes se comportent-ils conformément aux spécifications ?

Comportement du flush et de l’arrêt

• Error / Critical sont-ils répercutés immédiatement ?
• La queue est-elle vide après un arrêt normal ?
• Les journaux finaux nécessaires survivent-ils sur des chemins proches d’une sortie exceptionnelle ?

Rotation et rétention

• Le logger bascule-t-il vers un nouveau fichier quand la condition de rotation est remplie ?
• Les anciens fichiers au-delà de la limite de rétention sont-ils supprimés conformément aux spécifications ?
• Les lignes JSON restent-elles intactes juste avant et juste après la rotation ?

Cas d’anomalie

• Comportement quand le répertoire de destination n’existe pas
• Comportement en l’absence de droit d’écriture
• Notification ou valeur de retour en cas d’échec dans des conditions proches d’un disque plein
• Comportement en cas de débordement de la queue

Gestion de plusieurs processus

Si la spécification impose un fichier par processus, alors le fait même qu’un autre processus n’essaie pas d’entrer dans le même fichier peut lui-même devenir une cible de vérification. À l’inverse, avec un schéma à processus d’agrégation, la vérification doit inclure les échecs de transmission vers ce processus.

Le nombre minimal de tests à faire passer en v1

Vouloir tout faire dès le départ alourdit excessivement les tests. Le minimum à faire passer en v1 tourne autour des six éléments suivants.

1. Écritures normales depuis un thread unique
2. Écritures simultanées depuis plusieurs threads
3. Flush des Error / Critical
4. Rotation et rétention
5. Notification d’échec quand la destination est indisponible
6. Drain et flush final lors d’un arrêt normal

Même avec seulement ces six tests qui passent, on s’éloigne déjà nettement d’un « logger qui émet des chaînes de caractères mais auquel on ne peut pas faire confiance en exploitation ».

Résumé

Le premier objectif d’un logger maison n’est pas la richesse fonctionnelle, mais le fait d’être « crédible pendant un incident ». Pour y parvenir, il est efficace de fixer le format en UTF-8 JSON Lines, de garder des champs obligatoires resserrés, de faire d’un fichier par processus la base, et de décider tôt le flush, la rotation, la rétention et le comportement en cas d’échec.

Reste à vérifier si cette conception fonctionne réellement, ce qui doit passer par des tests d’intégration utilisant des fichiers réels, des threads réels et des processus réels. Avant de faire grossir l’implémentation, fixer d’abord la configuration minimale et le jeu de tests minimal permet ensuite de la faire évoluer sans forcer.

Articles associés

Articles récents partageant les mêmes étiquettes, pour approfondir des sujets proches.

Sujets associés

Ces pages replacent le sujet dans un contexte plus large de services et de décisions.

Services liés à ce sujet

Cet article est directement lié aux services suivants.

Questions fréquentes

Questions souvent posées lors d’une consultation sur le sujet de cet article.

Quel format doit utiliser un logger maison ?

UTF-8 en JSON Lines, avec un enregistrement par ligne, est le compromis pratique à privilégier. Un texte brut concaténé est difficile à traiter mécaniquement par la suite, tandis qu'un format binaire propriétaire lourd nuit à l'observabilité en exploitation. Avec JSON Lines, le fichier reste lisible comme du texte, facile à analyser avec des scripts et des outils, et même si une écriture est interrompue en cours de route, il est facile d'isoler la ligne corrompue. L'ensemble minimal de champs est timestamp, level, category, message, fields structurés, sessionId et processId.

Les écritures de journaux doivent-elles être synchrones ou asynchrones ?

Il faut adapter la stratégie à la charge. Tant que le volume de journaux est faible, les écritures synchrones sont plus simples à comprendre et facilitent l'investigation en cas d'incident ; forcer un passage à l'asynchrone risque de perdre les journaux écrits juste avant l'arrêt. Si le volume augmente et que les E/S synchrones deviennent le goulot d'étranglement, adoptez un single writer avec une bounded queue, et décidez à l'avance la politique de débordement plutôt que de la laisser floue. Dans tous les cas, effectuez un flush synchrone pour les enregistrements Error et Critical ainsi que pour les journaux de début et de fin de session.

Que doit faire un logger lorsqu'il ne peut pas écrire vers sa destination ?

Ne détournez jamais silencieusement les journaux vers un autre emplacement. Une conception qui écrit discrètement ailleurs lorsque la destination est indisponible complique l'investigation ultérieure, car le simple fait que les journaux ne soient pas là où ils devraient être retarde la réaction initiale de l'équipe d'exploitation face à un incident. Faites plutôt apparaître l'échec via un canal explicitement visible, comme une notification dans l'application, le journal d'événements Windows ou la sortie d'erreur standard, afin que personne ne se demande où sont passés les journaux.

Pourquoi un logger maison a-t-il besoin de tests d'intégration, et pas seulement de tests unitaires ?

Vérifier uniquement le formatage des chaînes et la sérialisation JSON passe à côté de ce qui cause réellement des problèmes en production : les E/S, la concurrence, la rotation, le flush à l'arrêt et les erreurs de permission. Les tests d'intégration doivent utiliser des fichiers réels, des threads réels et, si nécessaire, des processus réels. L'ensemble minimal à faire passer en v1 comprend six éléments : écritures normales à thread unique, écritures simultanées multi-threads, flush des Error et Critical, rotation et rétention, notification d'échec lorsque la destination est indisponible, et drain plus flush final lors d'un arrêt normal.

Profil de l’auteur

Page de présentation de l’auteur de l’article.

Go Komura

Représentant de KomuraSoft LLC

Spécialisé dans le développement de logiciels Windows, le conseil technique et l’analyse de pannes, notamment pour les systèmes existants et les incidents difficiles à reproduire.