Aller au contenu

Dépannage et investigation de CMonChoix

Cette page donne une méthode pour comprendre un problème avant de le corriger. Elle est conçue pour une personne qui reprend le projet et ne sait pas encore où chercher lorsqu'un comportement paraît anormal.

Le principe le plus important

Quand quelque chose ne fonctionne pas, ne pas commencer par modifier des fichiers ou la base de données.

Commencer par établir des faits.

Observer
  ↓
Qualifier
  ↓
Isoler
  ↓
Formuler une hypothèse
  ↓
Vérifier
  ↓
Corriger
  ↓
Revalider

Une correction appliquée trop tôt peut masquer la vraie cause et rendre le diagnostic beaucoup plus difficile.

Petit lexique

Symptôme

Ce que l'on observe : page vide, produit mal classé, run bloqué, erreur 500, image absente, etc.

Cause

Le mécanisme réellement responsable du symptôme.

Hypothèse

Une explication possible qui doit encore être vérifiée.

Périmètre

La partie réellement touchée : un produit, un feed, un marchand, une verticale, un run ou l'ensemble du site.

Reproductible

Un problème est reproductible lorsqu'on peut le faire apparaître à nouveau dans des conditions connues.

Étape 1 — Décrire le symptôme précisément

Éviter les formulations comme :

« le site bug »

Préférer :

« la page produit X répond en HTTP 200 mais affiche une image différente de celle attendue depuis le dernier rebuild »

Noter :

  • l'heure ;
  • l'URL ou le produit concerné ;
  • le marchand ou feed concerné ;
  • le dernier run connu ;
  • ce qui était attendu ;
  • ce qui est observé ;
  • si le problème touche tout le monde ou un seul cas.

Étape 2 — Vérifier l'état général

Avant d'aller dans le code :

make doctor

Puis, selon le problème, vérifier l'état Docker et les logs du composant concerné.

Si le diagnostic global échoue, identifier précisément quelle section échoue avant de poursuivre.

Étape 3 — Identifier la couche responsable

Le site ne répond plus

Regarder d'abord :

  • Docker ;
  • WordPress ;
  • Nginx/proxy ;
  • MariaDB ;
  • ressources système.

C'est probablement un problème technique ou Runtime/Infrastructure.

Une synchronisation ne démarre pas ou reste bloquée

Regarder :

  • Runtime ;
  • worker ;
  • cron ;
  • run state ;
  • verrous et reprises.

Voir Runtime.

Les données importées sont mauvaises

Regarder :

  • feed source ;
  • staging ;
  • mapping ;
  • normalisation ;
  • règles verticales.

Voir Pipeline.

Un produit est mal identifié

Regarder :

  • preuves normalisées ;
  • candidats ;
  • Resolver ;
  • règles de conflit ;
  • identité canonique.

Voir Identité canonique.

Les données sont correctes mais l'affichage est mauvais

Regarder :

  • projection consommée ;
  • cache éventuel ;
  • Frontend ;
  • CSS/JS si le problème est uniquement visuel.

Voir Frontend.

Étape 4 — Remonter le chemin de la donnée

Pour un problème métier, suivre la donnée de l'affichage vers sa source :

Frontend
   ↑
Projection
   ↑
Décision métier
   ↑
Données normalisées
   ↑
Mapping / staging
   ↑
Feed marchand

Le premier niveau où la donnée devient incorrecte indique généralement la responsabilité à investiguer.

Exemple

Une capacité de stockage affichée est fausse.

  • Si la projection contient déjà la mauvaise valeur, le Frontend n'est probablement pas responsable.
  • Si le mapping contient la bonne valeur mais la normalisation la change mal, chercher dans la normalisation.
  • Si la source marchande elle-même est erronée, le système peut avoir besoin d'une règle d'exception ou doit conserver l'incertitude selon le contrat.

Étape 5 — Préserver les preuves

Avant une correction sensible, conserver ce qui permettra de comparer avant/après :

  • logs pertinents ;
  • identifiant de run ;
  • extraits de données ;
  • métriques ;
  • capture du résultat ;
  • commit courant.

Ne pas supprimer ou écraser les éléments nécessaires à l'analyse.

Étape 6 — Formuler une hypothèse testable

Une bonne hypothèse doit pouvoir être invalidée.

Exemple :

« Le produit est mal classé parce que la règle de category routing reçoit Tablets mais la normalisation la convertit en Smartphone. »

On peut alors vérifier les données avant et après cette étape.

Une mauvaise hypothèse serait :

« Ça doit être le cache. »

sans preuve ni test précis.

Étape 7 — Tester sans modifier si possible

Privilégier :

  • audits ;
  • Read Services ;
  • simulations ;
  • comparaisons ;
  • requêtes SQL de lecture ;
  • tests automatiques ;
  • reproduction sur un échantillon contrôlé.

Éviter de tester une hypothèse en modifiant directement la production.

Étape 8 — Corriger une seule cause à la fois

Une fois la cause démontrée :

  1. identifier la bonne couche ;
  2. vérifier ses invariants ;
  3. ajouter ou mettre à jour les tests ;
  4. appliquer le changement ;
  5. reconstruire ou rejouer uniquement ce qui est nécessaire ;
  6. comparer avant/après ;
  7. vérifier qu'aucun autre périmètre n'a régressé.

Plusieurs corrections simultanées rendent impossible de savoir laquelle a réellement résolu le problème.

Problèmes fréquents et première direction de recherche

Symptôme Première zone à vérifier
Site inaccessible Docker / WordPress / DB / proxy
Run non démarré Runtime / worker / cron
Run en erreur logs Runtime + étape Pipeline concernée
Volume de feed anormal acquisition / source marchand
Mauvaise catégorie mapping / classification / category routing
Mauvaise identité evidence / candidates / resolver
Mauvaise image projection / Media Quality / source image
Donnée correcte en DB, mauvaise à l'écran projection consommée / Frontend / cache
Donnée différente après reprise idempotence / état de run / batch
Dégradation générale dernier changement + métriques + audit

Ce tableau donne un point de départ, pas une conclusion automatique.

Lire la base sans la modifier

Une requête SELECT correctement construite est généralement un outil de diagnostic en lecture.

À l'inverse, considérer avec prudence toute commande contenant :

INSERT
UPDATE
DELETE
TRUNCATE
DROP
ALTER

Ces opérations peuvent modifier ou supprimer des données.

Si l'objectif est seulement de comprendre un problème, commencer par une voie read-only.

Quand faut-il penser au rollback ?

Un rollback peut être pertinent lorsqu'une régression est clairement liée au dernier changement et que revenir au commit stable restaure le comportement sans incompatibilité de données.

Mais un rollback de code ne restaure pas une base qui a été modifiée destructivement.

Voir Déploiement et Sauvegarde/restauration.

Après la correction

La résolution n'est pas terminée tant que l'on n'a pas vérifié :

  • que le symptôme a disparu ;
  • que la cause identifiée est bien corrigée ;
  • que les tests passent ;
  • que les métriques restent cohérentes ;
  • que les autres produits ou marchands ne régressent pas ;
  • que la documentation décrit le nouveau comportement si nécessaire.

Pour une correction importante, conserver un compte rendu avec :

  • symptômes ;
  • cause ;
  • preuves ;
  • correction ;
  • tests ;
  • validation ;
  • rollback disponible.

Ce qu'il ne faut jamais faire pendant une investigation

Ne jamais :

  • modifier les données avant de savoir ce qu'elles représentent ;
  • supprimer les preuves avant la fin du diagnostic ;
  • corriger uniquement le symptôme si la cause se trouve en amont ;
  • lancer plusieurs réparations en parallèle ;
  • conclure qu'un composant est coupable simplement parce qu'il affiche l'erreur ;
  • utiliser une ancienne procédure sans vérifier qu'elle correspond encore au runtime actuel ;
  • transformer une hypothèse en certitude sans test.

Checklist d'investigation

  • [ ] J'ai décrit précisément le symptôme.
  • [ ] J'ai noté le commit et l'heure.
  • [ ] J'ai vérifié l'état général.
  • [ ] J'ai identifié la couche probable.
  • [ ] J'ai remonté le chemin de la donnée.
  • [ ] J'ai préservé les preuves.
  • [ ] Mon hypothèse est testable.
  • [ ] Je peux la vérifier sans écriture si possible.
  • [ ] La correction est placée dans la bonne responsabilité.
  • [ ] Je sais comment valider après correction.
  • [ ] Je sais comment revenir en arrière si nécessaire.

Voir aussi