50 lines
1.8 KiB
Markdown
50 lines
1.8 KiB
Markdown
<!-- file: docs/guides/LOGGING.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# Guide de logging et tracing
|
|
|
|
## Objectif
|
|
|
|
`ks-logging` possède le contrat logging, son document de profils, son schéma JSON et l'initialisation runtime `tracing`.
|
|
|
|
## Valeur globale
|
|
|
|
La racine des logs n'est pas un profil :
|
|
|
|
```text
|
|
logging.config.json.logs_directory = ${KS_LOGS_DIRECTORY:-logs}
|
|
```
|
|
|
|
Les targets fichier utilisent des chemins relatifs, par exemple `devnet/ks-pipeline/debug.log`. `ks-logging` les résout sous `logs_directory` au chargement. Une valeur absolue explicite reste absolue.
|
|
|
|
Cette séparation évite de recopier `logs/` dans chaque profil et permet à l'opérateur de déplacer tous les logs par variable d'environnement ou `.env`.
|
|
|
|
## Sélection du profil
|
|
|
|
`logging.config.json` définit `default_profile`. Un consommateur autonome l'utilise avec `default_logging_profile`.
|
|
|
|
Un binaire possédant une composition peut sélectionner un autre profil avec `logging_profile`; cette sélection ne modifie pas le document partagé.
|
|
|
|
## Flux de démarrage desktop
|
|
|
|
1. charger la composition `config/kb-app-demo-desktop.default.config.json` ;
|
|
2. résoudre le chemin `logging` référencé ;
|
|
3. charger `logging.config.json` ;
|
|
4. choisir l'override du profil ou son `default_profile` ;
|
|
5. résoudre les paths sous `logs_directory` ;
|
|
6. appeler `ks_logging::init_logging` ;
|
|
7. poursuivre l'initialisation du runtime.
|
|
|
|
`KS_LOGGING_CONFIG_PATH` remplace le chemin du document et `KS_LOGS_DIRECTORY` remplace uniquement sa racine de sortie.
|
|
|
|
## Sécurité
|
|
|
|
Les logs ne doivent jamais exposer :
|
|
|
|
- une valeur `KS_SECRET_*` ou `KB_SECRET_*` ;
|
|
- un DSN avec credentials ;
|
|
- une clé privée/keypair ;
|
|
- une configuration runtime complète résolue.
|
|
|
|
Le masquage structurel et les DTO diagnostics sûrs sont finalisés dans la prochaine prerelease de `0.5.1`.
|