Una documentación que explica cómo se construyó un pipeline no basta para operarlo a las tres de la mañana. El runbook debe ayudar a decidir si esperar, reintentar, recuperar un periodo o escalar, sin depender de la memoria de quien lo desarrolló.
Cabecera operativa
Empieza con información que se pueda encontrar rápido:
| Campo | Contenido |
|---|---|
| Propósito | decisión o producto que alimenta |
| Criticidad | impacto y objetivo de disponibilidad/frescura |
| Owner | equipo y canal de guardia |
| Entradas | sistema, dataset, contrato y frecuencia |
| Salidas | tablas, APIs, informes y consumidores |
| Orquestación | workflow, programación y zona horaria |
| Credenciales | referencia al gestor, nunca el secreto |
| Repositorio | código, versión desplegada y configuración |
| Paneles | salud, volumen, calidad y coste |
Incluye un diagrama pequeño del flujo y enlaza el linaje de datos para el detalle navegable.
Define qué significa sano
“Job verde” es insuficiente. Documenta controles de entrada, completitud, duplicados, esquema, periodo y publicación. Añade umbrales y la razón de cada uno. Explica retrasos normales, como una fuente que cierra más tarde el último laborable del mes.
Para cada alerta indica:
- significado y posibles causas;
- consultas o paneles para confirmar;
- acciones seguras;
- acciones prohibidas;
- condición de recuperación;
- cuándo y a quién escalar.
Procedimientos reproducibles
Un runbook útil contiene comandos parametrizados o enlaces a automatizaciones, con entorno y permisos necesarios. Evita “ejecutar el script de siempre”. Para reintento y backfill especifica:
- cómo determinar el periodo afectado;
- cómo detener consumidores si el dato es inseguro;
- cómo lanzar una ejecución idempotente;
- qué evidencias confirman completitud;
- cómo actualizar cachés o salidas;
- cómo comunicar recuperación.
Distingue rollback de datos, reejecución y compensación. Borrar una partición antes de recalcular puede crear una ventana vacía para usuarios.
Mantén contexto de cambios
Registra versiones de esquema, dependencias y decisiones relevantes. Si una dependencia externa cambia su horario o contrato, actualiza documentación junto al código. Asigna una revisión periódica y una prueba de runbook: otra persona sigue el procedimiento en un entorno seguro y anota ambigüedades.
El marco de excelencia operativa de Google Cloud insiste en documentación, automatización, observabilidad y aprendizaje continuo. Tras una incidencia de datos, convierte hallazgos en controles o pasos comprobables; no acumules relatos sin cambiar la operación.
Checklist de relevo
Otro equipo debería poder responder:
- qué consumidores están afectados;
- cuál fue el último periodo correcto;
- si repetir produce duplicados;
- dónde se guarda el cursor incremental;
- cuánto tarda un backfill;
- qué credencial necesita y cómo obtener acceso;
- qué prueba autoriza cerrar la incidencia.
La documentación está terminada cuando permite actuar con seguridad, no cuando describe todos los componentes. Mantén el camino crítico corto y enlaza detalles; durante una alerta, claridad y orden importan más que el volumen de texto.