Runbooks de respuesta a incidentes que sí se usan
Un runbook que abre con arquitectura del sistema es documentación para onboarding, no operaciones para las 3 AM. Los runbooks de incidentes se usan cuando empiezan con síntomas, ramifican en señales observables y terminan con pasos de verificación lo bastante cortos para ejecutar bajo estrés.
El pager sonó a las 2:47 AM. On-call abrió el wiki. El runbook empezaba con un diagrama de microservicios de 2022. Tres servicios habían sido renombrados. Uno fue eliminado. El diagrama no tenía enlace a logs, ni "si tasa de error en X," ni comando de rollback. Veinte minutos pasaron leyendo prosa sobre filosofía del sistema. Los runbooks de respuesta a incidentes que sí se usan comparten una propiedad: empiezan donde empieza el incidente — un síntoma, una alerta, un reporte de cliente — y ramifican en comprobaciones que tardan segundos, no capítulos que consumen atención.
Los runbooks no son documentación. La documentación enseña el sistema. Los runbooks guían acción cuando el sistema falla y la cognición está deteriorada. La diferencia es estructura: árboles de decisión frente a ensayos, comandos frente a conceptos, pasos de verificación frente a contexto histórico.
Los runbooks fallan cuando se escriben para lectores tranquilos
| Runbook anti-pattern | Why it fails at 3 AM |
|---|---|
| Resumen de arquitectura primero | El lector necesita acción, no contexto |
| Párrafos en prosa | El escaneo falla bajo estrés |
| Nombres de servicio obsoletos | La confianza colapsa en la primera referencia incorrecta |
| Sin owner ni fecha de última verificación | No está claro si es seguro seguirlo |
| Enlaces a enlaces | La navegación se rompe en móvil |
| "Contactar al equipo" | Sin teléfono, sin ruta de escalación |
Los buenos runbooks asumen: el lector puede ser nuevo, cansado, solo y desconocedor de deploys recientes. Cada paso debe ser ejecutable sin memoria institucional.
Un runbook es un programa para humanos. Si no ramifica en condiciones, es un script que solo corre en una máquina — la tuya, hace seis meses.
Anatomía de un runbook que sí se abre
Header (cinco líneas máximo)
- Nombre de servicio / síntoma
- Contexto de severidad (cuándo usar este runbook)
- Fecha de última verificación + owner
- Alertas relacionadas (nombres en PagerDuty, Grafana)
- Contacto de escalación
Puntos de entrada por síntoma
Múltiples rutas de entrada — la misma causa raíz puede presentarse de formas distintas:
Entry: Checkout error rate > 2%
Entry: Payment provider webhook failures
Entry: Customer report "card charged, order missing"
Árbol de decisión (núcleo)
1. Check payment provider status page → outage?
YES → Post status, enable maintenance message, DONE (monitor)
NO → step 2
2. Recent deploy < 30 min?
YES → Execute rollback runbook §1 → verify → DONE or escalate
NO → step 3
3. DB connection pool exhausted?
YES → Scale pool / kill long queries (link command) → verify
NO → escalate to payments on-call
Comandos listos para copiar y pegar
CLI exacto, URLs de dashboard, SQL con placeholders marcados {{service}}. Nada de "ejecutar la limpieza habitual."
Verificación
Cómo saber que el incidente está resuelto — umbrales de métricas, smoke test, transacción de muestra.
Plantilla de comunicación
Texto de status page, mensaje interno de Slack — rellenar en blanco.
Enlazar estrategia de rollback con árboles de decisión dentro de ramas relacionadas con deploy — no duplicar, referenciar.
Organizar por síntoma, no por organigrama de servicios
Los runbooks por servicio ("Payments Runbook") envejecen mal cuando cambia la propiedad. Los runbooks por síntoma ("Checkout failures") se alinean con cómo llegan alertas y clientes.
Enlazar runbooks relacionados:
- Tasa de error alta → ruta de rollback de deploy
- Latencia elevada → runbook de base de datos / caché
- Fallos de auth → runbook de proveedor de identidad
Página índice: nombre de alerta → URL de runbook. On-call no debería buscar en Confluence.
Mantener los runbooks vivos
Los runbooks se pudren más rápido que el código.
Fecha de última verificación — game day trimestral o actualización post-incidente obligatoria.
Mandato post-incidente — cada sev-1/sev-2 actualiza o crea runbook en 48 horas. Ítem de acción del postmortem sin culpa: "brecha de runbook."
Automatizar pasos donde sea posible — el runbook dispara script para operaciones seguras (reiniciar worker, limpiar cola atascada). Pasos humanos para decisiones de juicio.
Límite de longitud — una pantalla por nodo de decisión. Runbooks largos se dividen en sub-runbooks enlazados.
Las alertas de burn de SLO indican que se está en territorio de incidente. Los runbooks dicen qué hacer — emparejar cada alerta de burn con enlace a runbook en el payload de la alerta.
Roles durante incidentes: qué asumen los runbooks
Incluso equipos pequeños se benefician de roles explícitos en el header del runbook:
| Role | Responsibility |
|---|---|
| Incident commander | Coordina, comunica, decide escalación |
| Investigator | Sigue el árbol técnico |
| Communicator | Status page, sync con soporte al cliente |
| Scribe | Timeline para postmortem |
On-call en solitario puede llevar todos los sombreros — el runbook aún anota qué sombrero sirve cada sección para que nada se olvide.
¿Cómo deben escribir los equipos runbooks de incidentes?
Estos estándares separan runbooks operativos del relleno del wiki.
¿Cuánto debe medir un runbook?
Lo más corto posible para la ruta de decisión. Objetivo: primera acción en 60 segundos de abrirlo. Si hace falta contexto de arquitectura, enlazar a doc separada — no anteponer.
¿Qué va en el runbook frente al postmortem?
Runbook: cómo arreglar o mitigar ahora. Postmortem: por qué pasó, arreglos sistémicos. Los runbooks pueden anotar falsos positivos conocidos de incidentes pasados — una línea, no postmortem completo.
¿Deben los runbooks incluir comandos de rollback?
Sí, cuando la correlación con deploy es modo de fallo habitual. Referenciar árbol de decisión de rollback centralizado; incluir comandos específicos del servicio (redeploy tag, nombre de toggle de flag).
Una visión opuesta
La postura contraria sostiene que buena observabilidad y remediación automatizada hacen obsoletos los runbooks — que dashboards y sistemas auto-reparadores reemplazan procedimientos escritos.
La automatización maneja known knowns. Los incidentes suelen ser combinaciones novedosas — deploy más caída de proveedor más pico de tráfico. Los runbooks capturan memoria organizacional para secuencias de comprobación que la automatización no debería ejecutar sin supervisión (rollback, reparación de datos). Observabilidad sin runbooks produce parálisis informada — muchos gráficos, sin siguiente paso.
Key takeaways
- Los runbooks empiezan con síntomas y alertas — no diagramas de arquitectura.
- Árboles de decisión con ramas sí/no superan a la prosa; primera acción en 60 segundos.
- Comandos copiar-pegar, umbrales de verificación, plantillas de comunicación obligatorios.
- Índice nombre de alerta → URL de runbook; runbooks obsoletos peor que ninguno — verificar trimestralmente.
- Actualizaciones post-incidente en 48 horas para sev-1/sev-2; enlazar runbooks de rollback y SLO.
- Dividir procedimientos largos en sub-runbooks enlazados; una pantalla por nodo de decisión.
Conclusion
Los runbooks de respuesta a incidentes que sí se usan están escritos para la versión de on-call que lleva noventa minutos despierta y no recuerda el deploy del trimestre pasado. Síntomas primero, ramas en hechos observables, verificación antes del all-clear. Todo lo demás es documentación con etiqueta de runbook.
El ejercicio: elegir las últimas tres páginas. Para cada una, abrir el runbook enlazado. Tiempo hasta la primera acción ejecutable. Más de dos minutos — reescribir antes de la próxima página.