v0.1.0-pre.073

docs/guides/LOGGING.md

@@ -0,0 +1,74 @@
+<!-- file: docs/guides/LOGGING.md -->
+<!-- version: 1 -->
+
+# Guide de logging et tracing
+
+## Objectif
+
+`kb-logging` initialise les routes de tracing définies par la configuration et conserve les guards nécessaires à leur durée de vie.
+
+## Flux de démarrage
+
+1. charger et valider la configuration avec `kb-config` ;
+2. construire `LoggingConfig` ;
+3. appeler `kb_logging::init_logging` une seule fois ;
+4. conserver `LoggingGuard` jusqu’à la fermeture du processus ;
+5. émettre les événements avec des targets canoniques.
+
+```rust
+let guard = match kb_logging::init_logging(&config.logging) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+
+tracing::info!(
+    target: kb_logging::tracing_target(),
+    routes = guard.route_count(),
+    "logging initialized"
+);
+```
+
+## Routes
+
+Une route définit notamment :
+
+- sink console ou fichier ;
+- niveau minimal ;
+- format humain, compact, pretty ou JSON ;
+- rotation ;
+- targets exactes ou préfixes ;
+- activation ANSI.
+
+Les routes fichier ne doivent jamais écrire de secrets ou de keypairs.
+
+## Nomenclature des targets
+
+Les targets suivent les conventions du workspace, par exemple :
+
+```text
+kb-pipeline.backfill
+kb-pipeline.decode-replay
+kb-onchain-transport.http
+kb-lib.executor.spl.token-2022
+```
+
+Une nouvelle target doit être ajoutée selon `docs/OPERATION_NAMING_CONVENTION.md` et les règles Khadhroony.
+
+## Frontend desktop
+
+Les fenêtres Tauri utilisent la permission tracing prévue par leurs capabilities. Les logs frontend sont adaptés vers le backend sans permettre au frontend de choisir arbitrairement une target sensible.
+
+## Diagnostic
+
+- vérifier les routes actives via `route_names()` ;
+- confirmer le niveau global et les filtres spécifiques ;
+- vérifier le chemin et les permissions d’une route fichier ;
+- vérifier que le guard n’est pas détruit prématurément ;
+- ne pas réinitialiser le subscriber global pendant l’exécution.
+
+## Références
+
+- `kb-logging/README.md` ;
+- `kb-logging/USAGE.md` ;
+- `kb-config/USAGE.md` ;
+- `docs/architecture/ARCHITECTURE.md`.