0.5.1-pre.005

docs/guides/LOGGING.md

@@ -1,34 +1,43 @@
 <!-- file: docs/guides/LOGGING.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Guide de logging et tracing
 
 ## Objectif
 
-`ks-logging` initialise les routes de tracing définies par la configuration et conserve les guards nécessaires à leur durée de vie.
+`ks-logging` possède désormais le contrat logging, son document de profils, son schéma JSON et l’initialisation runtime `tracing`.
 
 ## Flux de démarrage
 
-1. charger et valider la configuration avec `ks-config` ;
-2. construire `LoggingConfig` ;
+1. charger `config/logging.config.json` avec `ks_logging::read_logging_json_file_with_environment` ;
+2. sélectionner le profil avec `ks_logging::active_logging_profile` ;
 3. appeler `ks_logging::init_logging` une seule fois ;
 4. conserver `LoggingGuard` jusqu’à la fermeture du processus ;
 5. émettre les événements avec des targets canoniques.
 
 ```rust
-let guard = match ks_logging::init_logging(&config.logging) {
+let document = match ks_logging::read_logging_json_file_with_environment(
+    std::path::Path::new("config/logging.config.json"),
+    std::path::Path::new("."),
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+let config = match ks_logging::active_logging_profile(&document) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+let guard = match ks_logging::init_logging(config) {
     std::result::Result::Ok(value) => value,
     std::result::Result::Err(error) => return std::result::Result::Err(error),
 };
-
-tracing::info!(
-    target: ks_logging::tracing_target(),
-    routes = guard.route_count(),
-    "logging initialized"
-);
 ```
 
-## Routes
+Le profil logging est sélectionné indépendamment du profil général de `app.config.json`.
+
+## Contrat JSON
+
+Le schéma est `config/schemas/logging.config.schema.json`. Les exemples sont `config/logging.config.json` pour la configuration runtime de référence et `config/example.logging.config.json` pour un exemple minimal.
 
 Une route définit notamment :
 
@@ -52,28 +61,28 @@ ks-onchain-transport.http
 ks-lib-executor.spl.token-2022
 ks-lib-materializer.compliance.audit
 ks-lib-materializer.token.accounts
-ks-lib-materializer.transaction.annotations
 ```
 
-Pour un matérialisateur, la target de tracing est l’identité runtime `ks-lib-materializer.<domain>[.<subsystem>]`. Elle reste distincte du `processorName` persisté `materializer.<domain>[.<subsystem>]`, qui ne doit pas être utilisé comme target de logs.
-
-Une nouvelle target doit être ajoutée selon `docs/OPERATION_NAMING_CONVENTION.md` et les règles Khadhroony.
+Pour un matérialisateur, la target de tracing reste distincte du `processorName` persisté.
 
 ## Frontend desktop
 
-Les fenêtres Tauri utilisent la permission tracing prévue par leurs capabilities. Les logs frontend sont adaptés vers le backend sans permettre au frontend de choisir arbitrairement une target sensible.
+Le desktop charge les documents app et logging séparément. Il ne convertit plus un type `ks_config::LoggingConfig` vers `ks_logging::LoggingConfig` : le type runtime est possédé directement par `ks-logging`.
+
+La surface publique de diagnostic/configuration reste volontairement inchangée jusqu’à `0.5.1-pre.006`, qui supprimera l’exposition des configurations résolues complètes.
 
 ## Diagnostic
 
-- vérifier les routes actives via `route_names()` ;
+- vérifier `KS_LOGGING_CONFIG_PATH` si le fichier par défaut n’est pas utilisé ;
+- vérifier le profil logging actif indépendamment du profil app ;
+- valider le document contre son schéma ;
 - confirmer le niveau global et les filtres spécifiques ;
-- vérifier le chemin et les permissions d’une route fichier ;
-- vérifier que le guard n’est pas détruit prématurément ;
+- vérifier les chemins et permissions des routes fichier ;
 - ne pas réinitialiser le subscriber global pendant l’exécution.
 
 ## Références
 
 - `ks-logging/README.md` ;
 - `ks-logging/USAGE.md` ;
-- `ks-config/USAGE.md` ;
-- `docs/architecture/ARCHITECTURE.md`.
+- `config/README.md` ;
+- `docs/OPERATION_NAMING_CONVENTION.md`.