Ecrire l'agent local de collecte (agent/push-metrics.js + run-push.sh) #15

New issue

Closed

opened 2026-08-15 20:10:16 +00:00 by maximus · 0 comments

maximus commented

2026-08-15 20:10:16 +00:00

Owner

Fichiers concernes

agent/push-metrics.js (creer)
agent/run-push.sh (creer)
agent/README.md (creer)

Depends on

#13 (contrat de payload)

Criteres d'acceptation

push-metrics.js reutilise collectMetrics() de metrics.js, POST avec timeout de 10 s, sortie en code non nul et message clair en cas d'echec
Aucune file d'attente ni rejeu : un battement manque est remplace par le suivant
run-push.sh source ~/.config/maximus-host-agent.env (chmod 600) et s'arrete proprement si HOSTS_API_URL, HOSTS_INGEST_TOKEN ou HOST_ID manque
Le chemin d'erreur ne journalise QUE err.code et le code HTTP — jamais les options de requete ni les en-tetes ; set -x interdit dans run-push.sh
Un test assure que le message d'echec ne contient aucune sous-chaine du token
agent/README.md documente l'installation sur un nouveau poste : fichier env, ligne de crontab, essai a blanc, et le fait que deux postes partageant le meme HOST_ID s'ecrasent mutuellement (signal a surveiller : un hostname qui change a chaque tour)
agent/ reste hors de l'image Docker (verifier le COPY)

Review caveats

SECURITE (MEDIUM) : run-push.sh pipe sa sortie vers logger -t host-agent. Un handler d'echec qui dumpe les options de requete ou un objet d'erreur portant l'en-tete Authorization persiste le token dans /var/log/syslog et journald.
ARCHITECTURE (MEDIUM) : partager metrics.js ne garantit PAS l'absence de derive en production — le serveur se deploie par trigger manuel et l'agent tournerait depuis un working tree. Le cron doit pointer vers une copie figee (~/.local/share/maximus-host-agent/), pas vers le depot. La vraie garantie du contrat reste la validation de payload cote serveur.

Decisions prises en planification

Node natif 0-dep des deux cotes (le poste est en Node v22.22.0, l'image en node:22-alpine).
Probe faite en planification : sur Node 22, os.freemem() retourne MemAvailable (7,8 G) et non MemFree (0,8 G) — le calcul de getHealth() est donc juste sur un poste charge de cache page, aucune lecture manuelle de /proc/meminfo n'est necessaire.

Spec source

la-compagnie-maximus/spec-plan-monitoring-postes.md + spec-decisions-monitoring-postes.md (depot different : ce body est auto-suffisant, ne pas compter sur le fichier) (Issue 5)

Agent 0-dependance qui collecte les metriques du poste et les pousse vers l'API. Tourne par cron toutes les 5 minutes sur le ThinkPad. L'installation reelle (fichier env, crontab) releve de l'issue de mise en service, pas de celle-ci. ## Fichiers concernes - `agent/push-metrics.js` (creer) - `agent/run-push.sh` (creer) - `agent/README.md` (creer) ## Depends on - #13 (contrat de payload) ## Criteres d'acceptation - [ ] `push-metrics.js` reutilise `collectMetrics()` de `metrics.js`, POST avec timeout de 10 s, sortie en code non nul et message clair en cas d'echec - [ ] Aucune file d'attente ni rejeu : un battement manque est remplace par le suivant - [ ] `run-push.sh` source `~/.config/maximus-host-agent.env` (chmod 600) et s'arrete proprement si `HOSTS_API_URL`, `HOSTS_INGEST_TOKEN` ou `HOST_ID` manque - [ ] Le chemin d'erreur ne journalise QUE `err.code` et le code HTTP — jamais les options de requete ni les en-tetes ; `set -x` interdit dans `run-push.sh` - [ ] Un test assure que le message d'echec ne contient aucune sous-chaine du token - [ ] `agent/README.md` documente l'installation sur un nouveau poste : fichier env, ligne de crontab, essai a blanc, et le fait que deux postes partageant le meme `HOST_ID` s'ecrasent mutuellement (signal a surveiller : un `hostname` qui change a chaque tour) - [ ] `agent/` reste hors de l'image Docker (verifier le `COPY`) ## Review caveats - SECURITE (MEDIUM) : `run-push.sh` pipe sa sortie vers `logger -t host-agent`. Un handler d'echec qui dumpe les options de requete ou un objet d'erreur portant l'en-tete `Authorization` persiste le token dans `/var/log/syslog` et journald. - ARCHITECTURE (MEDIUM) : partager `metrics.js` ne garantit PAS l'absence de derive en production — le serveur se deploie par trigger manuel et l'agent tournerait depuis un working tree. Le cron doit pointer vers une copie figee (`~/.local/share/maximus-host-agent/`), pas vers le depot. La vraie garantie du contrat reste la validation de payload cote serveur. ## Decisions prises en planification - Node natif 0-dep des deux cotes (le poste est en Node v22.22.0, l'image en node:22-alpine). - Probe faite en planification : sur Node 22, `os.freemem()` retourne `MemAvailable` (7,8 G) et non `MemFree` (0,8 G) — le calcul de `getHealth()` est donc juste sur un poste charge de cache page, aucune lecture manuelle de `/proc/meminfo` n'est necessaire. ## Spec source la-compagnie-maximus/spec-plan-monitoring-postes.md + spec-decisions-monitoring-postes.md (depot different : ce body est auto-suffisant, ne pas compter sur le fichier) (Issue 5)