khadhroony-bot3/docs/guides/LOGGING.md

Guide de logging et tracing

Objectif

ks-logging possède désormais le contrat logging, son document de profils, son schéma JSON et l’initialisation runtime tracing.

Flux de démarrage

1. charger config/logging.config.json avec ks_logging::read_logging_json_file_with_environment ;
2. sélectionner le profil avec ks_logging::active_logging_profile ;
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.

let document = match ks_logging::read_logging_json_file_with_environment(
    std::path::Path::new("config/logging.config.json"),
    std::path::Path::new("."),
) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let config = match ks_logging::active_logging_profile(&document) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let guard = match ks_logging::init_logging(config) {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

Le profil logging est sélectionné indépendamment du profil général de app.config.json.

Contrat JSON

Le schéma est config/schemas/logging.config.schema.json. Les exemples sont config/logging.config.json pour la configuration runtime de référence et config/example.logging.config.json pour un exemple minimal.

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

Pour un matérialisateur, la target de tracing reste distincte du processorName persisté.

Frontend desktop

Le desktop charge les documents app et logging séparément. Il ne convertit plus un type ks_config::LoggingConfig vers ks_logging::LoggingConfig : le type runtime est possédé directement par ks-logging.

La surface publique de diagnostic/configuration reste volontairement inchangée jusqu’à 0.5.1-pre.006, qui supprimera l’exposition des configurations résolues complètes.

Diagnostic

• vérifier KS_LOGGING_CONFIG_PATH si le fichier par défaut n’est pas utilisé ;
• vérifier le profil logging actif indépendamment du profil app ;
• valider le document contre son schéma ;
• confirmer le niveau global et les filtres spécifiques ;
• vérifier les chemins et permissions des routes fichier ;
• ne pas réinitialiser le subscriber global pendant l’exécution.

Références

• ks-logging/README.md ;
• ks-logging/USAGE.md ;
• config/README.md ;
• docs/OPERATION_NAMING_CONVENTION.md.