Tenir une base « erreurs et corrections » : fiches, runbooks et gains
Une fiche par erreur (symptôme, cause, correction, prévention), runbooks pour les incidents récurrents et raisons pour lesquelles cela rapporte.
La même erreur, résolue trois fois par trois personnes (ou par moi, à six mois d'écart) sans que personne ne se souvienne de la solution : c'est le coût caché de l'exploitation. Ma parade tient en un fichier : une base « erreurs et corrections », versionnée avec le code, où chaque erreur récurrente a sa fiche.
Une fiche par erreur
Court et concret. Chaque entrée a un identifiant stable (ERR-042) et cinq champs :
| Champ | Contenu | Exemple générique |
|---|---|---|
| Symptôme / signature | Le message exact ou le comportement, facile à rechercher | Login failed for user '<token-identified principal>' |
| Contexte | Où et quand cela arrive | Tâche Batch lancée depuis une identité managée |
| Cause racine | Spécifique, pas « problème de droits » | L'identité n'est pas créée comme utilisateur dans la base cible |
| Correction retenue | Actionnable, vérifiée | CREATE USER ... FROM EXTERNAL PROVIDER puis rôle minimal |
| Prévention | Règle explicite, y compris ce qu'il ne faut plus faire | Vérifier l'utilisateur dans le script de déploiement |
Un tableau Markdown d'une ligne par erreur suffit. Ajouter les preuves de vérification (test, journal) et, si une approche a été rejetée, le dire : c'est ce qui évite de la reproposer.
| ID | Signature | Cause racine | Correction | Prévention |
|---------|----------------------------|----------------------------------|-----------------------------------|-------------------------------------|
| ERR-042 | "Login failed ... token" | Utilisateur absent de la base | Créer l'utilisateur depuis Entra | Étape de contrôle au déploiement |
Le cycle de vie
flowchart LR
A["Incident"] --> B["Rechercher la signature dans la base"]
B --> C{"Trouvée ?"}
C -->|oui| D["Appliquer la correction confirmée"]
C -->|non| E["Diagnostiquer et corriger"]
E --> F["Écrire le test"]
F --> G["Ajouter une fiche avec le prochain identifiant"]
D --> H["Mettre à jour la fiche si le comportement a changé"]
G --> I["Intégrer la prévention dans les règles du dépôt"]
Règles que je m'impose :
- Chercher avant de corriger : la signature est peut-être déjà là.
- Une correction qui revient s'accompagne d'un test qui cite l'identifiant de la fiche.
- Prochain identifiant libre : vérifier tout le tableau. Une collision (deux erreurs différentes sous le même numéro) m'est arrivée une fois, et elle est pénible à démêler.
- Les règles de prévention vivent là où elles s'appliquent (guide du dépôt, conventions de code), pas seulement dans la table.
Runbooks pour les incidents récurrents
Quand un incident revient souvent, la fiche ne suffit plus : on écrit un runbook court qui enchaîne diagnostic et action. Format que je retiens :
- Déclencheur (quelle alerte, quel symptôme).
- Vérifications en lecture seule, avec les requêtes à copier.
- Arbre de décision : transitoire, changement d'un tiers, défaut.
- Action et vérification de son résultat.
- Qui prévenir.
Le runbook renvoie aux fiches d'erreurs ; les fiches renvoient au runbook. Voir aussi la méthode de triage décrite dans un autre article.
Pourquoi cela rapporte
- Temps de résolution : une recherche de signature coûte une minute, un diagnostic complet une heure.
- Moins de dépendance aux personnes : la connaissance survit aux congés et aux départs.
- Intégration des nouveaux : la liste des erreurs réelles est la meilleure documentation d'un système.
- Assistants IA : un outil de génération de code qui lit la base avant de proposer un changement ne repropose pas une approche déjà rejetée.
- Tendances : voir quelles familles d'erreurs reviennent oriente les vrais chantiers de fond.
Retour d'expérience
- Trop long, personne ne relit : une fiche tient en quelques lignes, les narrations vont ailleurs.
- Une fiche sans signature recherchable est inutile ; copier le message exact.
- Une copie dans le wiki d'équipe aide les non-développeurs, mais deux sources divergent : désigner la référence (le dépôt) et la répercuter, pas l'inverse.
- Mettre à jour une fiche quand le comportement change : une fiche périmée est pire que pas de fiche.