Antes de empezar#

«El servicio está caído» mezcla una observación con una explicación. Puede significar que una persona recibió un error, que un monitor no obtuvo respuesta, que un nombre resolvió a un destino inesperado o que un proceso terminó. Cada frase describe un alcance distinto y conduce a pruebas diferentes.

Diagnosticar consiste en reducir incertidumbre de forma controlada. El objetivo no es ejecutar muchas herramientas, sino elegir la siguiente observación que más ayude a separar causas plausibles sin empeorar el sistema.

Dependencias. Unidad 1.1 para razonar por capas y estado; Unidad 1.2 para interpretar comandos, flujos y códigos de salida.

Alcance. Impacto, síntoma, estado esperado y observado, línea temporal, baseline, hipótesis, pruebas discriminantes, sesgos, mitigación, cambio controlado, verificación, rollback y registro.

Fuera de alcance. Coordinación formal de incidentes grandes, comunicación ejecutiva, guardias, postmortems completos y diseño de sistemas de observabilidad.

1. Síntoma, impacto y causa#

Un síntoma es una diferencia observable entre lo esperado y lo real. El impacto indica quién o qué operación está afectada y con qué alcance. Una causa es un mecanismo que explica las observaciones y permite predecir otras.

esperado: GET /health responde 200 desde la red de usuarios
observado: timeout desde dos clientes externos desde las 10:14
impacto: esos clientes no pueden completar la operación
causa: todavía desconocida

Este informe es más útil que «la API está rota» porque contiene operación, perspectiva, resultado, alcance y tiempo.

2. Estado inicial, baseline y línea temporal#

Antes de cambiar, reúne un estado inicial mínimo:

• qué operación falla y cuál todavía funciona;
• desde qué host, identidad o red se observa;
• cuándo comenzó y si es continuo o intermitente;
• qué cambió cerca de ese momento;
• qué valores eran normales antes;
• qué proceso, socket, nombre o dependencia se esperaba encontrar;
• qué evidencia puede desaparecer al reiniciar.

El baseline no tiene que ser una plataforma compleja. Puede ser una ejecución anterior, un host equivalente, una respuesta conocida o una configuración versionada. Su función es distinguir «extraño» de «nuevo».

Una línea temporal ordena hechos sin convertir cercanía en causalidad:

10:08 despliegue completado
10:12 primera subida de errores observada
10:14 primer informe de usuario
10:18 prueba por loopback correcta
10:20 nombre resuelve a dos direcciones

El despliegue es sospechoso, pero todavía no explica por qué el síntoma aparece cuatro minutos después ni por qué loopback funciona.

3. Construir hipótesis#

Una hipótesis útil es concreta, compatible con las observaciones y refutable:

H1: no existe un proceso servidor.
H2: existe proceso, pero no hay socket en la dirección y puerto esperados.
H3: el socket responde localmente, pero el filtrado o la ruta impiden llegar desde el cliente.
H4: el nombre conduce a otro destino.
H5: la petición llega, pero la aplicación o una dependencia no responde.

El modelo de capas ayuda a no saltar directamente a la explicación favorita. Agrupa hipótesis por fronteras: cliente, resolución, ruta, filtrado, transporte, proceso, protocolo, aplicación y dependencia.

Ordena las hipótesis combinando:

1. compatibilidad con las señales actuales;
2. probabilidad basada en el contexto, no en costumbre;
3. impacto si fuese cierta;
4. coste y riesgo de comprobarla;
5. capacidad de la prueba para separar varias ramas.

Una hipótesis de baja probabilidad puede subir de prioridad si su impacto es extremo y la comprobación es barata.

4. La prueba discriminante#

La mejor siguiente prueba no es necesariamente la herramienta más potente. Es la que produce resultados diferentes para hipótesis relevantes.

Antes de ejecutar, escribe:

hipótesis que comparo:
resultado esperado si H1:
resultado esperado si H2:
señal que conservaré:
riesgo y alcance:

Si ambos resultados esperados son iguales, la prueba no discrimina esas hipótesis.

5. Evidencia y perspectiva#

Toda señal pertenece a una perspectiva:

• una petición desde el cliente describe el camino que ese cliente puede completar;
• ss en el servidor muestra sockets en ese espacio de red;
• el estado del gestor describe su unidad y procesos conocidos;
• un log cuenta lo que el código decidió registrar;
• una métrica agrega eventos según una definición;
• una captura de paquetes muestra tráfico en una interfaz y momento concretos.

La misma herramienta ejecutada desde otro host puede responder otra pregunta.

Conserva fragmentos mínimos con hora, origen y comando. Un volcado enorme sin contexto es difícil de revisar y puede exponer secretos. Una línea seleccionada sin la consulta que la produjo es difícil de reproducir.

6. Demostración: servicio aparentemente caído#

Partimos de este informe:

Desde client-a, api.example.test/health agota 3 s.
Comenzó entre 10:10 y 10:15.
No se ha cambiado todavía el servidor.

No asumimos que el servicio esté detenido. Construimos cuatro ramas iniciales: proceso, socket, trayecto/filtrado y nombre.

Prueba 1: estado local sin modificar. En el servidor se observa un proceso esperado y un socket en 127.0.0.1:8080, pero no en la interfaz externa.

Esto debilita «proceso ausente» y hace más precisa la rama del socket: el proceso escucha, pero solo en loopback. Todavía no sabemos si ese diseño es incorrecto; puede existir un proxy local previsto.

Prueba 2: petición por loopback. El endpoint responde 200 desde el servidor. Confirma que ese camino local llega a una aplicación capaz de responder. No valida el camino del cliente.

Prueba 3: resolución desde el cliente. El nombre devuelve la dirección esperada. Esto reduce la hipótesis de destino equivocado, sin descartar caché en otros clientes ni problemas posteriores.

Prueba 4: observar el extremo público esperado. No existe proxy ni socket en la dirección y puerto publicados. Ya tenemos una explicación compatible: el único listener está limitado a loopback y no hay intermediario que exponga el servicio.

síntoma remoto
├─ proceso ausente                     debilitada: proceso observado
├─ aplicación falla localmente         debilitada: /health local responde
├─ nombre apunta a otro destino        debilitada: respuesta esperada en client-a
└─ no existe extremo público           apoyada: no hay listener/proxy esperado

La evidencia no autoriza todavía cualquier corrección. Hay que comprobar cuál era la arquitectura deseada: cambiar el bind de la aplicación y configurar un proxy no son decisiones equivalentes.

7. Sesgos y cambios recientes#

Los cambios recientes son una fuente valiosa de hipótesis, no una sentencia. La correlación temporal puede ser coincidencia o revelar una condición que tardó en manifestarse.

Sesgos frecuentes:

• confirmación: buscar solo señales compatibles con la primera idea;
• disponibilidad: elegir la causa que recuerdas de la última incidencia;
• anclaje: conservar la primera estimación pese a evidencia nueva;
• autoridad: aceptar una explicación por quién la propuso;
• acción: preferir cambiar algo porque observar parece lento.

8. Mitigar, cambiar y revertir#

Una mitigación reduce impacto; una corrección elimina o controla la causa. Reiniciar puede mitigar una fuga de recursos sin corregirla. Desviar tráfico puede restaurar servicio mientras se investiga el host.

Antes de un cambio:

1. nombra la hipótesis que lo justifica;
2. define el estado exacto que modificará;
3. limita el alcance a un intento o componente;
4. conserva el estado anterior;
5. establece condición de parada;
6. prepara rollback;
7. decide qué señal demostrará mejora y cuál revelará regresión.

El rollback también se verifica. Restaurar un archivo no demuestra que el proceso lo haya cargado ni que el estado previo fuese saludable.

9. Verificar desde la perspectiva correcta#

La verificación debe responder al síntoma original, no solo al mecanismo modificado:

cambio: el proxy vuelve a escuchar en el extremo previsto
verificación local: proceso y socket presentes
verificación funcional: /health responde por el camino público
verificación de usuario: client-a completa la operación
regresión: logs y tasa de errores no empeoran
persistencia: la configuración sobrevive al ciclo previsto

Una comprobación interna puede ser necesaria sin ser suficiente. Si el impacto era remoto, terminar en systemctl active deja sin probar la ruta, el protocolo y la operación del usuario.

10. Registrar la investigación#

Una bitácora útil conserva decisiones, no una transcripción indiscriminada:

Incluye:

• quién y desde dónde observó;
• comando o consulta exactos;
• fragmento mínimo con hora;
• cambio realizado y estado previo;
• resultado esperado y real;
• rollback ejecutado o pendiente;
• hipótesis descartadas.

Esto permite que otra persona continúe sin repetir cambios ni depender de memoria.

11. Errores conceptuales frecuentes#

12. Síntesis y dominio#

Un diagnóstico riguroso comienza describiendo impacto, alcance, tiempo y diferencia entre lo esperado y lo observado. Después construye hipótesis causales, elige una prueba que las separe, conserva evidencia, modifica una sola variable cuando corresponde y verifica el resultado desde la perspectiva afectada.

Has alcanzado el dominio esperado cuando puedes:

• separar síntoma, impacto, observación, inferencia y causa;
• construir y ordenar un árbol pequeño de hipótesis;
• anticipar resultados distintos antes de una prueba;
• explicar el límite de cada señal;
• proponer un cambio acotado con verificación y rollback;
• registrar resultados positivos y negativos sin reescribir la historia.

Prácticas relacionadas#

• SYS-I-103: investigar un servicio aparentemente caído.
• SYS-RV-103: revisar una bitácora de cambios a ciegas.

13. Fuentes#

• Google SRE — Effective Troubleshooting

  Método hipotético-deductivo, informe del problema, triage, observación, simplificación, pruebas controladas, documentación y valor de resultados negativos.

• Google SRE — Monitoring Distributed Systems

  Diferencia entre síntomas orientados al usuario y causas internas, y selección de señales útiles para disponibilidad, errores, latencia y saturación.