0.5.1-pre.007

ks-logging/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: ks-logging/USAGE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Utilisation de ks-logging
 
@@ -13,114 +13,48 @@ let document = match ks_logging::read_logging_json_file_with_environment(
     Ok(value) => value,
     Err(error) => return Err(error),
 };
-let config = match ks_logging::active_logging_profile(&document) {
-    Ok(value) => value,
-    Err(error) => return Err(error),
-};
-let guard = match ks_logging::init_logging(config) {
+let config = match ks_logging::default_logging_profile(&document) {
     Ok(value) => value,
     Err(error) => return Err(error),
 };
 ```
 
-Le desktop utilise normalement le chemin déclaré dans sa composition `config/kb-app-demo-desktop.default.config.json`. `KS_LOGGING_CONFIG_PATH` peut encore remplacer explicitement ce chemin sans modifier le fichier de composition.
-
-## Format du document
+Le document possède :
 
 ```json
 {
-  "active_profile": "local_devnet",
-  "profiles": [
-    {
-      "name": "local_devnet",
-      "default_level": "info",
-      "targets": [],
-      "target_filters": []
-    }
-  ]
+  "logs_directory": "${KS_LOGS_DIRECTORY:-logs}",
+  "default_profile": "local_devnet",
+  "profiles": []
 }
 ```
 
-Le schéma formel est `config/schemas/logging.config.schema.json`. `config/example.logging.config.json` fournit un exemple minimal conforme avec des routes valides.
+`logs_directory` n'appartient à aucun profil. Les paths relatifs des targets fichier sont résolus sous cette racine. Un path absolu reste inchangé.
 
-`targets` doit contenir au moins une route et au moins une route doit être activée.
+## Override par composition
 
-## Sélection indépendante
-
-Le `active_profile` logging reste le défaut autonome du document. Lorsqu’un binaire utilise une composition, il sélectionne explicitement son `logging_profile` avec `ks_logging::logging_profile`; cette sélection prime pour ce binaire sans modifier le document partagé.
-
-## Construction directe
-
-Les tests ou consommateurs spécialisés peuvent toujours construire directement `LoggingConfig` puis appeler `init_logging` :
+Une application peut sélectionner un autre profil avec :
 
 ```rust
-let config = ks_logging::LoggingConfig {
-    default_level: "info".to_string(),
-    targets: vec![ks_logging::LogTargetConfig {
-        name: "console".to_string(),
-        enabled: true,
-        sink: "console".to_string(),
-        level: "info".to_string(),
-        path: String::new(),
-        rotation: "none".to_string(),
-        format: "compact".to_string(),
-        ansi: true,
-        targets: vec!["ks-*".to_string()],
-    }],
-    target_filters: Vec::new(),
-};
-let guard = match ks_logging::init_logging(&config) {
+let config = match ks_logging::logging_profile(&document, "mainnet_research") {
     Ok(value) => value,
     Err(error) => return Err(error),
 };
 ```
 
-## Route fichier JSON
+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 :
 
 ```rust
-let file_route = ks_logging::LogTargetConfig {
-    name: "operations-json".to_string(),
-    enabled: true,
-    sink: "file".to_string(),
-    level: "debug".to_string(),
-    path: "logs/operations.jsonl".to_string(),
-    rotation: "daily".to_string(),
-    format: "json".to_string(),
-    ansi: false,
-    targets: vec!["ks-pipeline*".to_string()],
-};
-```
-
-Les rotations supportées sont `none`, `never`, `daily` et `hourly`. Les formats supportés sont `human`, `compact`, `pretty` et `json`.
-
-## Inspection des routes
-
-```rust
-for route_name in guard.route_names() {
-    println!("active logging route: {route_name}");
+match ks_logging::init_logging(&config) {
+    Ok(()) => (),
+    Err(error) => return Err(error),
 }
-
-assert_eq!(guard.route_count(), guard.route_names().len());
 ```
 
-## Erreurs
-
-Les erreurs utilisent `ks_core::Error`. Les cas principaux sont :
-
-- document ou schéma invalide ;
-- profil actif absent ou dupliqué ;
-- aucune route activée ;
-- sink, format, rotation ou niveau inconnu ;
-- chemin fichier invalide ;
-- échec d’initialisation du subscriber global.
-
-## Tests instructifs
-
-- les tests de `document` vérifient les deux fichiers logging versionnés et les profils indépendants ;
-- `default_logging_config_routes_global_and_operational_crate_files` vérifie les routes canoniques ;
-- les tests de `tracing_runtime` vérifient l’installation, les filtres et le volume de routes.
-
-## Limites
-
-- initialisation globale unique par processus ;
-- la politique de redaction des valeurs secrètes avant logging est renforcée dans `0.5.1-pre.006`.
+L'initialisation reste globale au processus. Les binaires doivent donc résoudre leur configuration avant le premier appel à `init_logging`.