Plantilla de runbook para problemas recurrentes en producción que puedes reutilizar

Qué es un runbook y por qué los problemas recurrentes necesitan uno

Un runbook es un conjunto breve y práctico de instrucciones que ayuda a alguien a solucionar un problema conocido en producción de la misma forma cada vez. Convierte el conocimiento tribal ("intenta reiniciarlo" o "revisa los logs") en pasos claros, con comandos, responsables y comprobaciones que confirman que el sistema vuelve a estar sano.

Un runbook no es un postmortem. Un postmortem explica qué pasó, por qué pasó y qué cambiarás para que no vuelva a ocurrir. Un runbook es lo que usas durante el incidente, cuando el tiempo apremia y necesitas acciones seguras y repetibles.

Los runbooks ayudan especialmente cuando los problemas se repiten. Por ejemplo: la misma alerta salta cada semana (picos de CPU, acumulación en colas, cron fallando), soporte recibe el mismo informe de usuario ("bucle de inicio de sesión", "pagos atascados"), los despliegues suelen provocar una rotura predecible (migraciones, configuración, caché), o existe una solución pero solo una persona la recuerda.

Aquí tienes un ejemplo sencillo: después de algunos despliegues, los usuarios informan que no pueden iniciar sesión. Sin un runbook, la persona on-call adivina: revertir, reiniciar, cambiar variables de entorno, avisar a compañeros. Con un runbook, sigue un camino probado: confirma el síntoma, revisa las señales importantes, aplica la acción correctiva más segura y verifica que los inicios de sesión vuelvan a funcionar.

Un buen runbook reduce la incertidumbre y el pánico. No eliminará los incidentes ni reemplazará el trabajo de ingeniería para eliminar la causa raíz. Lo que sí hace es ganar tiempo, reducir el riesgo (menos cambios aleatorios en prod) y hacer la respuesta consistente, incluso cuando el constructor original no está disponible.

Elige los errores adecuados para convertir en runbooks

No toda alerta merece un runbook. Empieza con problemas que siguen arrastrando a la gente al mismo bucle: las mismas preguntas en Slack, las mismas respuestas de “¿quién sabe arreglar esto?” y los mismos pasos manuales que viven en la memoria de alguien.

Elige incidentes que ocurran con frecuencia o que dañen el negocio cuando aparecen (inicios de sesión perdidos, pagos fallidos, jobs atascados). Si todavía no puedes explicar una solución fiable, déjalo para más tarde y escribe una nota corta de “síntomas conocidos” en su lugar.

Un filtro simple para tus primeras 3 a 5 runbooks:

• Se repite: ha ocurrido más de una vez en las últimas semanas.
• Impacto: bloquea clientes o ingresos, aunque sea raro.
• Predecibilidad: tienes una solución conocida, aunque no entiendas por completo la causa raíz.
• Tiempo: suele tomar más de 15 a 30 minutos resolverlo.
• Propiedad: hay un equipo claro que puede mantenerlo.

La mayoría de los equipos encuentran victorias tempranas en las mismas áreas: flujos de inicio de sesión y autenticación (tokens, sesiones, bucles de redirección), pagos y webhooks (reintentos, comprobaciones de firma), trabajos en segundo plano y colas (workers atascados, mensajes venenosos), y timeouts y límites de tasa en APIs (endpoints lentos, fallos en upstream).

Estructura del runbook: los campos que incluir siempre

Un runbook solo ayuda si es fácil de escanear bajo estrés. Una estructura consistente también hace que el siguiente runbook sea más rápido de escribir.

Empieza con un encabezado que responda lo básico de un vistazo:

• Nombre del incidente (usa la misma redacción que tu alerta)
• Nivel de severidad
• Servicio o funcionalidad afectada
• Última actualización (nombre y fecha)

Si el runbook está desactualizado, la gente dudará en confiar en él.

A continuación, añade una meta de una línea que describa qué significa “arreglado” en lenguaje claro. No "reiniciar el servidor", sino "los usuarios pueden iniciar sesión de nuevo y la tasa de errores volvió a la normalidad durante 10 minutos". Esto evita que la gente se pare demasiado pronto.

Sé claro sobre para quién es el runbook. Un agente de soporte necesita detalles diferentes a un ingeniero on-call, un fundador o un contratista. Si el lector previsto es no técnico, incluye comprobaciones simples y dónde hacer clic, no solo jerga interna.

Enumera los accesos requeridos al principio para que la gente no se encuentre con un bloqueo en medio del incidente:

• Dashboards (métricas y seguimiento de errores)
• Logs (aplicación e infraestructura)
• Panel de administración (usuarios y facturación)
• Consola cloud (despliegues y secretos)
• Sistema de feature flags o configuración

Luego mantén algunos campos estándar para que cada runbook resulte familiar: prerequisitos y notas de seguridad (qué no hacer), contacto de escalado, nota de rollback y un pequeño bloque de verificación sobre cómo confirmar la recuperación.

Acciones paso a paso que la gente pueda seguir

Empieza con una nota de seguridad. Coloca lo arriesgado al principio para que nadie “ayude” empeorando la situación a las 2 a.m. Sé específico: “No borres datos, no roten claves ni reinicies un clúster entero sin la aprobación del líder del incidente.” Si un paso puede causar downtime, dilo claramente.

Escribe los pasos como acciones pequeñas que alguien pueda hacer en un minuto. Cada paso debe comenzar con un verbo (Comprobar, Comparar, Ejecutar, Revertir). Mantén cada paso enfocado: un paso, un objetivo, un resultado esperado.

Cuando incluyas comandos, haz que copiar y pegar sea predecible. Usa marcadores y explica de dónde vienen (ticket, logs, dashboard). Prioriza comprobaciones de solo lectura, luego los cambios.

# Set placeholders first
export ENV=prod
export SERVICE=api
export REQUEST_ID="<REQUEST_ID_FROM_LOGS>"

# 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

Después de pasos importantes, añade “qué deberías ver”. Si la salida esperada está vacía, dilo. Si el éxito significa que una métrica baja, nombra la métrica y el rango normal.

Incluye un punto de parada claro. Si los logs muestran un error distinto al que asume el runbook, o si un comando devuelve permiso denegado, el siguiente paso no es "insistir más". Es:

• Detener cambios
• Capturar las señales clave (timestamp, request ID, último despliegue)
• Escalar al responsable listado para ese sistema

Triaje y diagnóstico: encuentra la causa sin adivinar

Cuando salta una alerta, tu primer objetivo es entender la forma del problema, no buscar una solución ingeniosa. El runbook debe hacer predecibles los primeros 10 minutos, incluso cuando el sistema está ruidoso.

Empieza por el alcance. ¿Es un solo usuario (datos de cuenta), una región (edge o enrutamiento) o todo el mundo (dependencia central)? Una respuesta rápida evita que cavemos en el lugar equivocado.

Comprobaciones rápidas que suelen explicar fallos “súbitos”

Antes de profundizar en los logs, revisa los sospechosos habituales:

• Despliegues recientes, rollouts o migraciones en los últimos 30 a 60 minutos
• Cambios de configuración (env vars, secretos, cadenas de conexión) y credenciales caducadas
• Feature flags o experimentos que cambiaron reglas de targeting
• Incidentes en dependencias (base de datos, cola, proveedor de auth) y límites de tasa
• Cambios de capacidad (autoscaling atascado, nueva fuente de tráfico, pico de cron)

Luego toma algunos números que te ayuden a elegir una dirección: tendencia de tasa de errores, latencia, profundidad de colas y conteo de conexiones a base de datos (o saturación). Si puedes, compara “ahora” con “última hora” y “misma hora ayer” para detectar qué cambió.

Encuentra el primer mensaje de error útil

Los logs pueden ser infinitos. Filtra por el endpoint o nombre de job que falla y busca el error más temprano en la cadena (no la última traza de pila). Elige un único request ID, user ID o una ventana de tiempo ajustada alrededor del pico y síguelo hasta ver el primer “por qué”.

Si falta monitorización (común en prototipos apresurados), el runbook debe decir qué capturar de forma manual antes de cambiar nada:

• Hora exacta en que empezó el problema y cómo se detectó
• Algunos ejemplos de user IDs o request IDs que fallan
• Una respuesta de error completa y una exitosa (si existe)
• Versión/commit actual de la app y estado de feature flags activos
• Captura de pantalla o exportación de los gráficos clave que tengas

Ese pequeño paquete de evidencia evita conjeturas y facilita las transferencias.

Responsables y escalado: quién hace qué y cuándo

Un runbook solo funciona cuando nombra quién es responsable. “Owner” debe ser un rol (no solo una persona) que esté on-call o accountable por el servicio. Añade un rol de respaldo para cuando el primario duerme, está de permiso o ya atiende otro incidente.

También define quién puede aprobar acciones arriesgadas. Explica qué significa “arriesgado” para tu equipo: cualquier cosa que pueda causar pérdida de datos, downtime, exposición de seguridad o bloqueo de clientes. Ejemplos incluyen revertir una migración de base de datos, rotar secretos de autenticación, desactivar un control de seguridad o ejecutar un script destructivo.

Anota cuándo hacer paging y cuándo escalar. Reglas vagas como “pagea si está mal” generan retrasos.

• Pagea inmediatamente si los errores de login superan X% durante Y minutos, o si un endpoint clave devuelve 5xx.
• Pagea si cualquier incidente que afecta a clientes dura más de Z minutos sin una ruta de recuperación confirmada.
• Pagea seguridad de inmediato si sospechas de secretos expuestos, accesos administrativos inesperados o posible inyección.
• Escala si la solución requiere una aprobación que no tienes.
• Escala si no puedes verificar mejora tras una mitigación segura.

Luego lista el orden de escalado para que nadie lo debata en medio del incidente:

• On-call primario
• On-call de respaldo
• Tech lead del servicio
• Seguridad (si hay auth, secretos o tráfico sospechoso)
• Soporte del proveedor (cloud, pagos, email) cuando la evidencia apunte fuera de tu código

Añade una nota corta para equipos de soporte: una o dos frases para decir a los usuarios y qué no prometer. Ejemplo: “Estamos investigando fallos de inicio de sesión y trabajando en una solución. Tus datos están seguros. Próxima actualización en 30 minutos.”

Comprobaciones de verificación: cómo confirmar que la solución funcionó realmente

Una solución no es real hasta que puedes probarlo. Las comprobaciones de verificación son medidas pequeñas y repetibles que ejecutas justo después del cambio para confirmar que el sistema está sano otra vez.

Alinea las comprobaciones con lo que sufrieron los usuarios. Si el problema eran fallos de inicio de sesión, no te quedes en “los errores bajaron”. Confirma que la gente puede iniciar sesión realmente y que la tasa de errores y la salud del servicio de auth se ven normales.

Manténlo simple: una prueba de humo + algunas métricas

Apunta a una prueba de humo que cualquier on-call pueda ejecutar, más 2 a 3 señales de monitorización:

• Prueba de humo (flujo de usuario): realiza una acción real de extremo a extremo (iniciar sesión, crear un registro, hacer un checkout de prueba) y define qué significa “éxito”.
• Métricas clave: elige unas pocas que deberían moverse inmediatamente (tasa de 5xx, fallos de auth, profundidad de colas, latencia p95, logs de error para el endpoint específico).
• Comprobaciones del sistema: confirma que las dependencias están sanas (conexiones a base de datos, tasa de aciertos en cache, estado de terceros si están involucrados).
• Chequeo de regresión: repite la acción que desencadenó el incidente (misma ruta, misma forma de payload, mismo estado de feature flags).
• Guardarraíles: verifica que no se expusieron secretos ni configuraciones de depuración durante la solución.

Si la solución fue un rollback, añade verificación de rollback: confirma que la versión X está en producción, que el endpoint que fallaba devuelve 200 y que la tasa de errores vuelve a la línea base.

Establece una ventana de monitorización y una línea clara de “hecho”

Tras la solución, vigila los gráficos y logs correctos durante 15 a 60 minutos. Escribe qué esperas que se mantenga estable y qué umbral significa que el problema regresó.

Termina con una única línea de “hecho”, por ejemplo: “Hecho cuando la prueba de humo pasa dos veces, la tasa de errores se mantiene por debajo de 1% durante 30 minutos y no aparecen nuevas alertas relacionadas.” Luego documenta:

• qué cambió (commit, config, flag, despliegue o rollback)
• qué comprobaciones ejecutaste y los resultados
• qué harás la próxima vez para detectarlo antes

Sección de comandos: hacer que copiar y pegar sea seguro y predecible

La forma más rápida de convertir un runbook en una herramienta real (y no en un documento que nadie confía) es hacer los comandos seguros para copiar y difíciles de usar mal. Trata el bloque de comandos como un mini producto: entradas claras, salidas claras, advertencias claras.

Empieza con comandos de solo lectura. Coloca los comandos de escritura (reinicios, cambios de config, migraciones) después y añade una advertencia de una línea encima.

Un patrón que funciona bien:

• Usa marcadores como <service>, <env>, <region>, <user_id>, <incident_id> y muestra un ejemplo “conocido bueno”.
• Añade comandos “NO EJECUTAR” cuando la gente tiende a usarlos bajo estrés.
• Indica permisos requeridos al principio (nombre del rol, acceso al sistema y si se necesita acceso de escritura en prod).
• Exige una entrada en el registro de cambios: hora, comando exacto, resultado y el ticket/ID del incidente.
• Di qué significa “éxito” para cada comando (salida esperada o un número que debería cambiar).

# 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 heredaste comandos de despliegue poco claros o scripts de operaciones generados por IA, revísalos antes de convertirlos en “estándar”. Pequeños errores (namespace equivocado, wildcard inseguro, falta de paso de confirmación) pueden crear incidentes repetidos.

Errores comunes que hacen los runbooks inútiles

Los runbooks fallan bajo presión por unas razones previsibles, y la mayoría tienen que ver con la claridad.

La primera trampa es la rendición de cuentas. Un runbook que dice “alguien del backend debería revisar los logs” será ignorado a las 2 a.m. Cada problema recurrente necesita un responsable nombrado (rol o persona) y una ruta clara de escalado.

Otro fallo común es el conocimiento oculto. Pasos que dependen de “la contraseña de siempre”, un dashboard privado o una clave SSH única no son pasos, son esperanzas. Si el acceso es sensible, indica dónde se guardan las credenciales y qué permisos mínimos se necesitan. Si el acceso no está disponible durante un incidente, dilo y apunta a la alternativa.

Vigila estos problemas antes de publicar:

• Sin responsable ni contacto on-call
• Pasos que asumen conocimiento tribal, como dónde están los logs o qué entorno es “el real”
• Sin comprobaciones de verificación, de modo que el síntoma se detiene brevemente y vuelve
• Comandos que han cambiado tras modificaciones de la infraestructura (servicios renombrados, nuevas regiones, diferente herramienta de despliegue)
• “Soluciones” demasiado arriesgadas o vagas, como “reinicia todo” o “cambia la config con cuidado”

La verificación es lo que la gente se salta, y es lo que impide volver a recibir alertas. Después de cada arreglo, incluye pruebas rápidas como “inicio de sesión exitoso con un usuario de prueba”, “tasa de errores por debajo de X” y “no hay nuevos 5xx durante 10 minutos”.

Por último, redacta pensando en el estrés. Si un paso puede causar daño, detalla límites seguros y un rollback.

Ejemplo de runbook: fallos recurrentes de inicio de sesión después de un despliegue

Este runbook de ejemplo cubre un patrón común: los inicios de sesión se rompen justo después de un despliegue.

Escenario: 5 a 10 minutos después del despliegue, los usuarios reportan que no pueden iniciar sesión. El sitio carga, pero el botón de inicio de sesión gira y luego muestra “Algo salió mal”.

Señal de alerta: la tasa de errores de la API para /auth/login salta de <1% a 20%+. Los tickets de soporte mencionan “la contraseña es correcta, aun así falla.”

Responsables: ingeniero on-call (primario), capitán de releases (aprobador para rollback), líder de soporte (comunicación con usuarios).

Triaje y diagnóstico

Confirma el alcance y el cambio más reciente antes de intentar arreglos.

• Confirma impacto: ¿nuevos usuarios, usuarios existentes o ambos? ¿Una región o todas?
• Revisa el último despliegue: ¿qué cambió en auth, configuración, env vars o migraciones de base de datos?
• Inspecciona logs buscando la primera falla después del despliegue (buscar 401 vs 500, env var faltante, errores de firma de token).
• Comprueba dependencias: proveedor de identidad, base de datos, caché, estado del servicio de email.

Pasos de mitigación (elige lo más seguro que aplique)

Usa la acción menos disruptiva primero y para cuando el sistema se recupere.

• Desactiva la feature flag relacionada con login (si está disponible) para enrutar tráfico al camino anterior.
• Revierte la configuración de auth a la última versión conocida buena (común: URL de callback, secreto JWT, dominio de la cookie).
• Reinicia el servicio de auth para que cargue la configuración corregida (solo después de verificar que los secretos están presentes).
• Revertir al despliegue anterior si los errores persisten tras revertir la configuración.

Comprobaciones de verificación

Confirma la experiencia del usuario y las métricas.

• Completa un flujo real de inicio de sesión (usuario de prueba) y confirma que se crea una sesión.
• La tasa de errores vuelve a la línea base durante 10 a 15 minutos y no aparecen nuevos picos en los logs.

Tras el incidente, actualiza el runbook con el patrón de log exacto, la clave de configuración que causó la rotura, la regla para decidir rollback y una comprobación previa al despliegue (por ejemplo: “validar que las env vars de auth requeridas existen en producción”).

Próximos pasos: mantener los runbooks actualizados y reducir incidentes recurrentes

Un runbook solo ahorra tiempo si refleja cómo funciona el sistema hoy. La forma más rápida de acabar con documentación desactualizada es tratar un runbook como “listo” después de escribirlo una vez.

Después de cada incidente, dedica 10 minutos mientras los detalles están frescos y haz pequeñas ediciones: actualiza la redacción del síntoma, añade la línea de log que faltó y captura cualquier nueva trampa encontrada durante la solución.

Antes de cerrar el ticket, haz una prueba rápida de usabilidad:

• El encabezado está completo (servicio, entorno, última actualización, riesgos conocidos)
• Responsables y ruta de escalado están definidos (y siguen siendo correctos)
• Los pasos se probaron recientemente (no solo se escribieron)
• Las comprobaciones de verificación están definidas (qué significa éxito)
• Los comandos son seguros para copiar y pegar (acotados, reversibles y documentados)

Establece una cadencia de revisión simple. Mensual funciona para equipos ocupados, pero mejores disparadores son “después de cada incidente” y “tras cada refactor o actualización de dependencias” para los servicios que más fallan.

Si notas los mismos fallos tras cada despliegue, puede que no sea un problema de runbook sino del código. Es habitual en apps generadas por IA que la autenticación, los secretos y la arquitectura parecen correctos en la demo pero fallan en producción.

Si estás heredando una app generada por IA y sigues apagando incendios por las mismas roturas, FixMyMess (fixmymess.ai) se centra en diagnosticar y reparar esas bases de código: reparación de lógica, endurecimiento de seguridad, refactor y preparación para despliegues. Una auditoría corta puede convertir los “arreglos tribales” repetidos en cambios estables y darte runbooks que coincidan con cómo se comporta realmente el sistema.