# 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//`, la configuration crée : ```text logs//debug.log logs//info.log logs//error.jsonl logs//app.log logs///debug.log logs///info.log logs///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 le nom exact de la crate hors `kb-lib`. Dans `kb-lib`, il suit la hiérarchie du composant : ```text 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-lib.materializer.admin kb-lib.materializer.compliance kb-lib.materializer.lifecycle kb-lib.materializer.staking kb_pipeline kb_onchain_transport 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 : ```text 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//error.jsonl` ; - `logs///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`.