89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
<!-- 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`.
|