Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.5.1-pre.007

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-10 09:28:57 +02:00
parent 34a670eaec
commit a2820062eb
81 changed files with 3357 additions and 2381 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
docs/guides/LOGGING.md
View File

@@ -1,88 +1,49 @@
<!-- file: docs/guides/LOGGING.md -->
<!-- version: 6 -->
<!-- version: 7 -->
# 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`.
`ks-logging` possède le contrat logging, son document de profils, son schéma JSON et l'initialisation runtime `tracing`.
## Flux de démarrage
## Valeur globale
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 :
La racine des logs n'est pas un profil :
```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
logging.config.json.logs_directory = ${KS_LOGS_DIRECTORY:-logs}
```
Pour un matérialisateur, la target de tracing reste distincte du `processorName` persisté.
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.
## Frontend desktop
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`.
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`.
## Sélection du profil
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.
`logging.config.json` définit `default_profile`. Un consommateur autonome l'utilise avec `default_logging_profile`.
## Diagnostic
Un binaire possédant une composition peut sélectionner un autre profil avec `logging_profile`; cette sélection ne modifie pas le document partagé.
- 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.
## Flux de démarrage desktop
## Références
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/README.md` ;
- `ks-logging/USAGE.md` ;
- `config/README.md` ;
- `docs/OPERATION_NAMING_CONVENTION.md`.
`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`.