80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
<!-- file: docs/guides/LOGGING.md -->
|
||
<!-- version: 4 -->
|
||
|
||
# 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
|
||
ks-lib-executor.spl.token-2022
|
||
ks-lib-materializer.compliance.audit
|
||
ks-lib-materializer.token.accounts
|
||
ks-lib-materializer.transaction.annotations
|
||
```
|
||
|
||
Pour un matérialisateur, la target de tracing est l’identité runtime `ks-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`.
|