<!-- file: docs/guides/LOGGING.md -->
<!-- version: 3 -->

# Guide de logging et tracing

## Objectif

`ks-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 `ks-config` ;
2. construire `LoggingConfig` ;
3. appeler `ks_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 ks_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: ks_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
ks-pipeline.backfill
ks-pipeline.decode-replay
ks-onchain-transport.http
kb-lib.executor.spl.token-2022
kb-lib.materializer.compliance.audit
kb-lib.materializer.token.accounts
kb-lib.materializer.transaction.annotations
```

Pour un matérialisateur, la target de tracing est l’identité runtime `kb-lib.materializer.<domain>[.<subsystem>]`. Elle reste distincte du `processorName` persisté `materializer.<domain>[.<subsystem>]`, qui ne doit pas être utilisé comme target de logs.

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

- `ks-logging/README.md` ;
- `ks-logging/USAGE.md` ;
- `ks-config/USAGE.md` ;
- `docs/architecture/ARCHITECTURE.md`.