v0.1.0-pre.070

kb-logging/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-logging/USAGE.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Utilisation de kb-logging
 
@@ -37,14 +37,97 @@ assert_eq!(guard.guard_count(), 1);
 assert_eq!(guard.route_names(), &["console".to_string()]);
 ```
 
-## Routes fichier
+## Route fichier JSON
+
+```rust
+let file_route = kb_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![
+        "kb-pipeline*".to_string(),
+        "kb-onchain-transport*".to_string(),
+    ],
+};
+
+let config = kb_logging::LoggingConfig {
+    default_level: "info".to_string(),
+    targets: vec![file_route],
+    target_filters: Vec::new(),
+};
+
+let guard = match kb_logging::init_logging(&config) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+```
 
 Pour une route `file`, `path` doit désigner le fichier cible et `rotation` doit être une valeur supportée (`none`, `never`, `daily` ou `hourly`). Les formats supportés sont `human`, `compact`, `pretty` et `json`.
 
 ## Filtres de targets
 
+```rust
+let config = kb_logging::LoggingConfig {
+    default_level: "warn".to_string(),
+    targets: vec![kb_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!["kb-*".to_string()],
+    }],
+    target_filters: vec![
+        kb_logging::LogTargetFilterConfig {
+            target: "kb-pipeline".to_string(),
+            level: "debug".to_string(),
+        },
+        kb_logging::LogTargetFilterConfig {
+            target: "kb-store".to_string(),
+            level: "info".to_string(),
+        },
+    ],
+};
+```
+
 Les routes acceptent des targets exactes et des préfixes wildcard. Les `target_filters` ajoutent des niveaux spécifiques aux routes wildcard. Une route d’erreur conserve la sémantique stricte prévue par l’implémentation.
 
+## Émission d’événements après initialisation
+
+```rust
+tracing::info!(
+    target: kb_logging::tracing_target(),
+    action = "startup",
+    "logging runtime initialized"
+);
+
+tracing::debug!(
+    target: "kb-pipeline.demo",
+    scenario = "token_2022",
+    "scenario preparation started"
+);
+```
+
+Les targets doivent suivre la nomenclature canonique du workspace pour que les routes et filtres restent prévisibles.
+
+## Inspection des routes actives
+
+```rust
+for route_name in guard.route_names() {
+    println!("active logging route: {route_name}");
+}
+
+assert_eq!(guard.route_count(), guard.route_names().len());
+```
+
 ## Erreurs
 
 Les erreurs utilisent `kb_core::Error`. Les cas principaux sont :