64a864bfaa
Python 3, bibliothèque standard seule. unix:// par défaut (unix:///run/powersync/optimizer.sock), tcp:// accepté ; token lu dans un fichier (--token-file), jamais en argument ni affiché. Réponses écrites à côté de la trace, jamais d'écrasement ; résumé : requêtes, taux d'abstention, computeMs médian et max, cycles non comparables, cycles dont les actions du créneau courant diffèrent du plan enregistré. --fail-on-divergence : code 1. Test (unittest) contre un serveur Unix minimal qui renvoie les réponses enregistrées (ce n'est pas l'optimiseur de référence) : trace synthétique et trois traces réelles du moteur → zéro divergence ; réponse modifiée → divergence vue, code 1 ; tcp://, refus d'écraser, endpoint absent. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
43 lines
2.3 KiB
Markdown
43 lines
2.3 KiB
Markdown
# tools/
|
|
|
|
Outils de développement et d'exploitation du plugin. Ce fichier ne décrit que
|
|
`etm-powersync-trace-replay` ; les autres scripts portent leur mode d'emploi en en-tête.
|
|
|
|
## `etm-powersync-trace-replay` — rejouer des traces de décision
|
|
|
|
Python 3, bibliothèque standard seule, GPL-3.0 comme le dépôt.
|
|
|
|
Le moteur écrit, quand le réglage `optimizerTrace` est activé (`NymeaEnergy.SetOptimizerTrace`,
|
|
défaut : désactivé), une ligne NDJSON par cycle dans
|
|
`<storagePath>/etm-powersync-optimizer-trace-AAAA-MM-JJ.ndjson` (format :
|
|
`INTERFACE.md`, « Traces de décision » ; protocole : `docs/OPTIMIZER_PROTOCOL.md` annexe D).
|
|
L'outil renvoie chaque `request` d'un de ces fichiers à un optimiseur et compare ses actions au
|
|
plan enregistré.
|
|
|
|
```sh
|
|
# optimiseur local (défaut : unix:///run/powersync/optimizer.sock)
|
|
./tools/etm-powersync-trace-replay etm-powersync-optimizer-trace-2026-10-17.ndjson
|
|
|
|
# optimiseur sur le LAN, avec token, échec si une action diffère
|
|
./tools/etm-powersync-trace-replay trace.ndjson --endpoint tcp://nas:7600 \
|
|
--token-file ~/.config/etm-optimizer.token --fail-on-divergence
|
|
```
|
|
|
|
- **Token** : seulement par `--token-file` (jamais en argument : il se verrait dans `ps`).
|
|
Il n'est ni affiché ni écrit.
|
|
- **Sorties** : `<trace>.replay-<horodatage>.ndjson` (une ligne par requête rejouée : réponse,
|
|
latence, écarts) et `….summary.txt`, à côté de la trace. Jamais d'écrasement (`--out` vers un
|
|
fichier existant est refusé).
|
|
- **Résumé** : requêtes rejouées, taux d'abstention, `computeMs` médian et max (s'il est fourni
|
|
dans `diagnostics`), cycles non comparables (réponse enregistrée en erreur), cycles dont les
|
|
actions du créneau courant diffèrent du plan enregistré, avec la liste.
|
|
- **Code de sortie** : 0 ; 1 avec `--fail-on-divergence` s'il y a divergence ; 2 sur erreur
|
|
(fichier, connexion, handshake refusé).
|
|
- Les lignes L2 (`strategy: "none"`) n'ont pas de requête : elles ne sont pas rejouées.
|
|
|
|
Les traces contiennent des mesures du site : elles **restent sur le site**. L'export est manuel
|
|
(copie du fichier par l'installateur) ; l'outil ne parle qu'à l'endpoint donné.
|
|
|
|
Test : `python3 -I tests/tools/etm-powersync-trace-replay-test.py` (serveur de test minimal qui
|
|
renvoie les réponses enregistrées — ce n'est pas l'optimiseur de référence).
|