English: pump.py and pump.sh (ex pomper), lenzspitze_absolute.py, options --from/--to/--delay, out/pump.log; .env loaded with +u (pump.sh -h works)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-11-16 12:40:03 +01:00
1 parent 260cd5e522
commit 5ed9f5a97a
9 files changed
+531 -530

No files matched your search

+30 -30
View File
@@ -1,51 +1,51 @@
# extraction/ : pomper les données de la plateforme (lecture seule)
# extraction/: pumping the data of the platform (read-only)
`pomper.py` récupère, pour chaque station (numéro de série du système) et chaque jour UTC demandé, dans `data/<SERIE>/` :
- les **métriques système** (énergie, disque, 4G, températures…), moyennes horaires, un CSV par métrique et par jour dans `metrics/` ;
- les **déplacements** (export « advanced »), un CSV par jour dans `displacement/` ;
- les **mouvements de la caméra** (`pan`, `tilt`, `scale`, `rotation`, `sigma0`), en médiane et bornes (`median_`, `min_`, `max_`) par minute, aux seuls instants où la caméra a été recalée, un CSV par jour dans `camera/` ;
- les **images** IRON (`--images`, une par heure par défaut, `--every 10` ou `--every 0` pour plus) dans `images/`, et différentielles (`--diff`) dans `images_diff/`.
`pump.py` fetches, for each station (serial number of the system) and each UTC day asked, into `data/<SERIAL>/`:
- the **system metrics** (energy, disk, 4G, temperatures…), hourly means, one CSV per metric and per day in `metrics/`;
- the **displacements** ("advanced" export), one CSV per day in `displacement/`;
- the **camera movements** (`pan`, `tilt`, `scale`, `rotation`, `sigma0`), as median and bounds (`median_`, `min_`, `max_`) per minute, only at the times the camera was realigned, one CSV per day in `camera/`;
- the IRON **images** (`--images`, one per hour by default, `--every 10` or `--every 0` for more) in `images/`, and the differential ones (`--diff`) in `images_diff/`.
Formats : `~/labeling/connaissances/colonnes-des-deplacements.md`.
Formats: `~/labeling/knowledge/displacement-columns.md`.
**Stations suivies** : `stations.txt`, un numéro de série par ligne. Sans station ni dates, le script les met toutes à jour jusqu'à maintenant : chaque station comble d'abord ses jours manquants entre le premier et le dernier jour pompé (sans déplacements, ou sans aucune métrique), puis repart de son dernier jour, repompé (il était peut-être incomplet) ; une station sans dossier dans `data/` reçoit les 30 derniers jours.
**Tracked stations**: `stations.txt`, one serial number per line. Without station nor dates, the script updates them all up to now: each station first fills its missing days between the first and the last pumped day (without displacements, or without any metric), then restarts from its last day, pumped again (it was perhaps incomplete); a station without a folder in `data/` gets the last 30 days.
Reprise : avec `--du`, un fichier déjà dans `data/<SERIE>/` n'est pas redemandé ; relancer sur une plage plus large ne lit que les jours et les images qui manquent. Le jour en cours est pompé tel qu'il est, ses métriques jusqu'à la dernière heure terminée ; le lancement suivant sans `--du` le remplace.
Resuming: with `--from`, a file already in `data/<SERIAL>/` is not asked for again; running again on a wider range reads only the days and images that are missing. The current day is pumped as it is, its metrics up to the last completed hour; the next run without `--from` replaces it.
## Lancer (sous WSL)
## Running (under WSL)
`pomper.sh` lit les identifiants dans le `.env` à la racine du dépôt (base PostgreSQL et S3 ; jamais versionné, interdit en lecture à Claude), installe les 4 paquets nécessaires (`sqlalchemy`, `psycopg2-binary`, `pandas`, `boto3`) dans un environnement `uv` jetable (Python 3.12), lance `pomper.py`, puis `lenzspitze_absolu.py`. Sa sortie s'ajoute à `out/pompage.log` ; un second lancement pendant un pompage s'arrête aussitôt (verrou `out/pompage.lock`). Le verrou ne vaut que pour ce dossier : les autres dépôts lisent `data/` par un lien, ils ne pompent pas.
`pump.sh` reads the credentials from the `.env` at the root of the repository (PostgreSQL database and S3; never versioned, Claude may not read it), installs the 4 packages needed (`sqlalchemy`, `psycopg2-binary`, `pandas`, `boto3`) in a throwaway `uv` environment (Python 3.12), runs `pump.py`, then `lenzspitze_absolute.py`. Its output is appended to `out/pump.log`; a second run during a pumping stops at once (lock `out/pump.lock`). The lock holds for this folder only: the other repositories read `data/` through a link, they do not pump.
Variables du `.env` : `AIMSIGHT_DATABASE_USER`, `_PSWD`, `_TURL`, `_NAME`, `_PORT` ; pour les images, `AIMSIGHT_S3_URL`, `_ACCESS_KEY`, `_SECRET_KEY`, `_BUCKET`.
Variables of the `.env`: `AIMSIGHT_DATABASE_USER`, `_PSWD`, `_TURL`, `_NAME`, `_PORT`; for the images, `AIMSIGHT_S3_URL`, `_ACCESS_KEY`, `_SECRET_KEY`, `_BUCKET`.
1. **Un essai** (1 station, 2 jours, dans un dossier jetable) : `extraction/pomper.sh --du 2026-11-09 --au 2026-11-11 --images --out /tmp/essai-pompage NORDEND` (6 s le 2026-11-12). `lenzspitze_absolu.py` convertit ensuite `data/LENZSPITZE`, pas le dossier `--out` : sans effet si `data/LENZSPITZE` est déjà converti.
2. **Mettre à jour les stations suivies** : `extraction/pomper.sh` (sans argument : `--images --delai 300`), ou la tâche VS Code **pomper**. Le script dit, pour chaque station, la plage qu'il pompe.
3. **Une plage choisie** (historique, jour en échec), avec 3 jours de plus avant (l'historique des détecteurs) : `extraction/pomper.sh --du 2026-10-02 --au 2026-10-26 --images <SERIE>` (`--au` exclu ; plusieurs stations : `<SERIE1> <SERIE2>`). Aide : `extraction/pomper.sh -h`.
1. **A trial** (1 station, 2 days, in a throwaway folder): `extraction/pump.sh --from 2026-11-09 --to 2026-11-11 --images --out /tmp/pump-trial NORDEND` (6 s on 2026-11-12). `lenzspitze_absolute.py` then converts `data/LENZSPITZE`, not the `--out` folder: no effect if `data/LENZSPITZE` is already converted.
2. **Updating the tracked stations**: `extraction/pump.sh` (without argument: `--images --delay 300`), or the VS Code task **pump**. The script says, for each station, the range it pumps.
3. **A chosen range** (history, failed day), with 3 more days before (the history of the detectors): `extraction/pump.sh --from 2026-10-02 --to 2026-10-26 --images <SERIAL>` (`--to` excluded; several stations: `<SERIAL1> <SERIAL2>`). Help: `extraction/pump.sh -h`.
**Chaque nuit, automatiquement** : une tâche du Planificateur de tâches de Windows, à créer une fois dans PowerShell (pas en administrateur). Elle démarre WSL au besoin et, PC éteint ou en veille à l'heure dite, part dès qu'il se rallume ; un jour manqué est rattrapé au lancement suivant.
**Every night, automatically**: a task of the Windows Task Scheduler, to create once in PowerShell (not as administrator). It starts WSL if needed and, PC off or asleep at the set time, runs as soon as it wakes up; a missed day is caught up at the next run.
```powershell
$a = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-d Ubuntu -e bash -lc /home/maxime/aimsight-data/extraction/pomper.sh"
$a = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-d Ubuntu -e bash -lc /home/maxime/aimsight-data/extraction/pump.sh"
$t = New-ScheduledTaskTrigger -Daily -At 04:00
$s = New-ScheduledTaskSettingsSet -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Hours 6)
Register-ScheduledTask -TaskName "AIMsight pompage" -Action $a -Trigger $t -Settings $s
Register-ScheduledTask -TaskName "AIMsight pump" -Action $a -Trigger $t -Settings $s
```
Essayer la tâche tout de suite : `Start-ScheduledTask "AIMsight pompage"`, puis lire `out/pompage.log`. La retirer : `Unregister-ScheduledTask "AIMsight pompage"`.
Trying the task right away: `Start-ScheduledTask "AIMsight pump"`, then read `out/pump.log`. Removing it: `Unregister-ScheduledTask "AIMsight pump"`.
Lecture seule : moteur dédié, `default_transaction_read_only`, délai de 60 s par requête, une requête par jour ; hors des heures chargées (base partagée avec la production).
Read-only: dedicated engine, `default_transaction_read_only`, 60 s timeout per query, one query per day; outside busy hours (database shared with production).
Sans dépendance à l'appli `monitoring-dashboard` : ses lectures sont recopiées dans `pomper.py`, en SQL (sa docstring dit lesquelles, et de quel commit). Si l'appli change ses lectures, le script ne suit pas : comparer à nouveau des fichiers pompés aux deux.
No dependency on the `monitoring-dashboard` app: its reads are copied into `pump.py`, in SQL (its docstring says which ones, and from which commit). If the app changes its reads, the script does not follow: compare again files pumped by both.
## Avec Claude
## With Claude
Claude peut lancer `pomper.sh` lui-même (accord de l'utilisateur, 2026-11-12) : lecture seule, petites plages ; une longue plage ou un historique, hors des heures chargées. Il ne lit jamais le `.env`.
Claude may run `pump.sh` itself (user's agreement, 2026-11-12): read-only, small ranges; a long range or a history, outside busy hours. It never reads the `.env`.
## À savoir
## Good to know
- `<SERIE>` est le numéro de série du **système**, celui de l'URL de la page System (`/explore/system/<SERIE>`) et du début des CSV qu'on y télécharge (`NORDEND_BusVoltage_…` : `NORDEND`) ; pas le nom de l'appareil de la page Explore.
- `data/` est hors de git : un dossier perdu se repompe.
- Un jour en échec par délai dépassé (`QueryCanceled: … statement timeout`) : le relancer seul avec `--delai 300`. La lenteur vient de la base, pas du volume.
- Une heure sans image peut avoir sa mesure : l'image n'est jamais arrivée sur S3 (`measurement_uuid` vide, envoi inachevé). Le script la saute et prend l'image suivante de la tranche s'il y en a une.
- Un jour passé, pompé avant que la station ait fini d'envoyer ses données (coupure, synchronisation en retard), reste incomplet : supprimer ses fichiers dans `data/<SERIE>/` et relancer.
- LENZSPITZE : ses exports ont `x` / `y` relatifs et `pattern_type` vide ; `pomper.sh` lance ensuite `lenzspitze_absolu.py` (provisoire ; détail dans `~/labeling/connaissances/colonnes-des-deplacements.md`).
- `<SERIAL>` is the serial number of the **system**, the one in the URL of the System page (`/explore/system/<SERIAL>`) and at the start of the CSVs downloaded there (`NORDEND_BusVoltage_…`: `NORDEND`); not the name of the device on the Explore page.
- `data/` is out of git: a lost folder is pumped again.
- A day failed on a timeout (`QueryCanceled: … statement timeout`): run it again alone with `--delay 300`. The slowness comes from the database, not from the volume.
- An hour without an image can have its measurement: the image never reached S3 (empty `measurement_uuid`, unfinished upload). The script skips it and takes the next image of the slot if there is one.
- A past day, pumped before the station had finished sending its data (outage, late synchronisation), stays incomplete: delete its files in `data/<SERIAL>/` and run again.
- LENZSPITZE: its exports have relative `x` / `y` and an empty `pattern_type`; `pump.sh` then runs `lenzspitze_absolute.py` (provisional; details in `~/labeling/knowledge/displacement-columns.md`).