<!-- 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`.