Runbooks PHP pour récupérer les incidents en toute sécurité

Un runbook d’incidents pour applications PHP transforme une alerte en une séquence de décisions contrôlées. Ce n’est pas une liste de commandes ni un document qui présuppose une cause : il doit indiquer quel symptôme a été détecté, quelles preuves recueillir, quelles actions sont acceptables, quand s’arrêter et qui peut décider de l’étape suivante.

Cela est particulièrement important dans les applications avec du trafic web, des processus PHP en arrière-plan, des files d’attente, des cron, des intégrations externes et des bases de données partagées. Une intervention apparemment simple, telle que redémarrer des consommateurs ou réessayer des messages, peut masquer l’origine, dupliquer des opérations ou accroître la charge sur un service déjà dégradé.

Ce qu’un runbook résout et ce qu’il ne doit pas remplacer

Un runbook réduit l’improvisation lors de situations répétables ou prévisibles. Il rend explicites l’ordre des vérifications, les limites d’une intervention et les preuves nécessaires pour déclarer le rétablissement. Il permet également au développement, aux opérations et au métier de partager un même langage face à un incident.

Il ne remplace pas les contrôles qui doivent exister avant l’incident :

• Observabilité : métriques, logs corrélés, traces et alertes avec des seuils compréhensibles. Une procédure ne compense pas un signal ambigu ou dépourvu de contexte.
• Formation et permissions : les personnes qui l’exécutent doivent comprendre le risque et ne disposer que des accès nécessaires.
• Sauvegardes et restauration testée : une sauvegarde n’est pas une stratégie de récupération si l’on ne connaît pas son intégrité, sa portée et son temps de restauration.
• Architecture : des réessais idempotents, des limites de ressources, des timeouts, des circuit breakers et l’isolation des dépendances réduisent le besoin d’interventions manuelles.
• Gestion des changements : un déploiement n’équivaut pas à une release. Le runbook doit savoir quelle version est active et si une activation progressive peut réduire le risque d’annuler le déploiement.

L’objectif n’est pas de documenter chaque défaillance possible. Il consiste à standardiser les réponses aux signaux qui ont un impact opérationnel et pour lesquels une décision incorrecte peut aggraver l’état du système.

Quand une alerte mérite une procédure spécifique

Toutes les alertes ne nécessitent pas leur propre document. Il convient de prioriser les situations qui combinent fréquence, impact, pression temporelle ou dépendance entre équipes. Une alerte mérite un runbook lorsque la réaction ne devrait pas dépendre de la mémorisation d’étapes sous stress.

• Elle se répète et exige généralement les mêmes vérifications initiales.
• Elle affecte les revenus, les processus clients, le respect des délais ou la disponibilité d’une fonction critique.
• L’action corrective n’est réversible que dans une fenêtre limitée.
• Elle exige une coordination entre l’application PHP, l’infrastructure, la base de données ou un fournisseur d’API.
• Une action manuelle peut provoquer une perte, une duplication ou une exposition de données.
• L’alarme présente des faux positifs connus qui doivent être écartés à l’aide de preuves concrètes.

Commencez par le symptôme observable, et non par une théorie. « Les travaux en attente augmentent », « la latence de l’endpoint dépasse le seuil », « les erreurs 5xx augmentent » ou « une intégration renvoie des réponses non valides » sont des entrées utiles. « La base de données est saturée » est une hypothèse à vérifier, et non le point de départ de la procédure.

La structure minimale d’un runbook exploitable

Un document opérationnel utile peut être lu et exécuté pendant un incident. Il doit éviter des formulations telles que « consulter les logs » sans préciser quoi rechercher, sur quel intervalle et quel résultat modifie la décision.

1. Objectif et périmètre : décrivez le symptôme couvert, les composants affectés et ceux qui sont exclus. Indiquez s’il s’applique à la production, à des environnements précis ou à un type de processus.
2. Signaux d’entrée : incluez l’alerte, les seuils, les tableaux de bord pertinents, le message d’erreur et les conditions qui distinguent une alerte réelle du bruit.
3. Responsable initial et permissions : précisez qui prend en charge l’incident, qui exécute les actions et qui autorise les opérations à fort impact.
4. Risques et conditions d’arrêt : indiquez clairement quelles actions ne doivent pas être réalisées, quelles données pourraient être affectées et quand escalader sans continuer.
5. Étapes et preuves : chaque étape doit demander une vérification, consigner un résultat attendu et définir la branche de décision suivante.
6. Sortie : définissez quelles preuves permettent de clore l’incident et quel suivi reste ouvert ensuite.

Les liens internes vers des tableaux de bord, des dépôts ou des outils peuvent être utiles dans la version opérationnelle, mais ils ne doivent pas constituer l’unique contexte. Notez quelle métrique observer, quelle étiquette filtrer et quelle fenêtre temporelle utiliser. Si un outil n’est pas disponible, l’équipe doit savoir quelles preuves alternatives elle peut recueillir.

Séparez le diagnostic, la mitigation et la récupération

Une cause fréquente d’incidents prolongés est le mélange entre investigation et changements. Le runbook doit classer les actions selon leur niveau de risque et leur finalité.

Actions sûres et diagnostic

Prendre en charge l’alerte, ouvrir un canal de coordination, capturer des métriques, consulter les logs d’erreurs et vérifier l’état des dépendances sont généralement des actions à faible risque. Elles doivent néanmoins avoir des limites : des requêtes coûteuses sur une base de données dégradée ou des recherches de logs sans filtre peuvent également ajouter de la pression.

Le diagnostic doit formuler des hypothèses vérifiables. Par exemple : si les erreurs de connexion augmentent et que le pool de connexions est épuisé, on examine la dépendance et le modèle d’utilisation avant de modifier les limites. Si seule une version récemment exposée échoue, on compare son trafic et ses erreurs avec ceux de la version précédente.

Mitigation et récupération

La mitigation limite les dommages sans affirmer que la cause a été corrigée : réduire l’exposition d’une fonctionnalité, suspendre une entrée de travaux ou appliquer du rate limiting sont des exemples possibles. La récupération ramène le service à un état acceptable : restaurer un consommateur, revenir à une version précédente ou traiter le travail en attente de manière contrôlée.

Chaque action doit intégrer un point de décision : quelle métrique s’améliore, pendant combien de temps elle est observée et ce qui se passe si elle se dégrade. Redémarrer un processus PHP peut être valable comme mitigation limitée, mais cela ne doit pas être une instruction automatique s’il existe des tâches non idempotentes, des verrous de base de données ou une consommation mémoire inexpliquée.

Exemple hypothétique : accumulation de travaux dans une file d’attente PHP

Considérez une application PHP avec des consommateurs qui traitent des notifications, des synchronisations ou des tâches de commerce. L’alerte indique que le nombre de travaux en attente augmente de manière soutenue. Le runbook ne doit pas simplement ordonner de « vider la file d’attente ».

1. Confirmez le périmètre : mesurez les travaux en attente par type de travail, l’ancienneté des messages, le taux d’entrée et le taux de traitement. Vérifiez si le retard affecte tous les consommateurs ou un chemin spécifique.
2. Examinez l’état des consommateurs : processus actifs, redémarrages, mémoire, erreurs PHP, timeouts et exceptions répétées. Vérifiez également la connectivité avec la file d’attente et les dépendances appelées par les travaux.
3. Classez l’hypothèse : entrée anormalement élevée, capacité insuffisante, travail bloqué, erreur de code, dépendance externe lente ou données non valides. N’augmentez pas le nombre de consommateurs si la dépendance cible est déjà saturée.
4. Définissez des limites de réessai. Les messages qui échouent de façon répétée doivent être envoyés vers un chemin de révision ou une file d’erreurs lorsque la conception le permet ; les réessayer sans limite peut amplifier le trafic et dupliquer les effets.
5. Appliquez une récupération progressive : restaurez ou augmentez les consommateurs par étapes, observez le taux de réussite et surveillez les erreurs, la latence et la charge de la base de données. Maintenez une condition d’arrêt si le backlog augmente plus rapidement ou si les défaillances augmentent.
6. Validez le résultat : vérifiez que le travail ancien diminue, qu’il n’y a pas de doublons, que les opérations associées sont cohérentes et que l’alerte se stabilise pendant une fenêtre définie.

Si les travaux produisent des effets externes, tels que des paiements, des emails ou des changements d’inventaire, le runbook doit exiger une revue humaine avant de retraiter des lots. L’idempotence réduit le risque, mais ne doit pas être supposée sans preuves issues de la conception et des données affectées.

Protégez les données sensibles et les opérations irréversibles

Une procédure qui touche à des données personnelles, des identifiants, des commandes, des paiements ou des registres réglementaires nécessite des contrôles supplémentaires. Il ne suffit pas que la commande soit techniquement correcte.

• Utilisez le principe du moindre privilège et des comptes distincts pour la lecture, l’intervention opérationnelle et l’administration.
• Exigez une double confirmation pour les suppressions, les retraitements massifs, les restaurations ou les modifications directes de données.
• Consignez qui a autorisé et exécuté l’action, quel intervalle de données elle a couvert et quel résultat elle a obtenu.
• Définissez un échantillon de validation avant d’agir sur l’ensemble du jeu de données.
• Établissez une condition d’arrêt explicite en cas de divergences, de données non identifiables ou d’effets hors du périmètre initial.

Évitez d’inclure des secrets dans le runbook, les logs ou les captures. Le document peut indiquer le système autorisé permettant d’obtenir des identifiants temporaires, mais il ne doit pas transformer des informations sensibles en texte permanent.

Escalade et vérification après la récupération

L’escalade n’est pas un échec de l’équipe qui traite l’alerte ; c’est une décision de maîtrise des risques. Escaladez vers le développement lorsqu’il existe un défaut potentiel de l’application, une régression de version ou un comportement non idempotent. Escaladez vers l’infrastructure en cas d’épuisement des ressources, du réseau, du stockage ou de la plateforme d’exécution. Impliquez le fournisseur externe lorsque les preuves pointent vers son API ou son service. Demandez une décision métier si la mitigation exige de suspendre les ventes, de retarder les communications ou d’accepter un ordre de traitement différent.

Définissez également une durée maximale pour chaque phase. S’il n’y a pas suffisamment de preuves après le diagnostic initial, ou si une mitigation n’améliore pas le signal dans l’intervalle attendu, la personne responsable doit escalader au lieu de répéter les actions.

La récupération prend fin lorsque l’on vérifie davantage que la disparition de l’alerte :

• Le symptôme initial reste dans les limites pendant une fenêtre d’observation.
• Le travail en attente, les transactions et les données affectées sont cohérents.
• Les utilisateurs peuvent terminer les parcours pertinents sans dégradation notable.
• Les alertes associées ne montrent pas d’effets secondaires après le changement.
• La chronologie, les hypothèses confirmées ou écartées, les actions et les améliorations en attente sont documentées.

Révisez le runbook après son utilisation. Supprimez les étapes qui n’ont pas apporté de preuves, intégrez les décisions qui ont été nécessaires et transformez les constats récurrents en améliorations de l’observabilité, des tests ou de l’architecture. Ainsi, la procédure cesse d’être une documentation statique et devient un outil de récupération sûr.