218 lines
7.1 KiB
Markdown
218 lines
7.1 KiB
Markdown
<!-- file: crates/ksp-logging-lib/USAGE.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# Utilisation de ksp-logging-lib
|
|
|
|
## Target d'une crate consommatrice
|
|
|
|
Chaque crate KSP comportementale fournit explicitement son target, égal au nom Cargo de la crate :
|
|
|
|
```rust
|
|
const LOGGING_TARGET: &str = "ksp-store-lib";
|
|
|
|
ksp_logging_lib::trace!(
|
|
target: LOGGING_TARGET,
|
|
domain = "store",
|
|
component = "postgres",
|
|
operation = "load_transactions",
|
|
"executing store operation"
|
|
);
|
|
```
|
|
|
|
Les champs `domain`, `component`, `operation` et autres champs structurés sont ajoutés par le caller lorsqu'ils sont utiles ; ils ne remplacent pas le target propriétaire.
|
|
|
|
## Contrat des outputs
|
|
|
|
`LoggingSettings` possède :
|
|
|
|
- le `default_filter` global de takeover KSP ;
|
|
- les `TargetFilter` globaux ;
|
|
- la politique `SpanEvents` ;
|
|
- une console déclarée optionnellement ;
|
|
- zéro, un ou plusieurs `FileSettings`.
|
|
|
|
Chaque output possède un `OutputFilter` indépendant. Son niveau, ses targets et ses domains s'appliquent **en plus** de la politique globale. `*` signifie « tous » dans la dimension concernée.
|
|
|
|
Les formats publics sont :
|
|
|
|
```text
|
|
Human
|
|
Compact
|
|
Pretty
|
|
Json
|
|
```
|
|
|
|
Une sortie fichier possède un `output_id` stable et unique dans `LoggingSettings`. Cet identifiant appartient au runtime Logging et ne doit pas être confondu avec les `file_id` utilisés par `ksp-config-lib` pour identifier ses documents.
|
|
|
|
Les fichiers persistants interdisent `ansi = true`.
|
|
|
|
## Runtime multi-output de `pre.005`
|
|
|
|
`0.1.3-pre.005` active réellement :
|
|
|
|
- plusieurs fichiers simultanés ;
|
|
- les formats `Human`, `Compact`, `Pretty` et `Json` ;
|
|
- l'ANSI console ;
|
|
- le routing par niveau et target pour chaque output ;
|
|
- le comptage cumulatif des lignes abandonnées par `output_id` fichier ;
|
|
- le hot reload de ces sorties sans réinstaller le subscriber global.
|
|
|
|
Le routing `domain` est volontairement séparé. `OutputFilter` continue de représenter `domains[]`, mais un output actif dont cette dimension est différente de `["*"]` est refusé par `initialize/reinitialize` jusqu'à la tranche suivante. La configuration n'est donc jamais acceptée puis partiellement ignorée.
|
|
|
|
Les helpers `ConsoleSettings::stdout()` et `ConsoleSettings::stderr()` restent des raccourcis `Human`, sans ANSI et sans restriction supplémentaire par output.
|
|
|
|
## Initialisation
|
|
|
|
```rust
|
|
let file = ksp_logging_lib::FileSettings::new(
|
|
"file.worker",
|
|
true,
|
|
"logs",
|
|
"worker.log",
|
|
ksp_logging_lib::FileRotation::Daily,
|
|
ksp_logging_lib::LogFormat::Human,
|
|
ksp_logging_lib::OutputFilter::unrestricted(),
|
|
);
|
|
|
|
let settings = ksp_logging_lib::LoggingSettings::new(
|
|
ksp_logging_lib::LogFilterLevel::Info,
|
|
ksp_logging_lib::SpanEvents::NewAndClose,
|
|
std::option::Option::Some(ksp_logging_lib::ConsoleSettings::stderr()),
|
|
std::vec![file],
|
|
);
|
|
|
|
let initialize_result = ksp_logging_lib::initialize(&settings);
|
|
let mut logging_guard = match initialize_result {
|
|
std::result::Result::Ok(guard) => guard,
|
|
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
|
};
|
|
```
|
|
|
|
Une configuration sans output actif est valide et installe une infrastructure initialement silencieuse qui pourra être activée plus tard par hot reload.
|
|
|
|
## Construction d'un runtime multi-output
|
|
|
|
Le runtime peut maintenant activer plusieurs sorties ayant des formats et filtres metadata distincts :
|
|
|
|
```rust
|
|
let console = ksp_logging_lib::ConsoleSettings::new(
|
|
true,
|
|
ksp_logging_lib::ConsoleOutput::Stderr,
|
|
true,
|
|
ksp_logging_lib::LogFormat::Compact,
|
|
ksp_logging_lib::OutputFilter::new(
|
|
ksp_logging_lib::LogFilterLevel::Debug,
|
|
std::vec!["*".to_string()],
|
|
std::vec!["*".to_string()],
|
|
),
|
|
);
|
|
|
|
let error_file = ksp_logging_lib::FileSettings::new(
|
|
"file.config.error",
|
|
true,
|
|
"logs/config",
|
|
"error.jsonl",
|
|
ksp_logging_lib::FileRotation::Daily,
|
|
ksp_logging_lib::LogFormat::Json,
|
|
ksp_logging_lib::OutputFilter::new(
|
|
ksp_logging_lib::LogFilterLevel::Error,
|
|
std::vec!["ksp-config-lib".to_string()],
|
|
std::vec!["*".to_string()],
|
|
),
|
|
);
|
|
|
|
let settings = ksp_logging_lib::LoggingSettings::new(
|
|
ksp_logging_lib::LogFilterLevel::Warn,
|
|
ksp_logging_lib::SpanEvents::NewAndClose,
|
|
std::option::Option::Some(console),
|
|
std::vec![error_file],
|
|
);
|
|
|
|
let validation = settings.validate();
|
|
```
|
|
|
|
`validate()` vérifie le contrat structurel. `initialize/reinitialize` appliquent le niveau et les targets par output ; les domains spécifiques restent refusés jusqu'à la tranche de routing structuré.
|
|
|
|
## Hot reload
|
|
|
|
Une configuration peut être appliquée sans redémarrer le processus ou le worker :
|
|
|
|
```rust
|
|
let debug_settings = ksp_logging_lib::LoggingSettings::new(
|
|
ksp_logging_lib::LogFilterLevel::Info,
|
|
ksp_logging_lib::SpanEvents::NewAndClose,
|
|
std::option::Option::Some(ksp_logging_lib::ConsoleSettings::stderr()),
|
|
std::vec::Vec::new(),
|
|
)
|
|
.with_target_filter(ksp_logging_lib::TargetFilter::new(
|
|
"ksp-store-lib",
|
|
ksp_logging_lib::LogFilterLevel::Debug,
|
|
));
|
|
|
|
let reload_result = ksp_logging_lib::reinitialize(&mut logging_guard, &debug_settings);
|
|
if let std::result::Result::Err(error) = reload_result {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
```
|
|
|
|
La nouvelle configuration est préparée avant la bascule. Si sa validation ou la création d'un nouveau sink échoue, l'ancienne configuration reste active.
|
|
|
|
## Spans synchrones
|
|
|
|
```rust
|
|
let span = ksp_logging_lib::trace_span!(
|
|
target: LOGGING_TARGET,
|
|
"materialize_transaction",
|
|
domain = "store"
|
|
);
|
|
|
|
let output = span.in_scope(|| {
|
|
return materialize_transaction();
|
|
});
|
|
```
|
|
|
|
Avec `SpanEvents::NewAndClose`, le formatter produit les événements de création/fermeture et les temps `busy` / `idle` à la fermeture.
|
|
|
|
## Spans async
|
|
|
|
Une `Future` doit être instrumentée avec `ksp_logging_lib::instrument` ; un guard d'entrée de span ne doit pas être conservé à travers `.await` :
|
|
|
|
```rust
|
|
let span = ksp_logging_lib::trace_span!(
|
|
target: LOGGING_TARGET,
|
|
"fetch_account",
|
|
domain = "transport"
|
|
);
|
|
|
|
let output = ksp_logging_lib::instrument(span, fetch_account()).await;
|
|
```
|
|
|
|
La future instrumentée entre/sort du span pendant ses polls et lors de son `Drop`, conformément au contrat de la primitive `tracing` sous-jacente.
|
|
|
|
## Lignes abandonnées
|
|
|
|
Les sorties utilisent des queues lossy afin de ne pas appliquer de backpressure au hot path. La vue agrégée console/fichier reste disponible :
|
|
|
|
```rust
|
|
let dropped = logging_guard.dropped_lines();
|
|
ksp_logging_lib::warn!(
|
|
target: LOGGING_TARGET,
|
|
console = dropped.console(),
|
|
file = dropped.file(),
|
|
total = dropped.total(),
|
|
"logging queues dropped lines"
|
|
);
|
|
```
|
|
|
|
Pour un fichier précis :
|
|
|
|
```rust
|
|
let dropped_for_output = logging_guard.dropped_file_lines("file.worker");
|
|
```
|
|
|
|
Le compteur par `output_id` reste cumulatif à travers les hot reloads tant que le même `LoggingGuard` est conservé.
|
|
|
|
## Instrumentation async et executor
|
|
|
|
`instrument(span, future)` accepte une `Future` standard et ne dépend d'aucun executor particulier. Tokio n'est présent qu'en `dev-dependency` pour valider la surface sur un executor réel, y compris après plusieurs suspensions et sur un runtime multi-thread.
|