127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
<!-- file: ks-logging/USAGE.md -->
|
||
<!-- version: 6 -->
|
||
|
||
# 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::active_logging_profile(&document) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
let guard = match ks_logging::init_logging(config) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
```
|
||
|
||
Le desktop utilise normalement le chemin déclaré dans sa composition `config/kb-app-demo-desktop.default.config.json`. `KS_LOGGING_CONFIG_PATH` peut encore remplacer explicitement ce chemin sans modifier le fichier de composition.
|
||
|
||
## Format du document
|
||
|
||
```json
|
||
{
|
||
"active_profile": "local_devnet",
|
||
"profiles": [
|
||
{
|
||
"name": "local_devnet",
|
||
"default_level": "info",
|
||
"targets": [],
|
||
"target_filters": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Le schéma formel est `config/schemas/logging.config.schema.json`. `config/example.logging.config.json` fournit un exemple minimal conforme avec des routes valides.
|
||
|
||
`targets` doit contenir au moins une route et au moins une route doit être activée.
|
||
|
||
## Sélection indépendante
|
||
|
||
Le `active_profile` logging reste le défaut autonome du document. Lorsqu’un binaire utilise une composition, il sélectionne explicitement son `logging_profile` avec `ks_logging::logging_profile`; cette sélection prime pour ce binaire sans modifier le document partagé.
|
||
|
||
## Construction directe
|
||
|
||
Les tests ou consommateurs spécialisés peuvent toujours construire directement `LoggingConfig` puis appeler `init_logging` :
|
||
|
||
```rust
|
||
let config = ks_logging::LoggingConfig {
|
||
default_level: "info".to_string(),
|
||
targets: vec![ks_logging::LogTargetConfig {
|
||
name: "console".to_string(),
|
||
enabled: true,
|
||
sink: "console".to_string(),
|
||
level: "info".to_string(),
|
||
path: String::new(),
|
||
rotation: "none".to_string(),
|
||
format: "compact".to_string(),
|
||
ansi: true,
|
||
targets: vec!["ks-*".to_string()],
|
||
}],
|
||
target_filters: Vec::new(),
|
||
};
|
||
let guard = match ks_logging::init_logging(&config) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
```
|
||
|
||
## Route fichier JSON
|
||
|
||
```rust
|
||
let file_route = ks_logging::LogTargetConfig {
|
||
name: "operations-json".to_string(),
|
||
enabled: true,
|
||
sink: "file".to_string(),
|
||
level: "debug".to_string(),
|
||
path: "logs/operations.jsonl".to_string(),
|
||
rotation: "daily".to_string(),
|
||
format: "json".to_string(),
|
||
ansi: false,
|
||
targets: vec!["ks-pipeline*".to_string()],
|
||
};
|
||
```
|
||
|
||
Les rotations supportées sont `none`, `never`, `daily` et `hourly`. Les formats supportés sont `human`, `compact`, `pretty` et `json`.
|
||
|
||
## Inspection des routes
|
||
|
||
```rust
|
||
for route_name in guard.route_names() {
|
||
println!("active logging route: {route_name}");
|
||
}
|
||
|
||
assert_eq!(guard.route_count(), guard.route_names().len());
|
||
```
|
||
|
||
## Erreurs
|
||
|
||
Les erreurs utilisent `ks_core::Error`. Les cas principaux sont :
|
||
|
||
- document ou schéma invalide ;
|
||
- profil actif absent ou dupliqué ;
|
||
- aucune route activée ;
|
||
- sink, format, rotation ou niveau inconnu ;
|
||
- chemin fichier invalide ;
|
||
- échec d’initialisation du subscriber global.
|
||
|
||
## Tests instructifs
|
||
|
||
- les tests de `document` vérifient les deux fichiers logging versionnés et les profils indépendants ;
|
||
- `default_logging_config_routes_global_and_operational_crate_files` vérifie les routes canoniques ;
|
||
- les tests de `tracing_runtime` vérifient l’installation, les filtres et le volume de routes.
|
||
|
||
## Limites
|
||
|
||
- initialisation globale unique par processus ;
|
||
- la politique de redaction des valeurs secrètes avant logging est renforcée dans `0.5.1-pre.006`.
|