epitech-tracker — Runbook¶

Distinguer panne flotte entière et panne poste isolé

Ce sont deux problèmes de nature différente. Une panne flotte entière est presque toujours côté Zeno (dépôt distinct) ; ce dépôt ne peut alors rien réparer directement — seul le repli local (queue hors-ligne) protège les données en attendant. Une panne poste isolé se répare sur ce poste.

Cas 1 — Plus aucun poste ne reporte (panne flotte entière)¶

Symptômes¶

Aucun nouveau snapshot ne remonte côté Zeno/plateforme parentale, sur plusieurs postes distincts en même temps.
Sur un poste au hasard : journalctl -u epitech-tracker montre des snapshots mis en queue en boucle, pas d'erreur d'identité spécifique à ce poste.

Étape 1 — Confirmer que c'est bien fleet-wide et pas un faux positif¶

# Sur 2-3 postes différents si possible
systemctl status epitech-tracker
journalctl -u epitech-tracker --since "20 minutes ago" | tail -30

Chercher un pattern commun : Hors ligne, Rejeté (401), Rejeté (403), Erreur serveur (5xx).

Étape 2 — Vérifier Zeno directement¶

curl -s -o /dev/null -w "%{http_code}\n" https://zeno.epitech.africa/sonde/version
curl -s -o /dev/null -w "%{http_code}\n" https://zeno.epitech.africa/api/sonde/ingest -X POST

Si Zeno ne répond pas ou renvoie du 5xx de façon persistante : c'est une panne du projet Zeno, hors périmètre de ce dépôt. Escalader vers l'équipe/le contact responsable de Zeno — ce runbook ne couvre pas son diagnostic interne (voir sa propre documentation, si elle existe dans son dépôt).

Étape 3 — Le parc protège les données automatiquement, mais avec une limite dans le temps¶

Aucune action urgente côté tracker n'est requise pour une panne courte (quelques heures à quelques jours) : chaque poste continue de mettre ses snapshots en queue localement (/var/lib/epitech-tracker/queue/, src/queue_manager.py), et les rejoue automatiquement dès que Zeno répond 201 à nouveau (sender.flush_queue()).

La fenêtre de sécurité est de 7 jours OU 50 Mo, selon ce qui arrive en premier

Passé ce seuil, queue_manager.purge_old() et _enforce_size_limit() suppriment les fichiers les plus anciens silencieusement (pas d'alerte remontée). Une panne Zeno de plus d'une semaine cause une perte de données réelle sur les postes les plus actifs (ceux qui remplissent 50 Mo plus vite). Si l'incident dure, prévenir l'équipe pédagogique que la période sera incomplète pour les postes concernés plutôt que de laisser croire à une continuité parfaite.

Étape 4 — Une fois Zeno rétabli¶

Rien à faire côté postes : le cycle suivant (au plus 5 minutes après le rétablissement) tente un envoi direct puis vide la queue accumulée dans l'ordre chronologique. Vérifier sur un échantillon de postes que la queue redescend :

watch -n 30 'ls /var/lib/epitech-tracker/queue/ | wc -l'

Cas 2 — Un seul poste ne reporte plus¶

Étape 1 — Diagnostic initial¶

systemctl status epitech-tracker

Résultat	Signification	Aller à
`active (running)`, logs normaux	Le service tourne — le problème est en amont (identité, réseau, détection)	Étape 2
`failed` / crash loop (`NRestarts` élevé récemment)	Le process plante ou a atteint `StartLimitBurst`	Étape 3
Service absent (`Unit epitech-tracker.service could not be found`)	Le paquet n'est pas installé / a été purgé	Étape 4

Étape 2 — Le service tourne mais ne reporte pas¶

sudo cat /etc/epitech-tracker/identity.json
journalctl -u epitech-tracker --since "30 minutes ago" | grep -iE "non enrôlée|rejeté|hors ligne"

identity.json absent ou vide → le poste n'est pas (ou plus) enrôlé. Voir Étape 4 (ré-enrôlement) — c'est le cas typique d'un laptop réimagé : la réinstallation d'Ubuntu efface /etc/epitech-tracker/, mais le paquet lui-même doit être réinstallé après coup.
Rejets 401/403 répétés sur ce poste seulement → suspecter une clé désynchronisée côté serveur pour ce deviceId précis, ou une horloge système décalée (timedatectl status, comparer à l'heure réelle) — corriger l'horloge, puis vérifier que les rejets cessent.
Aucune ligne dans les logs depuis longtemps → passer à l'Étape 3, le process est probablement bloqué ou n'a pas redémarré après un crash.

Étape 3 — Le service crashe ou est en échec¶

journalctl -u epitech-tracker --since "1 hour ago" | grep -iE "traceback|exception"
systemctl show epitech-tracker -p NRestarts -p ActiveState

Le code applicatif encapsule déjà chaque cycle dans un try/except générique (main.py) — une exception dans detector/observer/sender est loguée (log.exception) mais ne fait pas planter le service. Un failed réel est donc plus probablement dû à une erreur au démarrage (import cassé, config.py invalide après une modification manuelle) qu'à un cycle de collecte.
Si StartLimitBurst=5 a été atteint (5 crashs en 60 secondes), systemd cesse de redémarrer automatiquement :
```
sudo systemctl reset-failed epitech-tracker
sudo systemctl restart epitech-tracker
```
Vérifier ensuite que ça ne re-crashe pas immédiatement avant de laisser le poste.

Étape 4 — Laptop réimagé / poste jamais enrôlé / ré-enrôlement nécessaire¶

Un poste réimagé (nouvel Ubuntu, ou apt purge epitech-tracker suivi d'une réinstallation) n'a plus d'identité. postinst refuse d'installer le paquet tant que identity.json n'existe pas — la seule voie normale est de repasser par le script d'installation qui enrôle avant d'installer :

curl -fsSL https://zeno.epitech.africa/sonde/install.sh | sudo bash

Le script (dans l'ordre) : demande prénom/nom, enrôle le poste et affiche le nom reconnu pour confirmation, écrit identity.json + tracker.env, télécharge le paquet et vérifie son sha256, installe, vérifie que le service tourne.

Ré-enrôlement d'un poste déjà installé (ex : clé compromise, ou changement de propriétaire du laptop) :

sudo rm /etc/epitech-tracker/identity.json
curl -fsSL https://zeno.epitech.africa/sonde/install.sh | sudo bash

L'enrôlement est idempotent : relancer sur la même machine avec la même déclaration rend le même deviceId et la même clé, sans doublon côté serveur.

Pas de notion de MAC ou de matériel à faire correspondre

Contrairement à ce que suggère une phrase de contexte du README (voir overview.md), l'identité d'un poste n'est pas liée à son adresse MAC ou à son matériel. Un changement de carte réseau, de disque, ou même un remplacement complet du laptop physique n'a aucun impact tant que identity.json est présent et valide — et inversement, une simple réinstallation d'Ubuntu sur le même matériel efface l'identité et exige un ré-enrôlement.

Étape 5 — Watcher AT-SPI bloqué (app active toujours "unknown")¶

journalctl -u epitech-tracker | grep -i "windowwatcher" | tail -20

Si le watchdog a atteint ses 10 tentatives et abandonné (WindowWatcher abandonné après 10 tentatives), un simple restart du service suffit une fois la session graphique de l'étudiant active :

sudo systemctl restart epitech-tracker

Publier une nouvelle version¶

Voir overview.md § Packaging pour le détail du mécanisme. Procédure :

# 1. Bumper la version — DANS LES DEUX FICHIERS, build.sh refuse sinon
#    src/config.py           → TRACKER_VERSION = "x.y.z"
#    package/DEBIAN/control  → Version: x.y.z

# 2. Builder
cd tracker/
./build.sh
# → epitech-tracker_x.y.z_all.deb, tools.deb, tools.deb.version, tools.deb.sha256

# 3. Déposer dans le conteneur API Zeno (accès VPS requis — voir continuite-acces-externes.md)
docker cp tools.deb epitech-api-prod:/app/public/sonde/tools.deb
docker cp tools.deb.version epitech-api-prod:/app/public/sonde/tools.deb.version

# 4. Taguer pour l'archive — déclenche .github/workflows/release.yml
git tag vx.y.z
git push --tags

Déployer Zeno AVANT de publier un paquet qui change le contrat

Depuis la 1.1.0, la sonde n'envoie plus de catégorie d'activité — un serveur Zeno antérieur à ce changement ne saurait pas la calculer. Vérifier que le déploiement serveur correspondant est en place avant de pousser une version de la sonde qui suppose ce contrat.

Migrer un reliquat de parc encore en 1.0.x¶

Les postes installés avant la 1.1.0 ont un updater qui interroge api.github.com/repos/YemalinModeste/epitech-tools (dépôt public personnel, pas celui de l'organisation) et ignorent Zeno — ils ne verront jamais les versions publiées normalement. Pour les faire basculer une dernière fois :

Lancer manuellement le workflow Build & Release (workflow_dispatch) avec l'option mirror_public activée.
Une fois confirmé que le parc concerné a basculé, laisser cette option désactivée pour tous les runs suivants — publier l'artefact d'un outil institutionnel sur un dépôt public personnel n'est pas une situation à pérenniser (commentaire du workflow lui-même).

Rollback d'une version défectueuse¶

Il n'existe pas de mécanisme de rollback automatique poussé aux postes. En cas de version défectueuse déjà publiée :

Rebuilder l'ancienne version (checkout du tag précédent) et la publier normalement sur /sonde/tools.deb + /sonde/version (côté Zeno) — les postes la récupéreront au prochain check horaire, exactement comme une mise à jour normale (l'updater ne fait pas de distinction montée/rétrogradation, il compare juste des numéros de version : publier un numéro supérieur à la version défectueuse, même si le contenu revient en arrière, pour que la comparaison _parse_version déclenche bien la mise à jour).

Sur un poste précis en urgence, réinstallation manuelle possible en levant l'immuabilité au préalable :

sudo chattr -i /usr/lib/systemd/system/epitech-tracker.service
sudo chattr -R -i /opt/epitech-tracker/
sudo dpkg -i /chemin/vers/epitech-tracker_<version_precedente>_all.deb

Contacts¶

Rôle	Contact
Développeur & Mainteneur	YemalinModeste — yemalin1.agbangla@epitech.eu
Repo	EpitechAfrik/epitech-tracker
API cible (Zeno)	projet distinct — escalader séparément en cas de panne serveur