0.5.1-pre.002

ks-logging/CHANGELOG.md

@@ -0,0 +1,61 @@
+<!-- file: ks-logging/CHANGELOG.md -->
+<!-- version: 12 -->
+
+# CHANGELOG — ks-logging
+
+## `0.5.1-pre.002`
+
+- renomme `kb-logging` en `ks-logging` et `kb_logging` en `ks_logging` ;
+- aligne le target racine obligatoire sur `ks-logging` et adapte les tests/routes liés au nom de package ;
+- reporte les identités hiérarchiques `kb-lib.*` à `pre.003`.
+
+## `0.5.0-pre.002`
+
+- confirme le futur document et schéma logging indépendants de la configuration généraliste ;
+- identifie la duplication `LoggingConfig`/`LogTargetConfig`/`LogTargetFilterConfig` avec `ks-config` et la conversion manuelle du desktop comme dette à supprimer en `0.5.1` ;
+- classe `LogFileRoute` comme contrat legacy sans consommateur actif à réévaluer avant restructuration.
+
+## 0.4.6
+
+- alignement de la crate sur la version fonctionnelle bot3 `0.4.6` ;
+- clôture des tâches de migration applicables et report explicite des évolutions ultérieures dans le TODO.
+
+## 0.1.0-pre.073
+
+- ajout du guide transversal [`docs/guides/LOGGING.md`](../docs/guides/LOGGING.md) ;
+
+## 0.1.0-pre.072
+
+- reclassement du TODO selon les blocants avant `0.4.6`, les travaux `0.4.7`, les versions ultérieures et les dépendances conditionnelles.
+
+## 0.1.0-pre.070
+
+- enrichissement de `USAGE.md` avec plusieurs exemples couvrant les familles d’API publiques significatives.
+
+## 0.1.0-pre.069
+
+### Documentation
+
+- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
+- réécriture du README selon la séparation bot3 entre configuration et runtime logging ;
+- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
+- retrait des travaux futurs du changelog ;
+- réécriture de `TODO.md` sous forme de tâches uniquement ;
+- correction de `USAGE.md` pour ne conserver que les contraintes runtime durables.
+
+## 0.1.0
+
+### Migré
+
+- migration du runtime de logging et tracing depuis bot2 ;
+- consolidation des routes console/fichier, formats, rotations et filtres de targets.
+
+### Modifié
+
+- adoption des règles Rust 2024 et Khadhroony ;
+- erreurs structurées via `ks_core::Error` ;
+- conservation explicite des guards non bloquants.
+
+### Validation
+
+- tests des routes, formats, niveaux, wildcards, writers et targets canoniques du workspace.

ks-logging/Cargo.toml

@@ -0,0 +1,18 @@
+# file: ks-logging/Cargo.toml
+# version: 3
+
+[package]
+name = "ks-logging"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[dependencies]
+ks-core = { path = "../ks-core" }
+tracing.workspace = true
+tracing-appender.workspace = true
+tracing-subscriber.workspace = true
+
+[lints]
+workspace = true

ks-logging/README.md

@@ -0,0 +1,38 @@
+<!-- file: ks-logging/README.md -->
+<!-- version: 5 -->
+
+# ks-logging
+
+`ks-logging` initialise le subscriber global `tracing` à partir d’une configuration de routes explicites vers la console ou des fichiers.
+
+## Responsabilités
+
+- sélectionner les routes activées ;
+- appliquer niveaux, targets exactes et préfixes wildcard ;
+- créer les writers non bloquants ;
+- gérer les formats human, compact, pretty et JSON ;
+- gérer les rotations de fichiers supportées ;
+- conserver les `WorkerGuard` pendant toute la durée du processus.
+
+## Hors périmètre
+
+La crate ne charge pas actuellement le fichier de configuration et ne définit pas les targets des autres crates. Le cadrage `0.5.0-pre.002` confirme qu’un document logging séparé sera introduit en `0.5.1`; la propriété exacte du DTO source sera fixée sans faire dépendre la configuration générale du runtime tracing.
+
+## API publique
+
+- `init_logging` initialise le subscriber global ;
+- `LoggingConfig`, `LogTargetConfig` et `LogTargetFilterConfig` décrivent les routes ;
+- `LoggingGuard` maintient les writers et expose les routes installées ;
+- `tracing_target` retourne le target canonique de la crate ;
+- `LogFileRoute` reste disponible pour les anciens appelants file-only.
+
+## Statut
+
+L’initialisation multi-routes est fonctionnelle. Elle échoue explicitement si aucune route n’est activée ou si le subscriber global a déjà été initialisé.
+
+## Documents
+
+- [Utilisation](USAGE.md)
+- [Travaux restants](TODO.md)
+- [Historique](CHANGELOG.md)
+- [Guide de configuration](../ks-config/USAGE.md)

ks-logging/TODO.md

@@ -0,0 +1,14 @@
+<!-- file: ks-logging/TODO.md -->
+<!-- version: 5 -->
+
+# TODO — ks-logging
+
+## Série `0.5.x`
+
+- [ ] `0.5.1` - consommer un document logging et un schéma distincts de la configuration généraliste.
+- [ ] `0.5.1` - définir avec `ks-config` un propriétaire unique du DTO source logging sans coupler `ks-config` au runtime tracing.
+- [ ] `0.5.1` - supprimer la conversion champ par champ actuellement portée par le desktop.
+- [ ] Compatibilité - préserver targets, niveaux, filtres, formats, routes et sémantique wildcard pendant la migration.
+- [ ] Contrat - réévaluer `LogFileRoute`, actuellement sans consommateur actif hors de la crate.
+- [ ] Tests - ajouter les tests d’API externe et de migration du futur format logging.
+- [ ] Documentation - mettre à jour les exemples après implémentation du nouveau chargement.

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 ;

ks-logging/src/config.rs

@@ -0,0 +1,58 @@
+// file: ks-logging/src/config.rs
+// version: 5
+
+//! Logging configuration data structures consumed by the tracing runtime.
+
+/// Legacy file route shape kept for early callers that only need human file logs.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LogFileRoute {
+    /// Output file path.
+    pub file: std::string::String,
+    /// Logging level filter.
+    pub level: std::string::String,
+    /// Target filters handled by this route.
+    pub targets: std::vec::Vec<std::string::String>,
+}
+
+/// One target-level filter shared by routes that include the wildcard target.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LogTargetFilterConfig {
+    /// Tracing target or crate prefix.
+    pub target: std::string::String,
+    /// Minimum level assigned to this target.
+    pub level: std::string::String,
+}
+
+/// One logging output route.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LogTargetConfig {
+    /// Route name used for diagnostics.
+    pub name: std::string::String,
+    /// Enables this route.
+    pub enabled: bool,
+    /// Sink kind: `console` or `file`.
+    pub sink: std::string::String,
+    /// Minimum level for this route.
+    pub level: std::string::String,
+    /// File path for file sinks, empty for console sinks.
+    pub path: std::string::String,
+    /// Rotation mode: `none`, `never`, `daily`, or `hourly`.
+    pub rotation: std::string::String,
+    /// Format kind: `human`, `compact`, `pretty`, or `json`.
+    pub format: std::string::String,
+    /// Enables ANSI formatting for this route.
+    pub ansi: bool,
+    /// Included tracing targets or wildcard target globs.
+    pub targets: std::vec::Vec<std::string::String>,
+}
+
+/// Logging configuration consumed by `ks-logging` before profile binding exists.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LoggingConfig {
+    /// Default log level used when a route does not provide target directives.
+    pub default_level: std::string::String,
+    /// Output routes.
+    pub targets: std::vec::Vec<crate::LogTargetConfig>,
+    /// Target-specific overrides appended to wildcard routes.
+    pub target_filters: std::vec::Vec<crate::LogTargetFilterConfig>,
+}

ks-logging/src/constants.rs

@@ -0,0 +1,5 @@
+// file: ks-logging/src/constants.rs
+// version: 3
+
+/// Canonical tracing target for this crate.
+pub(crate) const TRACING_TARGET: &str = "ks-logging";

ks-logging/src/lib.rs

@@ -0,0 +1,31 @@
+// file: ks-logging/src/lib.rs
+// version: 7
+
+//! Logging and tracing initialization for applications and workers.
+#![warn(missing_docs)]
+#![deny(unreachable_pub)]
+#![forbid(unsafe_code)]
+
+mod config;
+mod constants;
+mod tracing_runtime;
+
+/// Canonical tracing target for this crate.
+pub(crate) use self::constants::TRACING_TARGET;
+
+/// Exposes the legacy file route shape kept for early file-only callers.
+pub use self::config::LogFileRoute;
+/// Exposes one configured logging output target.
+pub use self::config::LogTargetConfig;
+/// Exposes one configured tracing target filter.
+pub use self::config::LogTargetFilterConfig;
+/// Exposes the logging configuration consumed by this crate.
+pub use self::config::LoggingConfig;
+/// Exposes the guard that keeps non-blocking logging workers alive.
+pub use self::tracing_runtime::LoggingGuard;
+/// Exposes initialization from a raw logging configuration section.
+pub use self::tracing_runtime::init_logging;
+/// Returns the canonical tracing target.
+pub fn tracing_target() -> &'static str {
+    return crate::TRACING_TARGET;
+}