Módulo 7: Blameless Postmortems And Runbooks
5. Qué es (y qué no es) un runbook
Descripción
POSTMORTEM.md mira hacia atrás: qué pasó, por qué, qué salió bien y qué salió mal. Un runbook mira hacia adelante: qué hacer, paso por paso, la próxima vez que una condición específica se repita — sin necesitar entender de nuevo, desde cero, todo el contexto del incidente que lo motivó. Esta lección establece esa distinción con precisión, con una fuente de mercado citada directamente, antes de que la lección 6 construya el primer runbook real de Andes Cargo.
Conexión con el módulo
El action item #3 de la lección 4 —escribir runbooks/manifest-processor-error-rate.md— es exactamente el entregable que esta lección prepara conceptualmente. La lección 6 no puede construir un buen runbook sin que esta lección primero establezca qué distingue un buen runbook de una mala imitación de un postmortem con numeración.
La analogía: la lista de emergencia pegada en la cabina
Un piloto comercial no memoriza, de memoria pura, qué hacer ante cada posible falla de un avión — hay demasiadas combinaciones, y bajo presión real la memoria falla de formas impredecibles. En su lugar, cada cabina tiene una lista de verificación de emergencia (checklist), física o digital, con pasos numerados, condicionales claros ("si la presión de cabina cae por debajo de X, entonces..."), y ningún párrafo de contexto histórico sobre por qué esa lista existe. Alguien medio dormido, en la mitad de la noche, con una alarma sonando, puede seguirla sin pensar —literalmente sin necesitar pensar, porque pensar bajo presión real es exactamente lo que la lista existe para reemplazar—.
Un runbook de SRE cumple la misma función, para el mismo tipo de momento: la alarma del Módulo 4 dispara a las 3 AM, la persona de guardia (Módulo 5) no necesita reconstruir, desde cero, qué significa esa alarma ni por qué existe — sigue los pasos exactos que alguien, con la cabeza despejada, ya pensó de antemano y verificó que funcionan.
POSTMORTEM vs RUNBOOK -- DOS DOCUMENTOS, DOS MOMENTOS DISTINTOS
POSTMORTEM (Leccion 3) RUNBOOK (Leccion 6)
─────────────────────── ────────────────────
Se escribe DESPUES de un incidente, Se escribe ANTES del proximo
con tiempo para pensar con cuidado incidente, para usarse CON PRISA
│ │
▼ ▼
Mira hacia atras: "¿que paso, y Mira hacia adelante: "¿que
por que?" hago, paso por paso, ahora?"
│ │
▼ ▼
Denso en contexto, causa raiz, Denso en pasos accionables,
analisis -- se lee una vez, con pobre en contexto -- se sigue
calma, para aprender bajo presion, sin pensar
│ │
▼ ▼
Exito = entender el sistema mejor Exito = resolver la condicion
que antes especifica mas rapidoPaso 1 — La definición, citada de mercado
PagerDuty —ya citada en el Módulo 4 de esta guía como el destino real de una alerta de producción— publica una definición pública de runbook que vale la pena citar completa, porque distingue con precisión los dos términos que suelen confundirse:
"A runbook is a detailed 'how-to' guide for completing a commonly repeated task or procedure within a company's IT operations process."
Y, sobre la diferencia específica con un playbook —un documento de alcance mayor, que puede incluir varios runbooks—:
"A playbook deals with the overarching responses to larger issues and events, and can include multiple runbooks and team members as part of the complete workflow."
La misma fuente ofrece una analogía casi idéntica a la de esta lección, con una variación útil: si un runbook es una receta, el playbook es la guía completa para organizar el evento — la receta resuelve un componente específico de una respuesta más grande, orquestada. El runbook que la lección 6 construye —qué hacer cuando la alarma de manifest-processor-error-rate dispara— es, con precisión, una receta: resuelve una condición específica, no "cómo responder a cualquier incidente de Andes Cargo en general" (eso ya lo cubre INCIDENT-RESPONSE-PLAN.md, el equivalente más cercano de esta guía a un playbook).
Paso 2 — Qué contiene un buen runbook, de mercado
La misma fuente cita el trabajo de Tom Limoncelli —una referencia reconocida en operaciones de sistemas— sobre las secciones que un runbook completo debería tener:
| Sección (Limoncelli, citada por PagerDuty) | Qué contesta |
|---|---|
| Service overview | ¿Qué es este servicio, en una frase? |
| Service build information | ¿Cómo se construye/despliega este servicio? |
| Instructions for deploying the software | Pasos concretos de despliegue |
| Instructions for common tasks | Las operaciones rutinarias más frecuentes |
| "Pager playbook" (monitoring alerts, step by step) | Qué hacer cuando una alerta específica dispara |
| Disaster recovery plans | Qué hacer ante una pérdida total |
| Service level agreement | Qué nivel de servicio se promete |
El runbook de la lección 6 —manifest-processor-error-rate.md— corresponde, con precisión, a la quinta fila de esta lista: un "pager playbook" para una alerta específica, no un documento que intenta cubrir las siete filas a la vez. Esta lección adopta esa misma disciplina de alcance acotado: un runbook completo, útil, no necesita ser un manual completo del servicio — necesita resolver bien una condición específica.
Paso 3 — Las tres propiedades que la fuente de mercado exige, y por qué cada una importa bajo presión
La misma fuente es explícita sobre qué hace que un runbook funcione de verdad, no solo que exista:
"Runbooks should be clear and simple [...] use easy to understand language [...] be specific and unique to your processes [...] remain flexible and adaptable to changes."
Tres de estas cuatro propiedades merecen una explicación de por qué importan específicamente bajo presión, no en abstracto:
- Claro y simple, con lenguaje fácil de entender: a las 3 AM, con una alarma sonando, la capacidad de procesamiento cognitivo de cualquier persona está reducida — un runbook escrito con la misma densidad que un documento de arquitectura obliga a releer cada paso dos veces, exactamente el tiempo que un runbook existe para ahorrar.
- Específico y único a tus propios procesos: un runbook genérico, copiado de un blog o de una plantilla, casi nunca coincide exactamente con el sistema real — la lección 6 de este módulo construye el runbook contra la alarma real, el SNS real, los comandos reales de Andes Cargo, no una versión genérica de "cómo responder a un Lambda con errores".
- Flexible y adaptable a cambios: un runbook que nadie actualiza cuando el sistema cambia se vuelve, con el tiempo, peor que no tener ningún runbook — porque genera confianza falsa en pasos que ya no aplican. Esta propiedad es la razón por la que la lección 6 etiqueta con precisión qué partes del runbook son literales (los pasos que corrieron de verdad) y cuáles son representativas (
awslocalsinLOCALSTACK_AUTH_TOKEN) — un runbook honesto sobre sus propios límites es más fácil de mantener actualizado que uno que finge una certeza que no tiene.
Paso 4 — Por qué un runbook y un postmortem no se pueden fusionar en un solo documento
Vale la pena resolver, con precisión, por qué esta guía —y la disciplina de SRE en general— insiste en mantener estos dos documentos separados, en vez de combinarlos en uno solo "más completo":
| Propiedad | Postmortem | Runbook |
|---|---|---|
| Cuándo se lee | Una vez, después del incidente, para aprender | Repetidamente, cada vez que la condición se repite |
| Bajo qué presión se lee | Sin prisa, con tiempo para reflexionar | Con prisa, bajo una alarma activa |
| Qué densidad de contexto necesita | Alta — causa raíz, qué salió bien/mal | Baja — pasos accionables, contexto mínimo |
| Qué pasa si está desactualizado | Sigue siendo un registro histórico válido | Se vuelve activamente peligroso — pasos que ya no aplican, seguidos bajo presión |
| Quién lo escribe | El Incident Commander, después del incidente (Módulo 5, lección 4) | Cualquier persona con el conocimiento operativo, antes de que haga falta |
La última fila es, tal vez, la diferencia más importante en la práctica: un postmortem desactualizado sigue siendo útil como historia; un runbook desactualizado es peligroso, porque alguien bajo presión real puede seguir un paso que ya no corresponde al sistema actual, con consecuencias reales. Fusionar ambos documentos en uno solo mezclaría contenido que necesita mantenerse actualizado con precisión (los pasos operativos) con contenido que es, por naturaleza, un registro histórico fijo (el análisis del incidente que ya pasó) — la separación no es burocracia, es la misma disciplina de responsabilidad única que ya rige cada documento de esta guía.
Errores comunes
Escribir un runbook que empieza con dos páginas de contexto histórico sobre el incidente que lo motivó (de confundir runbook con postmortem, en estructura). Qué pasa: alguien, al escribir el runbook de la lección 6, abre el documento narrando el incidente Claude Code completo antes de llegar al primer paso accionable. Cómo detectarlo: si alguien tiene que leer más de un par de líneas antes de encontrar el primer paso que puede ejecutar. Cómo corregirlo: el contexto histórico —por qué este runbook existe, qué incidente lo motivó— pertenece, como mucho, a una línea de referencia al postmortem correspondiente, no a una narración completa. La fuente del Paso 1 es explícita: un runbook es una guía de "cómo hacer", no un documento de "por qué llegamos aquí".
Asumir que un runbook, una vez escrito, no necesita revisarse nunca más (de perder la propiedad "flexible y adaptable" del Paso 3). Qué pasa: alguien trata el runbook de la lección 6 como un documento terminado para siempre, sin ningún proceso para actualizarlo cuando la alarma, el comando o la infraestructura que describe cambien. Cómo detectarlo: si el runbook menciona un nombre de alarma, un comando o un umbral que ya no coincide con observability.tf actual. Cómo corregirlo: cada vez que andes-cargo-infra/ cambia algo que un runbook describe —el nombre de una alarma, un umbral, un comando de diagnóstico— ese runbook necesita una revisión correspondiente, la misma disciplina de mantenimiento que cualquier pieza de infraestructura como código ya exige.
Escribir un runbook genérico, copiado de una plantilla pública, sin adaptarlo a los comandos y nombres reales de Andes Cargo (de violar la propiedad "específico y único" del Paso 3). Qué pasa: alguien escribe pasos como "revisa los logs de tu servicio" o "verifica la métrica relevante", sin nombrar el comando exacto, el nombre exacto de la alarma, o la tabla exacta involucrada. Cómo detectarlo: si tu runbook podría aplicarse, sin ningún cambio, a cualquier otro proyecto que no sea Andes Cargo. Cómo corregirlo: la lección 6 de este módulo construye el runbook contra andes-cargo-manifest-error-budget-burn-rate (el nombre exacto de la alarma del Módulo 4, lección 5), process-shipment-manifest (el Lambda exacto), y comandos awslocal con los nombres reales de recursos — nunca una versión genérica que obligue a alguien, bajo presión, a "traducir" el paso al sistema real.
Ejercicios
Ejercicio 1 — Clasifica cada uno de los siguientes documentos de esta guía como runbook, postmortem, o ninguno de los dos, y justifica cada respuesta con el Paso 4 de esta lección: TIMELINE.md, INCIDENT-RESPONSE-PLAN.md, runbooks/manifest-processor-error-rate.md.
Ver solución
TIMELINE.md no es ninguno de los dos exactamente — es un registro cronológico de hechos, el insumo del postmortem, pero sin la sección de causa raíz ni de action items que definen a un postmortem completo (Módulo 6, lección 8 ya lo estableció: "no analiza causa raíz — eso es el Módulo 7"). INCIDENT-RESPONSE-PLAN.md se parece más a lo que la fuente de esta lección llama un playbook — un marco de alcance mayor (ciclo de vida, severidad, roles) que puede incluir múltiples runbooks específicos, no un procedimiento paso a paso para una sola condición—. runbooks/manifest-processor-error-rate.md es, con precisión, un runbook: acotado a una sola condición (la alarma del Módulo 4 dispara), con pasos accionables, mínimo contexto histórico, escrito antes de que la próxima vez que la alarma dispare de verdad ocurra.
Ejercicio 2 — Explica, usando la cita de PagerDuty del Paso 1, por qué INCIDENT-RESPONSE-PLAN.md (Módulo 5) se parece más a un playbook que a un runbook, aunque esta guía nunca use esa palabra para describirlo.
Ver solución
La cita del Paso 1 define un playbook como algo que "deals with the overarching responses to larger issues and events, and can include multiple runbooks and team members as part of the complete workflow" — exactamente la descripción de INCIDENT-RESPONSE-PLAN.md: cubre el ciclo de vida completo de cualquier incidente (no una condición específica), coordina múltiples roles (IC, OL, CL), y está diseñado para que, dentro de él, existan runbooks específicos (como el de la lección 6) que se invocan según el tipo de incidente. Esta guía nunca usa la palabra "playbook" para describirlo porque no es un término que el resto de este ecosistema haya adoptado, pero la estructura —alcance amplio, coordinación de varios roles, capaz de incluir múltiples procedimientos específicos— coincide con la definición de mercado citada aquí.
Ejercicio 3 — Un compañero argumenta que, ya que un runbook "no necesita explicar el por qué", cualquier runbook que incluya una sola frase de contexto está mal escrito. ¿Estás de acuerdo, usando el Paso 4 de esta lección?
Ver solución
En desacuerdo, con un matiz. El Paso 4 no dice que un runbook nunca puede incluir contexto — dice que la densidad de contexto debe ser baja, no cero, y que el contexto extenso (el "por qué" completo) pertenece al postmortem, no al runbook. Una sola línea de referencia —por ejemplo, "esta alarma existe porque mide la misma proporción de error que SLO.md define como aceptable; ver POSTMORTEM.md para el análisis completo del incidente que motivó este documento"— no viola la propiedad de "claro y simple": ayuda a quien lo sigue a entender, en una frase, por qué el paso importa, sin obligarlo a leer un documento completo antes de poder actuar. Lo que sí viola la disciplina es reemplazar los pasos accionables con ese contexto, o extenderlo más allá de una o dos líneas de referencia.
Resumen y siguiente paso
Esta lección estableció la distinción central entre un postmortem (mira hacia atrás, denso en contexto, se lee una vez con calma) y un runbook (mira hacia adelante, denso en pasos accionables, se sigue bajo presión), citando la definición de mercado de PagerDuty y las siete secciones de un runbook completo según Tom Limoncelli. Confirmaste por qué ambos documentos deben mantenerse separados —un postmortem desactualizado sigue siendo historia válida; un runbook desactualizado es activamente peligroso— y las tres propiedades que un runbook real necesita: claro y simple, específico y único al sistema real, flexible ante los cambios.
Antes de avanzar deberías poder: citar la definición de runbook de PagerDuty; explicar la diferencia entre un runbook y un playbook; y justificar por qué fusionar un postmortem con un runbook en un solo documento sería un error de diseño, no solo una preferencia de estilo.
La lección 6 construye, con esta disciplina completa, el primer runbook real de Andes Cargo: qué hacer cuando la alarma andes-cargo-manifest-error-budget-burn-rate del Módulo 4 dispara de verdad.
Recursos
- PagerDuty — What Is a Runbook? — fuente de cada cita textual de esta lección, incluida la distinción runbook/playbook y las siete secciones de Limoncelli.
- Google SRE Workbook — Postmortem Culture — el documento que esta lección contrasta con un runbook, ya construido en la lección 3.
- Este mismo repositorio, Módulo 4, lección 5 (
05-hands-on-a-real-cloudwatch-alarm-on-the-lambda.md) — la alarma real que el runbook de la lección 6 va a operar. - Este mismo repositorio, Módulo 5, lección 8 (
08-project-andes-cargos-incident-response-plan.md) —INCIDENT-RESPONSE-PLAN.md, el documento de alcance mayor que esta lección compara con un playbook.