0.5.1-pre.002

ks-logging/USAGE.md

@@ -0,0 +1,150 @@
+<!-- file: ks-logging/USAGE.md -->
+<!-- version: 4 -->
+
+# Utilisation de ks-logging
+
+## Initialisation
+
+```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!["kb-*".to_string()],
+    }],
+    target_filters: Vec::new(),
+};
+let guard = match ks_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()]);
+```
+
+## Route fichier JSON
+
+```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(),
+        "ks-onchain-transport*".to_string(),
+    ],
+};
+
+let config = ks_logging::LoggingConfig {
+    default_level: "info".to_string(),
+    targets: vec![file_route],
+    target_filters: Vec::new(),
+};
+
+let guard = match ks_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 = ks_logging::LoggingConfig {
+    default_level: "warn".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!["kb-*".to_string()],
+    }],
+    target_filters: vec![
+        ks_logging::LogTargetFilterConfig {
+            target: "ks-pipeline".to_string(),
+            level: "debug".to_string(),
+        },
+        ks_logging::LogTargetFilterConfig {
+            target: "ks-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: ks_logging::tracing_target(),
+    action = "startup",
+    "logging runtime initialized"
+);
+
+tracing::debug!(
+    target: "ks-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 `ks_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 ;