v0.1.0-pre.069

kb-logging/USAGE.md

@@ -0,0 +1,67 @@
+<!-- file: kb-logging/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de kb-logging
+
+## Initialisation
+
+```rust
+let config = kb_logging::LoggingConfig {
+    default_level: "info".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::new(),
+};
+let guard = match kb_logging::init_logging(&config) {
+    Ok(value) => value,
+    Err(error) => return Err(error),
+};
+```
+
+`init_logging` doit être appelée une seule fois par processus. Le `LoggingGuard` retourné doit rester vivant jusqu’à l’arrêt afin de ne pas interrompre les writers non bloquants.
+
+## Inspection des routes
+
+```rust
+assert_eq!(guard.route_count(), 1);
+assert_eq!(guard.guard_count(), 1);
+assert_eq!(guard.route_names(), &["console".to_string()]);
+```
+
+## Routes fichier
+
+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
+
+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.
+
+## Erreurs
+
+Les erreurs utilisent `kb_core::Error`. Les cas principaux sont :
+
+- aucune route activée ;
+- sink, format, rotation ou niveau inconnu ;
+- chemin fichier invalide ;
+- échec d’initialisation du subscriber global.
+
+## Tests instructifs
+
+- `enabled_routes_keep_all_configured_outputs` vérifie l’installation multi-routes ;
+- `route_writer_filter_preserves_target_and_level_semantics` vérifie l’admission finale ;
+- `more_than_64_routes_compose_without_filtered_layer_ids` couvre un volume élevé de routes ;
+- `every_tracing_crate_exposes_canonical_targets` vérifie la cohérence des targets du workspace.
+
+## Limites
+
+- initialisation globale unique par processus ;
+- configuration fournie par l’appelant ;