<!-- file: docs/guides/LOGGING.md -->
<!-- version: 6 -->

# Guide de logging et tracing

## Objectif

`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 `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 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),
};
```

Le document logging reste indépendant de la composition binaire. Une composition `<binary>.default.config.json` sélectionne explicitement le profil logging qu’elle veut utiliser ; le `active_profile` propre à `logging.config.json` reste disponible pour les consommateurs autonomes.

## 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 :

- sink console ou fichier ;
- niveau minimal ;
- format humain, compact, pretty ou JSON ;
- rotation ;
- targets exactes ou préfixes ;
- activation ANSI.

Les routes fichier ne doivent jamais écrire de secrets ou de keypairs.

## Nomenclature des targets

Les targets suivent les conventions du workspace, par exemple :

```text
ks-pipeline.backfill
ks-pipeline.decode-replay
ks-onchain-transport.http
ks-lib-executor.spl.token-2022
ks-lib-materializer.compliance.audit
ks-lib-materializer.token.accounts
```

Pour un matérialisateur, la target de tracing reste distincte du `processorName` persisté.

## Frontend desktop

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 `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 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` ;
- `config/README.md` ;
- `docs/OPERATION_NAMING_CONVENTION.md`.