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

0.5.1-pre.005

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-10 01:36:42 +02:00
parent ec07ddbd80
commit b6a286a4df
54 changed files with 6236 additions and 5569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
ks-logging/USAGE.md
View File

@@ -1,9 +1,57 @@
<!-- file: ks-logging/USAGE.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Utilisation de ks-logging
## Initialisation
## 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 `config/logging.config.json` par défaut. `KS_LOGGING_CONFIG_PATH` peut sélectionner un autre document sans modifier `KS_CONFIG_PATH` ni le profil applicatif.
## 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 n’est jamais déduit de `app.config.json`. Un opérateur peut donc utiliser, par exemple, un profil applicatif `mainnet_research` avec un profil logging `local_devnet` ou tout autre profil logging explicitement défini.
## Construction directe
Les tests ou consommateurs spécialisés peuvent toujours construire directement `LoggingConfig` puis appeler `init_logging` :
```rust
let config = ks_logging::LoggingConfig {
@@ -17,7 +65,7 @@ let config = ks_logging::LoggingConfig {
rotation: "none".to_string(),
format: "compact".to_string(),
ansi: true,
targets: vec!["kb-*".to_string()],
targets: vec!["ks-*".to_string()],
}],
target_filters: Vec::new(),
};
@@ -27,16 +75,6 @@ let guard = match ks_logging::init_logging(&config) {
};
```
`init_logging` doit être appelée une seule fois par processus. Le `LoggingGuard` retourné doit rester vivant jusqu’à l’arrêt afin de ne pas interrompre les writers non bloquants.
## Inspection des routes
```rust
assert_eq!(guard.route_count(), 1);
assert_eq!(guard.guard_count(), 1);
assert_eq!(guard.route_names(), &["console".to_string()]);
```
## Route fichier JSON
```rust
@@ -49,76 +87,13 @@ let file_route = ks_logging::LogTargetConfig {
rotation: "daily".to_string(),
format: "json".to_string(),
ansi: false,
targets: vec![
"ks-pipeline*".to_string(),
"ks-onchain-transport*".to_string(),
],
};
let config = ks_logging::LoggingConfig {
default_level: "info".to_string(),
targets: vec![file_route],
target_filters: Vec::new(),
};
let guard = match ks_logging::init_logging(&config) {
Ok(value) => value,
Err(error) => return Err(error),
targets: vec!["ks-pipeline*".to_string()],
};
```
Pour une route `file`, `path` doit désigner le fichier cible et `rotation` doit être une valeur supportée (`none`, `never`, `daily` ou `hourly`). Les formats supportés sont `human`, `compact`, `pretty` et `json`.
Les rotations supportées sont `none`, `never`, `daily` et `hourly`. Les formats supportés sont `human`, `compact`, `pretty` et `json`.
## Filtres de targets
```rust
let config = ks_logging::LoggingConfig {
default_level: "warn".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!["kb-*".to_string()],
}],
target_filters: vec![
ks_logging::LogTargetFilterConfig {
target: "ks-pipeline".to_string(),
level: "debug".to_string(),
},
ks_logging::LogTargetFilterConfig {
target: "ks-store".to_string(),
level: "info".to_string(),
},
],
};
```
Les routes acceptent des targets exactes et des préfixes wildcard. Les `target_filters` ajoutent des niveaux spécifiques aux routes wildcard. Une route d’erreur conserve la sémantique stricte prévue par l’implémentation.
## Émission d’événements après initialisation
```rust
tracing::info!(
target: ks_logging::tracing_target(),
action = "startup",
"logging runtime initialized"
);
tracing::debug!(
target: "ks-pipeline.demo",
scenario = "token_2022",
"scenario preparation started"
);
```
Les targets doivent suivre la nomenclature canonique du workspace pour que les routes et filtres restent prévisibles.
## Inspection des routes actives
## Inspection des routes
```rust
for route_name in guard.route_names() {
@@ -132,6 +107,8 @@ assert_eq!(guard.route_count(), guard.route_names().len());
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 ;
@@ -139,12 +116,11 @@ Les erreurs utilisent `ks_core::Error`. Les cas principaux sont :
## Tests instructifs
- `enabled_routes_keep_all_configured_outputs` vérifie l’installation multi-routes ;
- `route_writer_filter_preserves_target_and_level_semantics` vérifie l’admission finale ;
- `more_than_64_routes_compose_without_filtered_layer_ids` couvre un volume élevé de routes ;
- `every_tracing_crate_exposes_canonical_targets` vérifie la cohérence des targets du workspace.
- 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 ;
- configuration fournie par l’appelant ;
- la politique de redaction des valeurs secrètes avant logging est renforcée dans `0.5.1-pre.006`.