<!-- 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`.