Logs de données : 8 traces à prévoir avant un traitement différé ou un feature flag

1. L’événement métier demandé

Le premier log utile décrit la demande métier, pas seulement l’appel technique. Une ligne comme `job_started` aide peu si personne ne sait quelle action elle représente. Il vaut mieux tracer un événement nommé dans le langage du domaine : demande de recalcul, activation d’un tarif, synchronisation d’un statut, génération d’un export ou relance d’une notification.

Ce log doit contenir un identifiant de corrélation, le type d’objet concerné, l’identifiant interne non sensible, la source de la demande et le moment de création. Il ne doit pas contenir la donnée complète si un identifiant suffit. L’objectif est de relier les étapes sans transformer les journaux en copie parallèle de la base.

2. Le contexte de règle appliqué

Une donnée ne change presque jamais seule. Elle change parce qu’une règle s’applique : seuil, statut, période, segment client, option produit, paramètre régional, version d’algorithme ou configuration temporaire. Si le traitement est rejoué deux jours plus tard, l’équipe doit savoir si la règle utilisée était celle du moment initial ou celle disponible au moment du rejeu.

Le log doit donc indiquer la version de règle, la famille de configuration ou le nom du paramètre utilisé. Pour un feature flag, il doit au minimum préciser le nom du flag, son état évalué et le motif de ciblage si celui-ci existe dans le système. Ce point rejoint les enjeux de maîtrise du cycle de vie des feature flags : une activation progressive n’est pilotable que si elle laisse une trace lisible.

3. L’entrée réellement consommée

Entre la demande initiale et l’exécution différée, la donnée source peut évoluer. Un utilisateur corrige un champ, un autre service synchronise un statut, une règle de gestion recalcule une valeur. Le traitement doit laisser voir quelle version logique de l’entrée il a consommée.

Il n’est pas nécessaire de journaliser tout le contenu. Une empreinte, un numéro de version, un horodatage de dernière modification ou un identifiant de snapshot peut suffire. Ce choix évite de dupliquer des données sensibles dans les logs tout en permettant de vérifier si le traitement a travaillé sur une information attendue.

4. La décision produite

Un traitement peut réussir techniquement et produire une décision discutable. Le log doit distinguer l’exécution de son résultat métier : dossier accepté, facture exclue, relance suspendue, document classé, synchronisation ignorée, calcul plafonné.

Cette trace doit rester courte. Elle décrit la décision, le statut final et la raison opérationnelle principale. Si plusieurs raisons existent, mieux vaut utiliser des codes stables plutôt qu’un message libre difficile à agréger. Les détails riches peuvent rester dans les données applicatives ou dans une table d’audit dédiée si le besoin le justifie.

5. Le chemin de reprise prévu

Pour les traitements asynchrones rejouables, le log doit indiquer ce qu’il est possible de faire ensuite. Peut-on relancer sans effet de bord ? Faut-il compenser ? L’objet doit-il être repris manuellement ? Le message doit-il être abandonné après validation ?

Cette information évite une enquête où chaque incident devient une question d’architecture. Le log peut exposer un statut simple : `replay_allowed`, `manual_review_required`, `compensation_required` ou `terminal_failure`. Le vocabulaire exact dépend du système, mais il doit être compréhensible par le support, l’exploitation et les développeurs.

6. Les refus attendus

Tous les échecs ne sont pas des incidents. Un traitement peut ignorer une donnée parce qu’elle est incomplète, trop ancienne, déjà traitée ou hors périmètre du flag actif. Ces refus attendus doivent être visibles, sinon l’équipe confond silence et perte.

La difficulté consiste à ne pas créer du bruit. Un refus attendu peut être journalisé à un niveau adapté, agrégé ou comptabilisé selon son volume. En revanche, la raison doit rester exploitable : une règle de non-éligibilité bien nommée vaut mieux qu’un message générique.

7. Le changement de périmètre

Quand une activation progressive ou une file de traitement change de périmètre, il faut tracer ce changement comme un événement à part entière. Cela inclut l’élargissement d’un segment, la désactivation d’une règle, la modification d’un lot traité ou l’ajout d’un type de donnée.

Ce log sert surtout aux comparaisons. Si les anomalies apparaissent après une bascule partielle, l’équipe peut rapprocher les premiers signaux du moment où le périmètre a changé. Sans cette trace, l’analyse dépend souvent de souvenirs, de tickets ou d’échanges dispersés.

8. Le résumé de lot

Les traitements par lot méritent un résumé distinct des lignes individuelles. Il doit indiquer le volume reçu, le volume traité, les refus attendus, les erreurs techniques, les reprises prévues et le statut final du lot. Ce résumé devient le point d’entrée de l’enquête.

Il ne remplace pas les traces détaillées, mais il évite de commencer par parcourir des milliers de lignes. Il permet aussi d’identifier une dérive : plus de refus qu’habituellement, un lot incomplet, une hausse de dossiers en reprise manuelle ou une absence de données alors qu’un flux était attendu.

Tableau de cadrage des logs de données

| Trace à prévoir | Question qu’elle résout | Risque si elle manque | | --- | --- | --- | | Événement métier demandé | Quelle action a lancé le traitement ? | Confusion entre appel technique et intention métier | | Contexte de règle | Quelle règle ou quel flag était actif ? | Décision impossible à expliquer après changement de configuration | | Entrée consommée | Quelle version de la donnée a servi ? | Rejeu ou diagnostic fondé sur une donnée différente | | Décision produite | Quel effet métier a été retenu ? | Succès technique interprété à tort comme succès métier | | Chemin de reprise | Que peut faire l’équipe ensuite ? | Relances manuelles risquées ou décisions improvisées | | Résumé de lot | Le volume traité est-il cohérent ? | Enquête trop lente sur les traitements de masse |

Checklist avant mise en production

• Chaque traitement différé possède un identifiant de corrélation propagé jusqu’au résultat.
• Les logs indiquent la règle, la configuration ou le feature flag réellement évalué.
• Les données sensibles ne sont pas recopiées dans les journaux lorsque des identifiants ou empreintes suffisent.
• Les refus fonctionnels attendus sont distingués des erreurs techniques.
• Le chemin de reprise est explicite pour les cas rejouables, compensables ou manuels.
• Les lots disposent d’un résumé lisible avant consultation des traces détaillées.
• Le support sait quelles traces consulter avant d’escalader vers le développement.
• Les noms d’événements sont stables et compréhensibles hors de l’équipe qui a écrit le code.

Infographie à prévoir : le fil d’une décision différée

L’infographie associée peut représenter un flux simple : demande métier, mise en file, lecture des données, évaluation de règle ou de feature flag, décision produite, résumé de lot, puis reprise éventuelle. Le point important est de montrer où les logs de données éclairent la décision, et où ils ne doivent pas stocker la donnée complète.

Commencer petit, mais au bon endroit

Il n’est pas nécessaire de redessiner toute la journalisation pour progresser. Le meilleur premier périmètre est souvent un traitement différé qui touche une donnée importante et dont les décisions sont parfois discutées par les métiers. L’équipe peut y ajouter trois traces prioritaires : contexte de règle, entrée consommée, décision produite.

Une fois ce socle en place, les logs cessent d’être seulement un outil de diagnostic technique. Ils deviennent une mémoire courte des décisions de données, suffisante pour comprendre, corriger et expliquer sans exposer plus d’informations que nécessaire.