Logging

La journalisation est centralisée dans kb_logging et repose sur des événements tracing structurés.

Objectifs

séparer console, fichiers globaux et fichiers par crate ;
conserver un fichier JSONL dédié aux erreurs ;
retrouver immédiatement un échec de décodage ou de matérialisation ;
corréler RPC, pipeline, store et processor sans dupliquer les décisions dans Tauri ;
activer le debug d’une crate sans dépendre de son découpage interne en modules.

Arborescence d’un profil

Pour un profil stocké sous logs/<profile>/, la configuration crée :

logs/<profile>/debug.log
logs/<profile>/info.log
logs/<profile>/error.jsonl
logs/<profile>/app.log
logs/<profile>/<crate>/debug.log
logs/<profile>/<crate>/info.log
logs/<profile>/<crate>/error.jsonl

Les routes sont en rotation quotidienne. tracing-appender insère la date dans le nom physique produit à partir du préfixe et du suffixe configurés.

Les niveaux sont cumulatifs :

debug.log reçoit debug, info, warn et error ;
info.log reçoit info, warn et error ;
error.jsonl reçoit uniquement error ;
app.log reçoit les événements kb_app_demo à partir de debug.

error.jsonl utilise le format JSON pour permettre la recherche par champ. Les autres fichiers utilisent le format humain sans ANSI.

Targets canoniques

Le target est exactement le nom de la crate et provient de src/constants.rs :

kb_app_demo
kb_decoder_solana_core
kb_executor_metadata_spl_name_service
kb_executor_solana_core
kb_executor_spl_account_compression
kb_executor_spl_memo
kb_executor_spl_noop
kb_executor_spl_single_pool
kb_logging
kb_materializer_admin
kb_materializer_compliance_audit
kb_materializer_lifecycle
kb_materializer_staking
kb_pipeline
kb_rpc
kb_store_pg

La granularité passe par les champs action, stage, window, campaign_id, signature, instruction_path, program_id, processor_name, status et error_code.

Corrélation de campagne

Les campagnes de backfill, extraction core et replay decode utilisent des identifiants stables :

capture_session_id
campaign_id
signature
slot
instruction_path
program_id
input_key
input_hash
processor_name
processor_version

Le pipeline journalise la sélection et l’agrégation. Le RPC journalise le transport et l’endpoint sélectionné sans exposer l’URL secrète. Le store journalise la persistance et les rollbacks. Le décodeur et chacun des matérialiseurs lifecycle, admin et compliance audit journalisent leur décision propre.

Fichier d’erreurs

Les erreurs de décodage et de matérialisation sont émises au niveau error par la crate responsable, puis éventuellement par la frontière qui constate l’échec terminal. Elles apparaissent donc dans :

logs/<profile>/error.jsonl ;
logs/<profile>/<crate>/error.jsonl.

Cette duplication volontaire fournit une vue globale et une vue isolée par composant. Les champs de corrélation permettent de regrouper les événements d’un même défaut.

Une transaction on-chain échouée mais correctement décodée n’est pas écrite dans error.jsonl uniquement à cause de meta.err. En revanche, un payload déclaré compatible mais failed ou unsupported indique une lacune du code ou une évolution du protocole et doit être visible dans le fichier d’erreurs.

Frontend et Tauri

Le frontend peut continuer à transmettre un identifiant logique tel que kb_app_demo.frontend.demo_decode_replay. Le backend le valide et le conserve dans le champ frontend_target, mais l’événement est émis avec le target canonique kb_app_demo.

kb_app_demo ne doit pas recopier les détails internes d’un retry RPC, d’un parsing binaire ou d’un commit SQL. Il journalise l’invocation, la progression visible et le résumé reçu de la crate opérationnelle.

Sécurité

Les logs ne contiennent jamais de clé privée, seed phrase, DSN non masqué, URL fournisseur secrète ou payload complet non borné. Pour un payload problématique, conserver la taille, un préfixe borné et un SHA-256.

Le contrat normatif complet se trouve dans docs/TRACING_CONTRACT.md.

4.2 KiB Raw Blame History Unescape Escape