Hasta ahora has visto contenedores que funcionan y contenedores que fallan de forma evidente. En el trabajo real, la situación más frecuente es la tercera: un contenedor que no funciona y no dice por qué. Está Up 3 hours pero no responde. Sale con código 1 y desaparece antes de que puedas mirarlo. Se marca unhealthy sin más explicación. Y tú, con veinte pestañas abiertas, probando cosas al azar.

Esta lección te da un método y las cinco herramientas que lo sostienen: docker logs, docker exec, docker inspect, docker stats y docker events. Vas a aprender a leerlas a fondo, a entrar en imágenes mínimas que no tienen ni ping, y a extraer del JSON de inspect exactamente el dato que necesitas. Y lo vas a aplicar a tres averías reales de Aurora Libros, entre ellas la que lleva tres lecciones esperándote: por qué aurora-api no encuentra a aurora-db aunque los dos estén corriendo en la misma máquina. Al final de esta lección sabrás la respuesta exacta.

1. Un método antes que un comando
2. docker logs a fondo
3. La regla de oro: stdout y stderr
4. docker exec: entrar en el contenedor
5. Depurar imágenes mínimas sin herramientas
6. docker inspect: el JSON completo del contenedor
7. docker top: los procesos de dentro
8. docker stats: consumo en tiempo real
9. docker events: el flujo del demonio
10. Caso A: el contenedor sale con código 1
11. Caso B: ECONNREFUSED en /libros
12. Caso C: el healthcheck en unhealthy

La diferencia entre alguien que depura rápido y alguien que da palos de ciego no son los comandos, sino el orden en que se hacen las preguntas:

Las cuatro preguntas, en este orden y sin saltarse ninguna:

El error más común es empezar por la 4 —entrar al contenedor a mirar— cuando la respuesta estaba en la 2. Y el segundo error más común es no hacer nunca la 3, quedándose horas convencido de haber pasado una variable de entorno que en realidad tenía una errata.

Las opciones que se usan de verdad:

Combinaciones que resuelven problemas reales:

Tres detalles importantes:

• docker logs funciona con el contenedor parado. Los logs viven en el host y sobreviven a docker stop. Solo desaparecen con docker rm. Es la razón por la que --rm es tu enemigo mientras depuras.
• --tail sin -f es la forma más rápida de ver el final de un log de 100 000 líneas sin volcarlo entero a la terminal.
• Con -f, Ctrl+C solo interrumpe el visor: no toca el contenedor. A diferencia de docker attach, aquí Ctrl+C es completamente seguro.

docker logs muestra exactamente dos cosas: la salida estándar y la salida de error del PID 1. Ni una más.

La tercera línea no aparece por ningún sitio, porque se escribió en un fichero dentro del contenedor. Puedes separar los dos flujos con la redirección estándar del shell:

De ahí sale la regla que gobierna toda la operación de contenedores:

Una aplicación en un contenedor escribe sus logs en la salida estándar y en la salida de error. Nunca en un fichero.

Los motivos:

Tu server.js ya lo hace bien desde la lección 01-07: usa console.log y console.error, que en Node escriben en stdout y stderr respectivamente.

Y una comprobación práctica cuando docker logs está sospechosamente vacío:

Si esos descriptores apuntaran a un fichero en vez de a la consola, ahí tendrías tu explicación.

Un apunte de alcance: dónde se guardan realmente esos logs, cómo cambiar el driver de logging, cómo rotarlos y cómo enviarlos a un sistema centralizado es el contenido de la lección 05-06. Aquí nos quedamos en leerlos.

Ya sabes de la lección 03-01 que exec lanza un proceso nuevo dentro de los namespaces del contenedor, y que por eso salir de él no afecta al servicio. Sus opciones:

Si te equivocas, el error es inconfundible:

Un truco que funciona casi siempre:

Tu aurora-api corre con USER node desde la lección 02-04. Eso está muy bien para producción y es un fastidio para depurar:

Tres cosas que aprender de esta salida:

1. -u root te da privilegios dentro del contenedor aunque la imagen declare otro usuario. La restricción de USER protege del código que corre dentro, no de quien controla el demonio de Docker.
2. Instalar herramientas con apk add dentro de un contenedor en marcha es legítimo para depurar y absolutamente prohibido como forma de "arreglar" nada: en cuanto recrees el contenedor, ese curl desaparece. Lo que se arregla, se arregla en el Dockerfile.
3. Y ahí está el diagnóstico servido en bandeja: errorDb: getaddrinfo ENOTFOUND aurora-db. El endpoint /salud que escribiste en la lección 01-07 está haciendo justo el trabajo para el que lo diseñaste.

Fíjate en /etc/hosts: hay tres entradas y ninguna se llama aurora-db. El comando getent hosts aurora-db ni siquiera imprimió nada (devolvió código 2, "no encontrado"). Guarda ese dato: es la mitad de la respuesta al caso B.

Una imagen bien optimizada no trae curl, ni ping, ni netstat, ni dig. Y las imágenes distroless o construidas FROM scratch no traen ni siquiera un shell. Eso es excelente para la seguridad y el tamaño (lección 05-04) y desesperante cuando algo falla.

La solución moderna: un contenedor efímero cargado de herramientas que comparte los namespaces del contenedor enfermo.

Lo que hace cada opción:

Y ahora, desde dentro de ese contenedor, diagnosticas la red de api-depurar como si estuvieras en él:

Cuatro conclusiones en cuatro comandos, sin instalar nada en la imagen de producción:

1. ss -tlnp confirma que la API sí escucha en el 3000, en 0.0.0.0 (bien: no en 127.0.0.1, que sería inalcanzable desde fuera).
2. ps -ef muestra el node server.js del contenedor vecino gracias a --pid container:, y además que corre con UID 1000.
3. nslookup aurora-db responde NXDOMAIN: el servidor DNS interno de Docker (127.0.0.11) existe y responde, pero no conoce ese nombre.
4. curl funciona aunque la imagen de la API no tenga curl, porque lo aporta netshoot.

Ese NXDOMAIN es la prueba definitiva. Volveremos a ella en el caso B.

Docker Desktop incluye una versión integrada de esta idea:

Abre una shell con un conjunto de herramientas montado sobre el contenedor sin modificarlo: funciona incluso en imágenes distroless sin shell, y al salir no queda ni rastro. Requiere una suscripción Pro o superior; el truco de netshoot es gratuito, funciona en cualquier Docker y conviene conocerlo igualmente.

docker inspect devuelve todo lo que Docker sabe de un contenedor: unas 200 líneas de JSON.

Los seis bloques que importan:

Leer 200 líneas de JSON no es depurar. Lo que se hace es extraer el dato concreto, con --format o con jq:

Un ejemplo completo sobre la flota:

Dos observaciones que serán decisivas dentro de cinco minutos: ambos están en la red bridge y cada uno tiene su propia IP.

Con jq puedes hacer consultas más ricas sobre el JSON crudo:

Nota de seguridad, y es seria: docker inspect muestra las contraseñas en claro. Cualquiera con acceso al demonio de Docker puede leer todas las variables de entorno de todos los contenedores. Por eso las variables de entorno no son un mecanismo de secretos; lo son los gestores de secretos, que se ven en la lección 05-03.

Dos particularidades que lo hacen especial:

• Los PID son los del host, no los de dentro del contenedor. docker exec aurora-db ps mostraría el mismo postgres como PID 1; aquí es el 24817. Es la doble numeración de los namespaces de PID.
• No necesita que la imagen tenga ps. El comando lo ejecuta el demonio en el host. Por eso funciona incluso en imágenes distroless.

Sirve para responder rápido a: ¿cuántos procesos hay?, ¿hay procesos zombis?, ¿está la aplicación lanzando hijos que no debería?

Sin --no-stream, la vista se refresca continuamente como un top. Columna a columna:

Ese LIMIT de 7,628 GiB en las dos filas es la señal de alarma que resolverás en la lección 03-07: ninguno de los dos contenedores tiene límite de memoria, así que cualquiera de ellos puede consumir toda la RAM de la máquina.

Formatos útiles:

docker events es el registro de todo lo que hace el demonio. Sin --since, se queda escuchando en directo. Es la herramienta que responde a preguntas que ninguna otra puede:

Los eventos más útiles: create, start, die (con su exitCode), kill, oom, health_status, restart, destroy, y los de red connect/disconnect. Un oom en esta lista es la confirmación de que fue el kernel y no tú (lección 03-07).

Síntoma: un compañero te dice que la API "no arranca en su máquina". Aplicas el método.

Pregunta 1: ¿está corriendo?

Código 1: de la tabla de la lección 03-02, eso significa que la aplicación arrancó y falló ella misma. No es Docker (sería 125), ni un ejecutable inexistente (127), ni una señal (>128). Así que hay que ir a los logs.

Pregunta 2: ¿qué dicen los logs?

Resuelto en dos comandos y quince segundos. El fichero se llama server.js, no serve.js. ¿De dónde sale ese nombre?

Pregunta 3: ¿cómo está configurado?

Ahí está: el CMD de la imagen (["server.js"]) fue sobrescrito desde la línea de comandos por el argumento suelto serve.js, tal y como aprendiste en la lección 03-01. La imagen está perfecta; el error estaba en el docker run.

Una variante del mismo síntoma que conviene reconocer, porque el diagnóstico es completamente distinto:

El comando docker ps -a no devuelve nada: el contenedor no llegó ni a crearse. Con un 125 no hay logs que mirar ni contenedor que inspeccionar; el error está en tu línea de comandos. Es la primera bifurcación del árbol de decisión y ahorra mucho tiempo perdido.

Aquí está el caso que arrastras desde el módulo 2. Vamos a resolverlo con el método completo.

Pregunta 1: ¿está corriendo?

Los tres están corriendo. No es un problema de arranque.

Pregunta 2: ¿qué dicen los logs?

El mensaje es claro: getaddrinfo es la función de resolución de nombres, y ENOTFOUND significa que el nombre aurora-db no se pudo traducir a ninguna dirección IP. No es un rechazo de conexión: es que la API no sabe a dónde conectarse.

Pregunta 3: ¿cómo está configurado?

Y aquí llega la sorpresa que hace interesante el caso: los tres están en la misma red, la bridge por defecto, con IPs del mismo rango 172.17.0.0/16. No es un problema de aislamiento.

Verifica las variables, por descartar:

Correctas. La configuración es la que querías.

Pregunta 4: ¿qué pasa dentro?

El DNS interno de Docker (127.0.0.11) está configurado, pero no resuelve aurora-db. Confírmalo con herramientas de verdad, usando el truco del apartado 5:

Este es el diagnóstico definitivo, y son dos hechos opuestos en la misma salida:

O sea: aurora-api puede hablar con aurora-db; simplemente no sabe cómo se llama. El problema nunca fue de firewall, ni de puertos, ni de PostgreSQL: es de resolución de nombres.

Y la causa es una característica muy concreta de Docker: la red bridge por defecto no tiene DNS interno entre contenedores. Solo las redes definidas por el usuario lo tienen. Nadie te lo había dicho hasta ahora porque es exactamente el tema de la próxima lección.

¿Y no podrías poner la IP directamente y acabar antes?

Podrías, y sería un error. Esas IPs las asigna Docker en el orden de arranque: reinicia la máquina, cambia el orden de los contenedores y 172.17.0.2 será otro. Escribir IPs a mano es construir un castillo sobre arena. La solución correcta —una red propia donde los nombres funcionen— es la primera práctica de la lección 03-05, y ahora ya sabes exactamente por qué la necesitas.

La incógnita del módulo queda cerrada. Solo falta aplicar la solución.

Síntoma: docker ps muestra Up 40 seconds (unhealthy) en aurora-api. ¿Qué significa exactamente y de dónde sale ese veredicto?

El histórico completo está en .State.Health.Log, un array con los últimos cinco intentos:

Léelo con calma, porque cuenta toda la historia:

Ese 503 no es casual: lo escribiste tú en la lección 01-07. El endpoint /salud devuelve 200 solo si la base de datos y la caché responden, y 503 en cualquier otro caso:

Y ahora el matiz que separa un unhealthy real de un falso positivo:

El contenedor está sano; el servicio no. El proceso node vive, escucha en el 3000 y responde en 173 milisegundos. Lo que está roto son sus dependencias. El HEALTHCHECK está haciendo exactamente lo que le pediste: informar de que este contenedor no está en condiciones de atender tráfico.

Los cuatro estados de salud posibles:

Y el detalle que sorprende a todo el mundo: unhealthy no hace nada por sí solo. Docker Engine no reinicia el contenedor, no lo saca de rotación ni avisa a nadie; se limita a marcarlo y a emitir un evento health_status. Quien actúa sobre esa información es un orquestador (Swarm en la lección 06-03, Kubernetes en la 06-05) o tú, mirando docker ps. Ni siquiera la política --restart reacciona a un unhealthy, y ese matiz se explica en la lección 03-07.

Deja aurora-api como está: en la próxima lección se pondrá healthy solo.

• Empezar por entrar al contenedor. El 70 % de las averías se ven en docker logs en diez segundos. Sigue el orden: estado → logs → configuración → dentro.
• Depurar con --rm. Si el contenedor se borra al morir, no hay logs, ni inspect, ni autopsia. Durante la investigación, sin --rm.
• Buscar logs de una aplicación que escribe en un fichero. docker logs vacío no significa "no pasa nada": comprueba adónde escribe realmente el proceso.
• Instalar herramientas en el contenedor "para arreglarlo". Se pierden al recrearlo. Para diagnosticar, un contenedor efímero con netshoot; para arreglar, el Dockerfile.
• Confundir ECONNREFUSED con ENOTFOUND. El primero dice "el nombre se resolvió pero nadie escucha ahí"; el segundo, "no sé quién es ese". Son dos averías distintas y llevan a sitios distintos.
• Leer docker stats sin límites configurados. La columna LIMIT muestra toda la RAM del host y el MEM % resulta engañosamente tranquilizador.
• Creer que unhealthy reinicia algo. Docker Engine solo lo marca. Sin orquestador, nadie actúa.
• Volcar docker inspect entero en la terminal. Son 200 líneas de JSON. Usa --format o jq y ve directo al dato.
• Consejo: guarda alias para las consultas de inspect que repitas. Por ejemplo dip() { docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' "$1"; }.
• Consejo: docker events en una segunda terminal mientras reproduces el fallo. Ver el die con su exitCode en el instante exacto vale más que diez conjeturas.

Lanza este contenedor, que fallará a propósito, y realiza la investigación completa sin volver a ejecutarlo:

Responde con comandos concretos: ¿en qué estado está y con qué código salió?, ¿ese código apunta a Docker o a la aplicación?, ¿qué escribió en stdout y qué en stderr, por separado?, ¿qué variables de entorno tenía configuradas?, ¿cuál era su comando efectivo?, ¿cuánto tiempo estuvo vivo (calcúlalo con StartedAt y FinishedAt)?

Arranca un contenedor web-mudo con nginx:alpine sin publicar ningún puerto. Después, sin instalar nada dentro de él y sin recrearlo:

1. Averigua su dirección IP.
2. Comprueba desde un contenedor efímero de netshoot que Nginx responde en su puerto 80.
3. Demuestra que desde el host, con curl localhost:80, no responde, y explica por qué eso no contradice el punto anterior.
4. Averigua qué procesos corren dentro sin usar docker exec.

Crea una imagen aurora-api:falso-sano a partir de auroralibros/aurora-api:1.2.0 que sustituya el HEALTHCHECK por uno que compruebe simplemente que el proceso existe (CMD pgrep node || exit 1). Arráncala sin base de datos ni caché y compara, con comandos, el estado de salud que reporta frente al de auroralibros/aurora-api:1.2.0 en las mismas condiciones. Después responde: ¿cuál de los dos healthchecks es "mejor"?, ¿en qué situación concreta el segundo te habría evitado un incidente y en cuál te habría dado una falsa alarma?

Solución al ejercicio 1

El código 78 está en el rango 1–124, así que es de la aplicación, no de Docker. Un 125 habría significado un error del propio docker run, un 127 un ejecutable inexistente y un 137 una señal. Aquí, el programa decidió salir con ese número, así que la explicación está en su código y en sus logs.

La separación de flujos es lo que da el diagnóstico: en stdout hay ruido informativo y en stderr está la causa real. En un log entremezclado de 500 líneas, ese filtro es la diferencia entre encontrarlo y no encontrarlo.

Confirmado: MODO estaba definida y API_KEY no aparece por ninguna parte, que es justo lo que denunciaba el stderr.

Vivió 2,17 segundos, coherentes con el sleep 2 del comando. Ese cálculo es más útil de lo que parece: un contenedor que vive milisegundos suele fallar al arrancar; uno que vive horas y luego muere apunta a una fuga de memoria o a un evento externo.

Solución al ejercicio 2

2. Comprobar que responde, desde netshoot:

Nginx funciona perfectamente. Otra forma, compartiendo directamente su pila de red:

3. Desde el host:

No hay contradicción alguna: el contenedor escucha en el puerto 80 de su propia pila de red, pero como no se publicó ningún puerto con -p, no existe ninguna regla que reenvíe el puerto 80 del host hacia él. La conectividad existe dentro de la red de Docker (donde vive netshoot) y no existe desde el host. Es justo la distinción entre "publicar un puerto" y "que dos contenedores se hablen" que se formaliza en la lección 03-05.

4. Procesos sin docker exec:

docker top lo ejecuta el demonio en el host, así que no necesita entrar en el contenedor ni que la imagen tenga ps. Y de propina se ve la buena práctica de Nginx: el master corre como root y los workers como el usuario 101.

Solución al ejercicio 3

Dos contenedores idénticos en todo salvo en su comprobación de salud, y veredictos opuestos. El de la izquierda dice estar sano; ninguno de los dos puede servir un solo libro.

El healthcheck falso responde 0 porque pgrep node encuentra el proceso. Y tiene toda la razón: el proceso está vivo. Simplemente está midiendo lo que no importa.

Las respuestas:

• El de auroralibros/aurora-api:1.2.0 es mejor en este escenario, porque comprueba la capacidad real de dar servicio (una petición HTTP de extremo a extremo, que a su vez consulta la base de datos y la caché) en lugar de la mera existencia de un proceso.
• Cuándo te habría salvado el segundo (pgrep): cuando la caída es de una dependencia y no quieres que todas tus réplicas se declaren enfermas a la vez. Si PostgreSQL se cae 30 segundos, con el healthcheck estricto las diez réplicas de la API pasan a unhealthy simultáneamente, el orquestador las saca de rotación y te quedas con un corte total en lugar de un servicio degradado que aún sirve lo cacheado. Es el conocido efecto dominó de los healthchecks demasiado profundos.
• Cuándo te habría dado una falsa alarma... o peor, ninguna: cuando el proceso de Node está vivo pero su bucle de eventos está bloqueado, el pool de conexiones agotado o respondiendo 500 a todo. pgrep diría "sano" indefinidamente mientras los usuarios ven errores. Ese escenario es literalmente el que motivó HEALTHCHECK en la lección 02-04.

La solución profesional, que apuntabas ya en el ejercicio 3 de la lección 02-04, es separar dos endpoints: uno de vivacidad (/salud/vivo, superficial, para decidir reinicios) y otro de disponibilidad (/salud, profundo, para decidir si recibe tráfico). Es la distinción entre liveness y readiness que se desarrolla en la lección 06-05.

Tienes un método, y eso vale más que la lista de comandos: ¿está corriendo? → ¿qué dicen los logs? → ¿cómo está configurado? → ¿qué pasa dentro?, en ese orden y sin saltarse pasos. Sabes que un Created señala un ejecutable inexistente, que un 125 significa que el contenedor ni se creó y no hay nada que inspeccionar, y que un código entre 1 y 124 manda directamente a docker logs.

Manejas docker logs con sus ventanas de tiempo, su --tail y su -f que puedes cortar con Ctrl+C sin miedo, y tienes grabada la regla de oro: los contenedores logean a stdout y stderr, nunca a un fichero, y sabes separar los dos flujos con una redirección para que el error aparezca solo. Entras con docker exec eligiendo el shell correcto según la base, sabes que -u root te da privilegios aunque la imagen declare USER node, y —lo más valioso— sabes depurar imágenes mínimas sin herramientas lanzando un contenedor efímero de netshoot que comparte los namespaces de red y de procesos del enfermo, sin ensuciar la imagen de producción.

Del JSON de docker inspect extraes el dato exacto con plantillas Go y jq, con una tabla de consultas para IP, redes, puertos, montajes, entorno, salud, código de salida y reinicios, y sabes que ese mismo comando muestra las contraseñas en claro, razón por la que las variables de entorno no son un mecanismo de secretos. Con docker top ves los procesos desde el host aunque la imagen no tenga ps, con docker stats interpretas las siete columnas —y has descubierto que tus contenedores no tienen ningún límite de memoria— y con docker events reconstruyes qué pasó y cuándo.

Y has cerrado la investigación que arrastrabas desde el módulo 2. aurora-api, aurora-db y aurora-cache están en la misma red y con conectividad plena entre ellos: nc -zv 172.17.0.2 5432 responde succeeded. Lo que falla es una sola cosa, y ahora la sabes nombrar con precisión: nslookup aurora-db devuelve NXDOMAIN, porque la red bridge por defecto no tiene DNS interno entre contenedores. No es un cortafuegos, ni un puerto, ni PostgreSQL: es que la API no sabe cómo se llama su base de datos.

Solo falta aplicar la solución, y es más corta que el diagnóstico. En la siguiente lección, Redes en Docker, verás por qué cada contenedor tiene su propia pila de red y su propio localhost, compararás los drivers bridge, host y none, y entenderás la diferencia decisiva entre la bridge por defecto y una red definida por el usuario, donde el DNS interno resuelve nombres de contenedor automáticamente. Crearás aurora-net, recrearás los tres servicios dentro de ella, y ejecutarás por fin ese curl http://localhost:3000/libros que lleva seis lecciones esperando para devolverte El jardín de senderos que se bifurcan, Rayuela y los otros seis títulos. Después añadirás aurora-web como proxy inverso, y la plataforma de Aurora Libros estará viva de verdad.