Modèle de runbook réutilisable pour problèmes de production récurrents

Ce qu'est un runbook et pourquoi les problèmes récurrents en ont besoin

Un runbook est un ensemble court et pratique d'instructions qui aide quelqu'un à réparer un problème de production connu de la même façon à chaque fois. Il transforme le savoir tribal ("essaie de redémarrer" ou "vérifie les logs") en étapes claires, avec des commandes, des propriétaires et des contrôles qui confirment que le système est de nouveau sain.

Un runbook n'est pas un postmortem. Un postmortem explique ce qui s'est passé, pourquoi, et ce que vous changerez pour que cela ne se reproduise pas. Un runbook, c'est ce que vous utilisez pendant l'incident, quand le temps est compté et que vous avez besoin d'actions sûres et reproductibles.

Les runbooks aident surtout quand les problèmes se répètent. Par exemple : la même alerte se déclenche chaque semaine (pics CPU, accumulation dans la file, cron qui échoue), le support reçoit toujours le même rapport utilisateur ("boucle de connexion", "paiements bloqués"), les déploiements provoquent souvent une cassure prévisible (migrations, config, cache), ou une correction existe mais une seule personne s'en souvient.

Voici un exemple simple : après certains déploiements, les utilisateurs signalent qu'ils ne peuvent pas se connecter. Sans runbook, la personne on-call devine : revenir en arrière, redémarrer, changer des variables d'environnement, pinguer des collègues. Avec un runbook, elle suit un chemin éprouvé : confirmer le symptôme, vérifier les signaux importants, appliquer l'action corrective la plus sûre et vérifier que les connexions fonctionnent à nouveau.

Un bon runbook réduit les suppositions et la panique. Il n'éliminera pas les incidents, et ne remplacera pas le travail d'ingénierie pour supprimer la cause racine. En revanche, il vous fait gagner du temps, réduit les risques (moins de changements aléatoires en prod) et rend la réponse cohérente, même quand le créateur initial n'est pas disponible.

Choisir les erreurs à transformer en runbooks

Toutes les alertes ne méritent pas un runbook. Commencez par les problèmes qui ramènent régulièrement les gens dans la même boucle : les mêmes questions Slack, les mêmes "qui sait réparer ça ?", et les mêmes étapes manuelles qui vivent dans la mémoire de quelqu'un.

Choisissez les incidents qui se produisent souvent ou qui nuisent à l'activité quand ils arrivent (perte de connexions, paiements échoués, jobs bloqués). Si vous n'avez pas encore de contournement fiable, mettez-le de côté et écrivez d'abord une courte note "symptômes connus".

Un filtre simple pour vos 3 à 5 premiers runbooks :

• Récurrence : cela s'est produit plus d'une fois ces dernières semaines.
• Impact : cela bloque des clients ou du chiffre d'affaires, même si c'est rare.
• Prédictibilité : vous avez un contournement connu, même si la cause racine n'est pas totalement comprise.
• Temps : cela prend régulièrement plus de 15 à 30 minutes à résoudre.
• Propriété : il y a une équipe claire qui peut le maintenir.

La plupart des équipes trouvent des gains rapides dans les mêmes domaines : flux de connexion et d'auth (tokens, sessions, boucles de redirection), paiements et webhooks (retries, vérifications de signature), jobs et files d'attente (workers bloqués, messages « poison »), et timeouts d'API et limites de débit (endpoints lents, pannes en amont).

Structure d'un runbook : les champs à inclure à chaque fois

Un runbook n'aide que s'il est facile à scanner sous stress. Une structure cohérente rend aussi le prochain runbook plus rapide à écrire.

Commencez par un en-tête qui répond aux bases en un coup d'œil :

• Nom de l'incident (utilisez la même formulation que votre alerte)
• Niveau de sévérité
• Service ou fonctionnalité affectée
• Dernière mise à jour (nom et date)

Si le runbook est périmé, les gens hésiteront à lui faire confiance.

Ensuite, ajoutez un objectif en une ligne qui décrit ce que signifie « réparé » en termes simples. Pas "redémarrer le serveur", mais "les utilisateurs peuvent se reconnecter et le taux d'erreur est revenu à la normale pendant 10 minutes". Cela évite d'arrêter trop tôt.

Soyez clair sur le public visé. Une personne du support a besoin de détails différents d'un ingénieur on-call, d'un fondateur ou d'un prestataire. Si le lecteur visé est non technique, incluez des vérifications simples et où cliquer, pas seulement du jargon interne.

Listez les accès requis en tête pour que les gens ne se retrouvent pas bloqués en plein incident :

• Dashboards (métriques et suivi d'erreurs)
• Logs (application et infrastructure)
• Panneau admin (utilisateurs et facturation)
• Console cloud (déploiements et secrets)
• Système de feature flags ou de configuration

Puis gardez quelques champs standards pour que chaque runbook soit familier : prérequis et notes de sécurité (ce qu'il ne faut pas faire), contact d'escalade, note de rollback et un petit bloc de vérification pour confirmer la remise en état.

Actions pas à pas que les gens peuvent suivre

Commencez par une note de sécurité. Mettez les opérations risquées en évidence pour que personne n'aggrave la situation à 2 h du matin. Soyez spécifique : « Ne supprimez pas de données, ne faites pas tourner des clés, et ne redémarrez pas tout un cluster sans approbation du lead incident. » Si une étape peut causer une indisponibilité, dites-le clairement.

Rédigez des étapes comme de petites actions que quelqu'un peut faire en environ une minute. Chaque étape doit commencer par un verbe (Vérifier, Comparer, Exécuter, Revenir en arrière). Gardez chaque étape ciblée : une étape, un objectif, un résultat attendu.

Quand vous incluez des commandes, facilitez le copier-coller. Utilisez des placeholders et indiquez d'où ils viennent (ticket, logs, dashboard). Mettez d'abord des vérifications en lecture seule, puis les modifications.

# Set placeholders first
export ENV=prod
export SERVICE=api
export REQUEST_ID="\u003cREQUEST_ID_FROM_LOGS\u003e"

# Read-only: confirm the error is happening
kubectl -n $ENV logs deploy/$SERVICE --since=10m | grep "$REQUEST_ID" | tail -n 5

# Expected: lines include "ERROR" and the same REQUEST_ID

Après les étapes importantes, ajoutez « ce que vous devriez voir ». Si la sortie attendue est vide, dites-le. Si le succès signifie qu'une métrique baisse, nommez la métrique et la plage normale.

Prévoyez un point d'arrêt clair. Si les logs montrent une erreur différente de ce que suppose le runbook, ou si une commande retourne "permission denied", la prochaine étape n'est pas "insister". C'est :

• Arrêter les changements
• Capturer les signaux clés (horodatage, request ID, dernier déploiement)
• Escalader vers le propriétaire listé pour ce système

Triage et diagnostic : trouver la cause sans deviner

Quand une alerte se déclenche, votre premier objectif est de comprendre la forme du problème, pas de chasser une solution ingénieuse. Le runbook doit rendre les 10 premières minutes prévisibles, même quand le système est bruyant.

Commencez par le périmètre. Est-ce un seul utilisateur (données de compte), une région (edge ou routage), ou tout le monde (dépendance cœur) ? Une réponse rapide évite de creuser au mauvais endroit.

Vérifications rapides qui expliquent souvent des pannes « soudaines »

Avant d'aller dans les logs profonds, vérifiez les suspects habituels :

• Déploiements, rollouts ou migrations récents dans les 30 à 60 dernières minutes
• Changements de configuration (env vars, secrets, chaînes de connexion) et credentials expirés
• Feature flags ou expériences qui ont changé leurs règles de ciblage
• Incidents de dépendances (base de données, file, fournisseur d'auth) et limites de débit
• Variations de capacité (autoscaling bloqué, nouvelle source de trafic, pic de cron)

Ensuite, prenez quelques chiffres qui aident à choisir une direction : tendance du taux d'erreur, latence, profondeur de file, et nombre de connexions DB (ou saturation). Si possible, comparez « maintenant » à « la dernière heure » et « la même heure hier » pour repérer ce qui a changé.

Trouver le premier message d'erreur utile

Les logs peuvent être infinis. Filtrez par endpoint ou nom de job en échec, puis cherchez la première erreur utile dans la chaîne (pas la dernière trace de pile). Prenez un seul request ID, user ID ou une fenêtre temporelle serrée autour du pic et suivez-le jusqu'à voir le premier « pourquoi ».

Si le monitoring manque (courant dans les prototypes rushés), le runbook devrait indiquer quoi capturer manuellement avant de changer quoi que ce soit :

• Heure exacte du début du problème et comment il a été détecté
• Quelques exemples d'IDs utilisateur ou request IDs qui échouent
• Une réponse d'erreur complète et une réponse réussie (si disponible)
• Version/commit actuelle de l'app et état des feature flags actifs
• Capture d'écran ou export des graphiques clés que vous avez

Ce petit paquet de preuves évite les suppositions et facilite les transferts.

Propriétaires et escalade : qui fait quoi et quand

Un runbook ne fonctionne que s'il nomme qui est responsable. « Propriétaire » doit être un rôle (pas seulement une personne) qui est on-call ou responsable du service. Ajoutez un propriétaire de secours quand le principal est absent, en congé ou déjà sur un autre incident.

Définissez aussi qui peut approuver les actions risquées. Précisez ce que « risqué » signifie pour votre équipe : tout ce qui peut causer perte de données, indisponibilité, exposition de sécurité ou blocage client. Exemples : rollback d'une migration DB, rotation de secrets d'auth, désactivation d'un contrôle de sécurité, ou exécution d'un script de nettoyage destructeur.

Indiquez quand pager et quand escalader. Des règles vagues comme « alerter si c'est grave » créent des délais.

• Pager immédiatement si les erreurs de connexion dépassent X% pendant Y minutes, ou si un endpoint clé renvoie des 5xx.
• Pager si tout incident impactant le client dure plus de Z minutes sans chemin confirmé de récupération.
• Pager la sécurité immédiatement si vous suspectez des secrets exposés, un accès admin inattendu, ou une possible injection.
• Escalader si la correction nécessite une approbation que vous n'avez pas.
• Escalader si vous ne pouvez pas vérifier l'amélioration après une mitigation sûre.

Puis listez l'ordre d'escalade pour éviter les débats en pleine crise :

• On-call principal
• On-call de secours
• Tech lead du service
• Sécurité (si auth, secrets ou trafic suspect impliqués)
• Support vendeurs (cloud, paiements, email) quand les preuves indiquent un problème hors de votre code

Ajoutez une note courte pour les équipes support : une ou deux phrases à dire aux utilisateurs, plus ce qu'il ne faut pas promettre. Exemple : « Nous investiguons des échecs de connexion et travaillons à une correction. Vos données sont en sécurité. Prochaine mise à jour dans 30 minutes. »

Vérifications : comment confirmer que la correction a vraiment marché

Une correction n'est pas réelle tant que vous ne pouvez pas le prouver. Les vérifications sont de petites mesures répétables que vous exécutez juste après le changement pour confirmer que le système est de nouveau sain.

Adaptez les vérifications à ce que les utilisateurs ont vécu. Si le problème concernait les connexions, ne vous contentez pas de « les erreurs ont diminué ». Vérifiez que les utilisateurs peuvent réellement se connecter et que le taux d'erreur et la santé du service d'auth sont normaux.

Restez simple : un smoke test + quelques métriques

Visez un smoke test que tout on-call peut exécuter, plus 2 à 3 signaux de monitoring :

• Smoke test (flux utilisateur) : effectuez une action réelle de bout en bout (connexion, création d'un enregistrement, passage d'un paiement test) et définissez ce que signifie « succès ».
• Métriques clés : choisissez quelques indicateurs qui devraient bouger immédiatement (taux 5xx, échecs d'auth, profondeur de file, latence p95, logs d'erreur pour l'endpoint spécifique).
• Vérifications système : confirmez que les dépendances sont saines (connexions DB, taux de hit du cache, statut tiers si impliqué).
• Contrôle de régression : refaites l'action qui a déclenché l'incident (même route, même forme de payload, même état de feature flag).
• Garde-fous : vérifiez qu'aucun secret ni paramètre de debug n'a été exposé lors de la correction.

Si la correction a été un rollback, ajoutez la vérification de rollback : confirmez que la version X est active en production, que l'endpoint problématique renvoie 200, et que le taux d'erreur revient à la baseline.

Définir une fenêtre de surveillance et un critère de "fini"

Après la correction, surveillez les bons graphiques et logs pendant 15 à 60 minutes. Écrivez ce que vous attendez de stable, et quel seuil signifie que le problème est revenu.

Terminez par une unique ligne « fini », par exemple : « Fini quand le smoke test réussit deux fois, le taux d'erreur reste sous 1% pendant 30 minutes et aucune nouvelle alerte liée ne se déclenche. » Puis documentez :

• ce qui a changé (commit, config, flag, déploiement ou rollback)
• les vérifications exécutées et leurs résultats
• ce que vous ferez la prochaine fois pour le détecter plus tôt

Section commandes : rendre le copier-coller sûr et prévisible

Le moyen le plus rapide de faire d'un runbook un outil réel (et non un doc dont personne ne se sert) est de rendre les commandes sûres à copier et difficiles à mal utiliser. Traitez le bloc de commandes comme un mini-produit : entrées claires, sorties claires, avertissements explicites.

Commencez par des commandes en lecture seule. Placez les commandes d'écriture (redémarrages, changements de config, migrations) plus bas, et ajoutez une ligne d'avertissement au-dessus.

Un modèle qui fonctionne bien :

• Utilisez des placeholders comme <service>, <env>, <region>, <user_id>, <incident_id> et montrez un exemple « connu bon » rempli.
• Ajoutez des commandes « NE PAS LANCER » quand les gens y ont recours sous stress.
• Indiquez les permissions requises en tête (nom du rôle, accès système, et si un accès écriture prod est nécessaire).
• Exigez une entrée de journal de changement : heure, commande exacte, résultat, et l'ID du ticket/incident.
• Indiquez ce que signifie « succès » pour chaque commande (sortie attendue ou chiffre qui devrait changer).

# Read-only checks (safe)
export ENV=<prod|staging>
export SERVICE=<api>

# Confirm current deploy + error rate
kubectl -n $ENV get deploy $SERVICE
kubectl -n $ENV logs deploy/$SERVICE --since=10m | tail -n 50

# Known good example
# ENV=prod SERVICE=auth-api

# Write actions (DANGER: prod impact)
# Only run with <role_name> and after confirming incident <incident_id>
# Log: <time> <command> <result> <incident_id>

# DO NOT RUN: resets all sessions (use only with approval)
# redis-cli -h <host> FLUSHALL

Si vous héritez de commandes de déploiement peu claires ou de scripts d'ops générés par IA, faites-les revoir avant qu'ils ne deviennent la norme. Les petites erreurs (mauvais namespace, wildcard dangereux, absence d'étape de confirmation) peuvent créer des incidents répétés.

Erreurs courantes qui rendent les runbooks inutiles

Les runbooks échouent sous pression pour des raisons prévisibles, et la plupart tournent autour de la clarté.

La première erreur est la responsabilité floue. Un runbook qui dit « quelqu'un du backend doit vérifier les logs » sera ignoré à 2 h du matin. Chaque problème récurrent a besoin d'un propriétaire nommé (rôle ou personne) et d'un chemin d'escalade clair.

Un autre échec fréquent est la connaissance cachée. Des étapes qui reposent sur « le mot de passe habituel », un dashboard privé, ou une clé SSH unique ne sont pas des étapes, ce sont des espoirs. Si l'accès est sensible, dites où sont stockées les credentials et quelles permissions minimales sont nécessaires. Si l'accès n'est pas disponible pendant un incident, dites-le et indiquez le recours.

Vérifiez ces problèmes avant de publier :

• Pas de propriétaire ni de contact on-call
• Étapes qui supposent des connaissances tribales, comme où sont les logs ou quel environnement est « le vrai »
• Pas de vérifications, donc le symptôme cesse brièvement puis revient
• Commandes obsolètes après des changements d'infra (services renommés, nouvelles régions, outil de déploiement différent)
• "Correctifs" trop risqués ou vagues, comme "redémarrer tout" ou "changer la config prudemment"

La vérification est la pièce que les gens sautent, et c'est celle qui empêche les pages répétées. Après chaque correction, incluez une preuve rapide comme « connexion réussie pour un utilisateur test », « le taux d'erreur tombe sous X », et « pas de nouveaux 5xx pendant 10 minutes ».

Enfin, adaptez le libellé pour résister au stress. Si une étape peut causer des dégâts, exposez les limites sûres et un rollback.

Exemple de runbook : échecs de connexion récurrents après un déploiement

Ce runbook exemple couvre un motif courant : les connexions se cassent juste après un déploiement.

Scénario : 5 à 10 minutes après un déploiement, les utilisateurs signalent qu'ils ne peuvent pas se connecter. Le site charge, mais le bouton de connexion tourne puis affiche « Something went wrong. »

Signal d'alerte : le taux d'erreur API pour /auth/login passe de <1% à 20%+. Les tickets support disent « mot de passe correct, ça échoue quand même ».

Propriétaires : ingénieur on-call (principal), release captain (approbateur pour rollback), lead support (comms utilisateur).

Triage et diagnostic

Confirmez le périmètre et le changement le plus récent avant d'essayer des corrections.

• Confirmez l'impact : nouveaux utilisateurs, utilisateurs existants, ou les deux ? Une région ou toutes ?
• Vérifiez le dernier déploiement : quoi a changé dans l'auth, la config, les env vars ou les migrations DB ?
• Inspectez les logs pour la première erreur après l'heure du déploiement (cherchez 401 vs 500, variable d'env manquante, erreurs de signature de token).
• Vérifiez les dépendances : fournisseur d'identité, base de données, cache, service email.

Étapes de mitigation (choisir l'action la plus sûre applicable)

Utilisez l'action la moins disruptive en premier, et arrêtez-vous dès que le système récupère.

• Désactiver le feature flag lié à la connexion (si disponible) pour router le trafic sur le chemin précédent.
• Revenir à la configuration d'auth connue bonne (ex. URL de callback, secret JWT, domaine du cookie).
• Redémarrer le service d'auth pour qu'il prenne la config corrigée (seulement après vérification des secrets).
• Revenir au déploiement précédent si les erreurs persistent après la restauration de la config.

Vérifications

Confirmez à la fois l'expérience utilisateur et les métriques.

• Effectuez une connexion réelle (utilisateur test) et confirmez qu'une session est créée.
• Le taux d'erreur revient à la baseline pendant 10 à 15 minutes, et aucun nouveau pic n'apparaît dans les logs.

Après l'incident, mettez à jour le runbook avec le motif de log exact, la clé de config qui a causé la casse, la règle de décision de rollback, et un contrôle pré-déploiement (par ex. « valider que les env vars d'auth requises existent en production »).

Étapes suivantes : maintenir les runbooks à jour et réduire les incidents récurrents

Un runbook ne fait gagner du temps que s'il reste fidèle au fonctionnement actuel du système. La façon la plus rapide d'obtenir des docs périmées est de considérer un runbook comme « terminé » après l'avoir écrit une fois.

Après chaque incident, prenez 10 minutes pendant que les détails sont frais et faites de petites modifications : ajustez le libellé des symptômes, ajoutez la ligne de log manquante qui aurait aidé, et capturez les nouveaux écueils rencontrés lors de la correction.

Avant de clore le ticket, faites un rapide contrôle d'utilisabilité :

• L'en-tête est complet (service, environnement, dernière mise à jour, risques connus)
• Propriétaires et chemin d'escalade sont définis (et toujours valides)
• Les étapes ont été testées récemment (pas seulement écrites)
• Les vérifications sont définies (ce que signifie le succès)
• Les commandes sont sûres à copier-coller (scopées, réversibles et documentées)

Mettez en place un simple rythme de revue. Une revue mensuelle convient aux équipes occupées, mais de meilleurs déclencheurs sont « après chaque incident » et « après chaque refactor ou mise à jour de dépendance » pour les services qui tombent le plus souvent.

Si vous remarquez les mêmes échecs après chaque déploiement, ce n'est peut-être pas un problème de runbook. Cela peut être un problème de code, particulièrement dans des applis générées par des outils IA où l'authentification, les secrets et l'architecture semblent corrects en démo mais échouent en production.

Si vous héritez d'une appli générée par IA et que vous passez votre temps à éteindre des feux, FixMyMess (fixmymess.ai) se concentre sur le diagnostic et la réparation de ces bases de code : correction de logique, renforcement de la sécurité, refactorisation et préparation au déploiement. Un audit court peut transformer les "correctifs tribaux" répétés en changements stables et vous donner des runbooks qui correspondent réellement au comportement du système.