v0.1.3-pre.005

crates/ksp-logging-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-logging-lib/USAGE.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Utilisation de ksp-logging-lib
 
@@ -46,15 +46,22 @@ Une sortie fichier possède un `output_id` stable et unique dans `LoggingSetting
 
 Les fichiers persistants interdisent `ansi = true`.
 
-## Compatibilité runtime de `pre.004`
+## Runtime multi-output de `pre.005`
 
-`0.1.3-pre.004` étend d'abord le **contrat public**. Le runtime multi-sink/routing est livré séparément en `pre.005`.
+`0.1.3-pre.005` active réellement :
 
-Jusqu'à cette tranche suivante, `initialize`/`reinitialize` refusent explicitement toute capacité nouvellement représentée qu'ils ne savent pas encore appliquer : plusieurs fichiers actifs, format non `Human`, ANSI console ou filtre propre à un output. Ces valeurs ne sont donc jamais acceptées puis ignorées silencieusement.
+- plusieurs fichiers simultanés ;
+- les formats `Human`, `Compact`, `Pretty` et `Json` ;
+- l'ANSI console ;
+- le routing par niveau et target pour chaque output ;
+- le comptage cumulatif des lignes abandonnées par `output_id` fichier ;
+- le hot reload de ces sorties sans réinstaller le subscriber global.
 
-Les helpers `ConsoleSettings::stdout()` et `ConsoleSettings::stderr()` construisent une console compatible avec le runtime actuel : activée, `Human`, sans ANSI et sans filtre supplémentaire par rapport au takeover global.
+Le routing `domain` est volontairement séparé. `OutputFilter` continue de représenter `domains[]`, mais un output actif dont cette dimension est différente de `["*"]` est refusé par `initialize/reinitialize` jusqu'à la tranche suivante. La configuration n'est donc jamais acceptée puis partiellement ignorée.
 
-## Initialisation compatible avec le runtime actuel
+Les helpers `ConsoleSettings::stdout()` et `ConsoleSettings::stderr()` restent des raccourcis `Human`, sans ANSI et sans restriction supplémentaire par output.
+
+## Initialisation
 
 ```rust
 let file = ksp_logging_lib::FileSettings::new(
@@ -83,9 +90,9 @@ let mut logging_guard = match initialize_result {
 
 Une configuration sans output actif est valide et installe une infrastructure initialement silencieuse qui pourra être activée plus tard par hot reload.
 
-## Construction d'un contrat multi-output
+## Construction d'un runtime multi-output
 
-Le contrat public peut déjà représenter la future configuration Config complète :
+Le runtime peut maintenant activer plusieurs sorties ayant des formats et filtres metadata distincts :
 
 ```rust
 let console = ksp_logging_lib::ConsoleSettings::new(
@@ -110,7 +117,7 @@ let error_file = ksp_logging_lib::FileSettings::new(
     ksp_logging_lib::OutputFilter::new(
         ksp_logging_lib::LogFilterLevel::Error,
         std::vec!["ksp-config-lib".to_string()],
-        std::vec!["config".to_string()],
+        std::vec!["*".to_string()],
     ),
 );
 
@@ -124,11 +131,11 @@ let settings = ksp_logging_lib::LoggingSettings::new(
 let validation = settings.validate();
 ```
 
-`validate()` vérifie le contrat structurel. L'activation runtime de ce routage enrichi appartient à `pre.005`.
+`validate()` vérifie le contrat structurel. `initialize/reinitialize` appliquent le niveau et les targets par output ; les domains spécifiques restent refusés jusqu'à la tranche de routing structuré.
 
 ## Hot reload
 
-Une configuration compatible avec les capacités runtime actives peut être appliquée sans redémarrer le processus ou le worker :
+Une configuration peut être appliquée sans redémarrer le processus ou le worker :
 
 ```rust
 let debug_settings = ksp_logging_lib::LoggingSettings::new(
@@ -184,7 +191,7 @@ La future instrumentée entre/sort du span pendant ses polls et lors de son `Dro
 
 ## Lignes abandonnées
 
-Les sorties utilisent des queues lossy afin de ne pas appliquer de backpressure au hot path. Les compteurs restent encore agrégés console/fichier pendant `pre.004` ; leur généralisation par output appartient au runtime multi-sink :
+Les sorties utilisent des queues lossy afin de ne pas appliquer de backpressure au hot path. La vue agrégée console/fichier reste disponible :
 
 ```rust
 let dropped = logging_guard.dropped_lines();
@@ -197,6 +204,14 @@ ksp_logging_lib::warn!(
 );
 ```
 
+Pour un fichier précis :
+
+```rust
+let dropped_for_output = logging_guard.dropped_file_lines("file.worker");
+```
+
+Le compteur par `output_id` reste cumulatif à travers les hot reloads tant que le même `LoggingGuard` est conservé.
+
 ## Instrumentation async et executor
 
 `instrument(span, future)` accepte une `Future` standard et ne dépend d'aucun executor particulier. Tokio n'est présent qu'en `dev-dependency` pour valider la surface sur un executor réel, y compris après plusieurs suspensions et sur un runtime multi-thread.