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

charger et valider la configuration avec ks-config ;
construire LoggingConfig ;
appeler ks_logging::init_logging une seule fois ;
conserver LoggingGuard jusqu’à la fermeture du processus ;
émettre les événements avec des targets canoniques.

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 :

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.

2.5 KiB Raw Blame History Unescape Escape