khadhroony-bot3/ks-logging/USAGE.md

Utilisation de ks-logging

Chargement recommandé

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

Le document possède :

{
  "logs_directory": "${KS_LOGS_DIRECTORY:-logs}",
  "default_profile": "local_devnet",
  "profiles": []
}

logs_directory n'appartient à aucun profil. Les paths relatifs des targets fichier sont résolus sous cette racine. Un path absolu reste inchangé.

Override par composition

Une application peut sélectionner un autre profil avec :

let config = match ks_logging::logging_profile(&document, "mainnet_research") {
    Ok(value) => value,
    Err(error) => return Err(error),
};

Le default_profile reste le fallback autonome du document ; la sélection explicite d'une composition prime uniquement pour le consommateur concerné.

Le chemin du document peut être remplacé opérationnellement par KS_LOGGING_CONFIG_PATH. La racine des fichiers peut être remplacée indépendamment par KS_LOGS_DIRECTORY.

Initialisation

Une fois le profil résolu :

match ks_logging::init_logging(&config) {
    Ok(()) => (),
    Err(error) => return Err(error),
}

L'initialisation reste globale au processus. Les binaires doivent donc résoudre leur configuration avant le premier appel à init_logging.

Filtres des dépendances tierces

Les routes wildcard debug restent destinées aux composants Khadhroony, mais elles ne doivent pas transformer la console et debug.log en trace brute des bibliothèques réseau ou SQL.

Les profils standards imposent WARN aux targets h2, hyper, hyper_util, rustls, rustls_platform_verifier et sqlx. Les targets tiers restent ceux de leurs crates propriétaires : un événement HTTP/2 reste h2::*, un événement Hyper reste hyper*, un événement SQLx reste sqlx::query et un événement TLS reste rustls::*.

ks-store désactive en complément le statement logging automatique de SQLx. Les requêtes fonctionnellement importantes doivent être instrumentées par ks-store avec son target canonique et des champs structurés, sans dépendre du format de logging d'une bibliothèque tierce. Les warnings/errors des dépendances restent observables dans les profils standards.