70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
<!-- file: ks-logging/USAGE.md -->
|
|
<!-- version: 9 -->
|
|
|
|
# Utilisation de ks-logging
|
|
|
|
## Chargement recommandé
|
|
|
|
```rust
|
|
let document = match ks_logging::read_logging_json_file_with_environment(
|
|
std::path::Path::new("config/logging.config.json"),
|
|
std::path::Path::new("."),
|
|
) {
|
|
Ok(value) => value,
|
|
Err(error) => return Err(error),
|
|
};
|
|
let config = match ks_logging::default_logging_profile(&document) {
|
|
Ok(value) => value,
|
|
Err(error) => return Err(error),
|
|
};
|
|
```
|
|
|
|
Le document possède :
|
|
|
|
```json
|
|
{
|
|
"logs_directory": "${KS_LOGS_DIRECTORY:-logs}",
|
|
"default_profile": "local_devnet",
|
|
"profiles": []
|
|
}
|
|
```
|
|
|
|
`logs_directory` n'appartient à aucun profil. Les paths relatifs des targets fichier sont résolus sous cette racine. Un path absolu reste inchangé.
|
|
|
|
## Override par composition
|
|
|
|
Une application peut sélectionner un autre profil avec :
|
|
|
|
```rust
|
|
let config = match ks_logging::logging_profile(&document, "mainnet_research") {
|
|
Ok(value) => value,
|
|
Err(error) => return Err(error),
|
|
};
|
|
```
|
|
|
|
Le `default_profile` reste le fallback autonome du document ; la sélection explicite d'une composition prime uniquement pour le consommateur concerné.
|
|
|
|
Le chemin du document peut être remplacé opérationnellement par `KS_LOGGING_CONFIG_PATH`. La racine des fichiers peut être remplacée indépendamment par `KS_LOGS_DIRECTORY`.
|
|
|
|
## Initialisation
|
|
|
|
Une fois le profil résolu :
|
|
|
|
```rust
|
|
match ks_logging::init_logging(&config) {
|
|
Ok(()) => (),
|
|
Err(error) => return Err(error),
|
|
}
|
|
```
|
|
|
|
L'initialisation reste globale au processus. Les binaires doivent donc résoudre leur configuration avant le premier appel à `init_logging`.
|
|
|
|
## Filtres des dépendances tierces
|
|
|
|
Les routes wildcard `debug` restent destinées aux composants Khadhroony, mais elles ne doivent pas transformer la console et `debug.log` en trace brute des bibliothèques réseau ou SQL.
|
|
|
|
Les profils standards imposent `WARN` aux targets `h2`, `hyper`, `hyper_util`, `rustls`, `rustls_platform_verifier` et `sqlx`. Les targets tiers restent ceux de leurs crates propriétaires : un événement HTTP/2 reste `h2::*`, un événement Hyper reste `hyper*`, un événement SQLx reste `sqlx::query` et un événement TLS reste `rustls::*`.
|
|
|
|
`ks-store` désactive en complément le statement logging automatique de SQLx. Les requêtes fonctionnellement importantes doivent être instrumentées par `ks-store` avec son target canonique et des champs structurés, sans dépendre du format de logging d'une bibliothèque tierce. Les warnings/errors des dépendances restent observables dans les profils standards.
|
|
|