v0.1.2-pre.005

crates/ksp-logging-lib/USAGE.md

@@ -0,0 +1,118 @@
+<!-- file: crates/ksp-logging-lib/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de ksp-logging-lib
+
+## Target d'une crate consommatrice
+
+Chaque crate KSP comportementale fournit explicitement son target, égal au nom Cargo de la crate :
+
+```rust
+const LOGGING_TARGET: &str = "ksp-store-lib";
+
+ksp_logging_lib::trace!(
+    target: LOGGING_TARGET,
+    domain = "store",
+    component = "postgres",
+    operation = "load_transactions",
+    "executing store operation"
+);
+```
+
+Les champs `domain`, `component`, `operation` et autres champs structurés sont ajoutés par le caller lorsqu'ils sont utiles ; ils ne remplacent pas le target propriétaire.
+
+## Initialisation
+
+`initialize` installe le subscriber global KSP une seule fois et retourne le `LoggingGuard` qui doit rester vivant pendant la durée du runtime :
+
+```rust
+let settings = ksp_logging_lib::LoggingSettings::new(
+    ksp_logging_lib::LogFilterLevel::Info,
+    ksp_logging_lib::SpanEvents::NewAndClose,
+    std::option::Option::Some(ksp_logging_lib::ConsoleSettings::stderr()),
+    std::option::Option::Some(ksp_logging_lib::FileSettings::new(
+        "logs",
+        "worker.log",
+        ksp_logging_lib::FileRotation::Daily,
+    )),
+);
+
+let initialize_result = ksp_logging_lib::initialize(&settings);
+let mut logging_guard = match initialize_result {
+    std::result::Result::Ok(guard) => guard,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+Une configuration sans console ni fichier est valide et installe une infrastructure initialement silencieuse qui pourra être activée plus tard par hot reload.
+
+## Hot reload
+
+Une nouvelle configuration peut être appliquée sans redémarrer le processus ou le worker :
+
+```rust
+let debug_settings = ksp_logging_lib::LoggingSettings::new(
+    ksp_logging_lib::LogFilterLevel::Info,
+    ksp_logging_lib::SpanEvents::NewAndClose,
+    std::option::Option::Some(ksp_logging_lib::ConsoleSettings::stderr()),
+    std::option::Option::None,
+)
+.with_target_filter(ksp_logging_lib::TargetFilter::new(
+    "ksp-store-lib",
+    ksp_logging_lib::LogFilterLevel::Debug,
+));
+
+let reload_result = ksp_logging_lib::reinitialize(&mut logging_guard, &debug_settings);
+if let std::result::Result::Err(error) = reload_result {
+    return std::result::Result::Err(error);
+}
+```
+
+La nouvelle configuration est préparée avant la bascule. Si sa validation ou la création d'un nouveau sink échoue, l'ancienne configuration reste active.
+
+## Spans synchrones
+
+```rust
+let span = ksp_logging_lib::trace_span!(
+    target: LOGGING_TARGET,
+    "materialize_transaction",
+    domain = "store"
+);
+
+let output = span.in_scope(|| {
+    return materialize_transaction();
+});
+```
+
+Avec `SpanEvents::NewAndClose`, le formatter produit les événements de création/fermeture et les temps `busy` / `idle` à la fermeture.
+
+## Spans async
+
+Une `Future` doit être instrumentée avec `ksp_logging_lib::instrument` ; un guard d'entrée de span ne doit pas être conservé à travers `.await` :
+
+```rust
+let span = ksp_logging_lib::trace_span!(
+    target: LOGGING_TARGET,
+    "fetch_account",
+    domain = "transport"
+);
+
+let output = ksp_logging_lib::instrument(span, fetch_account()).await;
+```
+
+La future instrumentée entre/sort du span pendant ses polls et lors de son `Drop`, conformément au contrat de la primitive `tracing` sous-jacente.
+
+## Lignes abandonnées
+
+Les sorties utilisent des queues lossy afin de ne pas appliquer de backpressure au hot path. Les pertes restent observables :
+
+```rust
+let dropped = logging_guard.dropped_lines();
+ksp_logging_lib::warn!(
+    target: LOGGING_TARGET,
+    console = dropped.console(),
+    file = dropped.file(),
+    total = dropped.total(),
+    "logging queues dropped lines"
+);
+```