107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
<!-- file: docs/LOGGING.md -->
|
||
<!-- version: 9 -->
|
||
|
||
# Logging
|
||
|
||
La journalisation est centralisée dans `kb_logging` et repose sur des événements `tracing` structurés.
|
||
|
||
## Objectifs
|
||
|
||
- séparer console, fichiers globaux et fichiers par crate ;
|
||
- conserver un fichier JSONL dédié aux erreurs ;
|
||
- retrouver immédiatement un échec de décodage ou de matérialisation ;
|
||
- corréler RPC, pipeline, store et processor sans dupliquer les décisions dans Tauri ;
|
||
- activer le debug d’une crate sans dépendre de son découpage interne en modules.
|
||
|
||
## Arborescence d’un profil
|
||
|
||
Pour un profil stocké sous `logs/<profile>/`, la configuration crée :
|
||
|
||
```text
|
||
logs/<profile>/debug.log
|
||
logs/<profile>/info.log
|
||
logs/<profile>/error.jsonl
|
||
logs/<profile>/app.log
|
||
logs/<profile>/<crate>/debug.log
|
||
logs/<profile>/<crate>/info.log
|
||
logs/<profile>/<crate>/error.jsonl
|
||
```
|
||
|
||
Les routes sont en rotation quotidienne. `tracing-appender` insère la date dans le nom physique produit à partir du préfixe et du suffixe configurés.
|
||
|
||
Les niveaux sont cumulatifs :
|
||
|
||
- `debug.log` reçoit `debug`, `info`, `warn` et `error` ;
|
||
- `info.log` reçoit `info`, `warn` et `error` ;
|
||
- `error.jsonl` reçoit uniquement `error` ;
|
||
- `app.log` reçoit les événements `kb_app_demo` à partir de `debug`.
|
||
|
||
`error.jsonl` utilise le format JSON pour permettre la recherche par champ. Les autres fichiers utilisent le format humain sans ANSI.
|
||
|
||
## Targets canoniques
|
||
|
||
Le target est le nom exact de la crate hors `kb-lib`. Dans `kb-lib`, il suit la hiérarchie du composant :
|
||
|
||
```text
|
||
kb_app_demo
|
||
kb_decoder_solana_core
|
||
kb_executor_metadata_spl_name_service
|
||
kb_executor_solana_core
|
||
kb_executor_spl_account_compression
|
||
kb_executor_spl_memo
|
||
kb_executor_spl_noop
|
||
kb_executor_spl_single_pool
|
||
kb_logging
|
||
kb-lib.materializer.admin
|
||
kb-lib.materializer.compliance
|
||
kb-lib.materializer.lifecycle
|
||
kb-lib.materializer.staking
|
||
kb_pipeline
|
||
kb_onchain_transport
|
||
kb_store_pg
|
||
```
|
||
|
||
La granularité passe par les champs `action`, `stage`, `window`, `campaign_id`, `signature`, `instruction_path`, `program_id`, `processor_name`, `status` et `error_code`.
|
||
|
||
## Corrélation de campagne
|
||
|
||
Les campagnes de backfill, extraction core et replay decode utilisent des identifiants stables :
|
||
|
||
```text
|
||
capture_session_id
|
||
campaign_id
|
||
signature
|
||
slot
|
||
instruction_path
|
||
program_id
|
||
input_key
|
||
input_hash
|
||
processor_name
|
||
processor_version
|
||
```
|
||
|
||
Le pipeline journalise la sélection et l’agrégation. Le RPC journalise le transport et l’endpoint sélectionné sans exposer l’URL secrète. Le store journalise la persistance et les rollbacks. Le décodeur et chacun des matérialiseurs lifecycle, admin et compliance audit journalisent leur décision propre.
|
||
|
||
## Fichier d’erreurs
|
||
|
||
Les erreurs de décodage et de matérialisation sont émises au niveau `error` par la crate responsable, puis éventuellement par la frontière qui constate l’échec terminal. Elles apparaissent donc dans :
|
||
|
||
- `logs/<profile>/error.jsonl` ;
|
||
- `logs/<profile>/<crate>/error.jsonl`.
|
||
|
||
Cette duplication volontaire fournit une vue globale et une vue isolée par composant. Les champs de corrélation permettent de regrouper les événements d’un même défaut.
|
||
|
||
Une transaction on-chain échouée mais correctement décodée n’est pas écrite dans `error.jsonl` uniquement à cause de `meta.err`. En revanche, un payload déclaré compatible mais `failed` ou `unsupported` indique une lacune du code ou une évolution du protocole et doit être visible dans le fichier d’erreurs.
|
||
|
||
## Frontend et Tauri
|
||
|
||
Le frontend peut continuer à transmettre un identifiant logique tel que `kb_app_demo.frontend.demo_decode_replay`. Le backend le valide et le conserve dans le champ `frontend_target`, mais l’événement est émis avec le target canonique `kb_app_demo`.
|
||
|
||
`kb_app_demo` ne doit pas recopier les détails internes d’un retry RPC, d’un parsing binaire ou d’un commit SQL. Il journalise l’invocation, la progression visible et le résumé reçu de la crate opérationnelle.
|
||
|
||
## Sécurité
|
||
|
||
Les logs ne contiennent jamais de clé privée, seed phrase, DSN non masqué, URL fournisseur secrète ou payload complet non borné. Pour un payload problématique, conserver la taille, un préfixe borné et un SHA-256.
|
||
|
||
Le contrat normatif complet se trouve dans `docs/TRACING_CONTRACT.md`.
|