Runbooks et transfert de connaissance
Écrire des runbooks exploitables à 3h du matin par une personne stressée et peu familière du système.
À retenir
- Un runbook doit être actionnable sans compréhension préalable du système, sous stress.
- Chaque étape doit indiquer comment vérifier son succès avant de continuer.
- Les critères d'escalade doivent être explicites et non laissés à l'appréciation.
- Le shadowing d'astreinte transfère mieux la connaissance qu'une formation théorique.
Le runbook comme outil de survie
Un runbook n'est pas de la documentation d'architecture : c'est un guide d'action conçu pour être suivi sous stress, à 3h du matin, par quelqu'un qui n'a peut-être jamais touché ce composant. S'il exige de comprendre le système avant d'agir, il a échoué.
Anatomie d'un bon runbook
- Titre lié directement au nom de l'alerte : la personne d'astreinte doit retrouver le bon document en moins de 30 secondes.
- Symptômes observables : ce que montre le dashboard, pas une hypothèse de cause.
- Étapes numérotées et vérifiables : chaque étape indique comment savoir si elle a fonctionné avant de passer à la suivante.
- Commandes copiables telles quelles, avec les variables clairement identifiées.
- Critères d'escalade explicites : à quel moment précis appeler quelqu'un d'autre, et qui.
| Élément | Mauvais runbook | Bon runbook |
|---|---|---|
| Titre | "Problèmes base de données" | "Alerte DBReplicationLagHigh" |
| Étape | "Vérifier la réplication" | "Exécuter SHOW SLAVE STATUS\G, vérifier Seconds_Behind_Master < 60" |
| Escalade | "Si ça ne marche pas, prévenir quelqu'un" | "Si lag > 300s après 10 min, escalader au DBA de garde (#oncall-dba)" |
Point clé
un runbook se teste comme du code : en le faisant exécuter par quelqu'un qui n'a pas écrit le système, idéalement en jeu de rôle pendant un exercice d'astreinte.
Transfert de connaissance continu
Le savoir tacite d'un ingénieur senior est le pire actif à perdre en cas de départ. Documenter au fil de l'eau, immédiatement après chaque incident non couvert par un runbook existant, évite l'accumulation d'une dette de connaissance invisible jusqu'au jour où elle manque cruellement.
Attention
un runbook qui n'a pas été relu depuis plus de 6 mois est suspect par défaut ; les systèmes évoluent plus vite que la documentation qui les décrit.
Le rôle du shadowing
Faire suivre une astreinte à une personne junior en observation ("shadow on-call") avant qu'elle ne prenne son propre tour est l'un des moyens les plus efficaces de transfert de connaissance, bien plus qu'une session de formation théorique isolée.
Sur le terrain
les équipes qui exigent qu'un runbook accompagne systématiquement toute nouvelle alerte en production évitent l'écueil classique de l'alerte "orpheline", où personne ne sait plus pourquoi elle existe ni quoi faire quand elle se déclenche.
Astuce
ajoutez un lien direct vers le runbook dans le corps même de l'alerte (annotation Prometheus/Alertmanager) : la personne d'astreinte ne doit jamais avoir à chercher le document dans un wiki mal indexé.