Fins ara has vist contenidors que funcionen i contenidors que fallen de manera evident. A la feina real, la situació més freqüent és la tercera: un contenidor que no funciona i no diu per què. Està Up 3 hours però no respon. Surt amb codi 1 i desapareix abans que el puguis mirar. Es marca unhealthy sense cap més explicació. I tu, amb vint pestanyes obertes, provant coses a l'atzar.

Aquesta lliçó et dona un mètode i les cinc eines que el sostenen: docker logs, docker exec, docker inspect, docker stats i docker events. Aprendràs a llegir-les a fons, a entrar en imatges mínimes que no tenen ni ping, i a extreure del JSON d'inspect exactament la dada que necessites. I ho aplicaràs a tres avaries reals d'Aurora Libros, entre elles la que fa tres lliçons que t'espera: per què aurora-api no troba aurora-db encara que tots dos estiguin corrent a la mateixa màquina. Al final d'aquesta lliçó en sabràs la resposta exacta.

1. Un mètode abans que una comanda
2. docker logs a fons
3. La regla d'or: stdout i stderr
4. docker exec: entrar al contenidor
5. Depurar imatges mínimes sense eines
6. docker inspect: el JSON complet del contenidor
7. docker top: els processos de dins
8. docker stats: consum en temps real
9. docker events: el flux del dimoni
10. Cas A: el contenidor surt amb codi 1
11. Cas B: ECONNREFUSED a /llibres
12. Cas C: el healthcheck en unhealthy

La diferència entre algú que depura ràpid i algú que dona pals de cec no són les comandes, sinó l'ordre en què es fan les preguntes:

Les quatre preguntes, en aquest ordre i sense saltar-se'n cap:

L'error més comú és començar per la 4 —entrar al contenidor a mirar— quan la resposta era a la 2. I el segon error més comú és no fer mai la 3, quedant-se hores convençut d'haver passat una variable d'entorn que en realitat tenia una errada.

Les opcions que es fan servir de debò:

Combinacions que resolen problemes reals:

Tres detalls importants:

• docker logs funciona amb el contenidor aturat. Els registres viuen al host i sobreviuen a docker stop. Només desapareixen amb docker rm. És la raó per la qual --rm és el teu enemic mentre depures.
• --tail sense -f és la manera més ràpida de veure el final d'un registre de 100.000 línies sense bolcar-lo sencer al terminal.
• Amb -f, Ctrl+C només interromp el visor: no toca el contenidor. A diferència de docker attach, aquí Ctrl+C és completament segur.

docker logs mostra exactament dues coses: la sortida estàndard i la sortida d'error del PID 1. Ni una més.

La tercera línia no apareix enlloc, perquè es va escriure en un fitxer dins del contenidor. Pots separar els dos fluxos amb la redirecció estàndard del shell:

D'aquí surt la regla que governa tota l'operació de contenidors:

Una aplicació en un contenidor escriu els seus registres a la sortida estàndard i a la sortida d'error. Mai en un fitxer.

Els motius:

El teu server.js ja ho fa bé des de la lliçó 01-07: fa servir console.log i console.error, que a Node escriuen a stdout i stderr respectivament.

I una comprovació pràctica quan docker logs està sospitosament buit:

Si aquests descriptors apuntessin a un fitxer en comptes de a la consola, allà tindries la teva explicació.

Un apunt d'abast: on es desen realment aquests registres, com canviar el driver de logging, com rotar-los i com enviar-los a un sistema centralitzat és el contingut de la lliçó 05-06. Aquí ens quedem a llegir-los.

Ja saps de la lliçó 03-01 que exec llança un procés nou dins dels namespaces del contenidor, i que per això sortir-ne no afecta el servei. Les seves opcions:

Si t'equivoques, l'error és inconfusible:

Un truc que funciona gairebé sempre:

El teu aurora-api corre amb USER node des de la lliçó 02-04. Això està molt bé per a producció i és una molèstia per depurar:

Tres coses per aprendre d'aquesta sortida:

1. -u root et dona privilegis dins del contenidor encara que la imatge declari un altre usuari. La restricció d'USER protegeix del codi que corre a dins, no de qui controla el dimoni de Docker.
2. Instal·lar eines amb apk add dins d'un contenidor en marxa és legítim per depurar i absolutament prohibit com a manera d'"arreglar" res: tan bon punt recreïs el contenidor, aquell curl desapareix. El que s'arregla, s'arregla al Dockerfile.
3. I aquí tens el diagnòstic servit en safata: errorDb: getaddrinfo ENOTFOUND aurora-db. L'endpoint /salut que vas escriure a la lliçó 01-07 està fent just la feina per a la qual el vas dissenyar.

Fixa't en /etc/hosts: hi ha tres entrades i cap no es diu aurora-db. La comanda getent hosts aurora-db ni tan sols va imprimir res (va retornar codi 2, "no trobat"). Guarda't aquesta dada: és la meitat de la resposta al cas B.

Una imatge ben optimitzada no porta curl, ni ping, ni netstat, ni dig. I les imatges distroless o construïdes FROM scratch no porten ni tan sols un shell. Això és excel·lent per a la seguretat i la mida (lliçó 05-04) i desesperant quan alguna cosa falla.

La solució moderna: un contenidor efímer carregat d'eines que comparteix els namespaces del contenidor malalt.

El que fa cada opció:

I ara, des de dins d'aquest contenidor, diagnostiques la xarxa d'api-depurar com si hi fossis:

Quatre conclusions en quatre comandes, sense instal·lar res a la imatge de producció:

1. ss -tlnp confirma que l'API sí que escolta al 3000, a 0.0.0.0 (bé: no a 127.0.0.1, que seria inabastable des de fora).
2. ps -ef mostra el node server.js del contenidor veí gràcies a --pid container:, i a més que corre amb UID 1000.
3. nslookup aurora-db respon NXDOMAIN: el servidor DNS intern de Docker (127.0.0.11) existeix i respon, però no coneix aquest nom.
4. curl funciona encara que la imatge de l'API no tingui curl, perquè l'aporta netshoot.

Aquest NXDOMAIN és la prova definitiva. Hi tornarem al cas B.

Docker Desktop inclou una versió integrada d'aquesta idea:

Obre un shell amb un conjunt d'eines muntat sobre el contenidor sense modificar-lo: funciona fins i tot en imatges distroless sense shell, i en sortir no en queda ni rastre. Requereix una subscripció Pro o superior; el truc de netshoot és gratuït, funciona a qualsevol Docker i convé conèixer-lo igualment.

docker inspect retorna tot el que Docker sap d'un contenidor: unes 200 línies de JSON.

Els sis blocs que importen:

Llegir 200 línies de JSON no és depurar. El que es fa és extreure la dada concreta, amb --format o amb jq:

Un exemple complet sobre la flota:

Dues observacions que seran decisives d'aquí a cinc minuts: tots dos són a la xarxa bridge i cadascun té la seva pròpia IP.

Amb jq pots fer consultes més riques sobre el JSON cru:

Nota de seguretat, i és seriosa: docker inspect mostra les contrasenyes en clar. Qualsevol amb accés al dimoni de Docker pot llegir totes les variables d'entorn de tots els contenidors. Per això les variables d'entorn no són un mecanisme de secrets; ho són els gestors de secrets, que es veuen a la lliçó 05-03.

Dues particularitats que el fan especial:

• Els PID són els del host, no els de dins del contenidor. docker exec aurora-db ps mostraria el mateix postgres com a PID 1; aquí és el 24817. És la doble numeració dels namespaces de PID.
• No necessita que la imatge tingui ps. La comanda l'executa el dimoni al host. Per això funciona fins i tot en imatges distroless.

Serveix per respondre ràpid a: quants processos hi ha?, hi ha processos zombis?, l'aplicació està llançant fills que no hauria?

Sense --no-stream, la vista es refresca contínuament com un top. Columna a columna:

Aquest LIMIT de 7,628 GiB a les dues files és el senyal d'alarma que resoldràs a la lliçó 03-07: cap dels dos contenidors no té límit de memòria, així que qualsevol d'ells pot consumir tota la RAM de la màquina.

Formats útils:

docker events és el registre de tot el que fa el dimoni. Sense --since, es queda escoltant en directe. És l'eina que respon a preguntes que cap altra no pot:

Els esdeveniments més útils: create, start, die (amb el seu exitCode), kill, oom, health_status, restart, destroy, i els de xarxa connect/disconnect. Un oom en aquesta llista és la confirmació que va ser el nucli i no pas tu (lliçó 03-07).

Símptoma: un company et diu que l'API "no arrenca a la seva màquina". Apliques el mètode.

Pregunta 1: està corrent?

Codi 1: de la taula de la lliçó 03-02, això significa que l'aplicació va arrencar i va fallar ella mateixa. No és Docker (seria 125), ni un executable inexistent (127), ni un senyal (>128). Així que cal anar als registres.

Pregunta 2: què diuen els registres?

Resolt en dues comandes i quinze segons. El fitxer es diu server.js, no serve.js. D'on surt aquest nom?

Pregunta 3: com està configurat?

Aquí ho tens: el CMD de la imatge (["server.js"]) va ser sobreescrit des de la línia de comandes per l'argument solt serve.js, tal com vas aprendre a la lliçó 03-01. La imatge és perfecta; l'error era al docker run.

Una variant del mateix símptoma que convé reconèixer, perquè el diagnòstic és completament diferent:

La comanda docker ps -a no retorna res: el contenidor no es va arribar ni a crear. Amb un 125 no hi ha registres per mirar ni contenidor per inspeccionar; l'error és a la teva línia de comandes. És la primera bifurcació de l'arbre de decisió i estalvia molt de temps perdut.

Aquí hi ha el cas que arrossegues des del mòdul 2. El resoldrem amb el mètode complet.

Pregunta 1: està corrent?

Tots tres estan corrent. No és un problema d'arrencada.

Pregunta 2: què diuen els registres?

El missatge és clar: getaddrinfo és la funció de resolució de noms, i ENOTFOUND significa que el nom aurora-db no s'ha pogut traduir a cap adreça IP. No és un rebuig de connexió: és que l'API no sap on connectar-se.

Pregunta 3: com està configurat?

I aquí arriba la sorpresa que fa interessant el cas: tots tres són a la mateixa xarxa, la bridge per defecte, amb IPs del mateix rang 172.17.0.0/16. No és un problema d'aïllament.

Verifica les variables, per descartar:

Correctes. La configuració és la que volies.

Pregunta 4: què passa a dins?

El DNS intern de Docker (127.0.0.11) està configurat, però no resol aurora-db. Confirma-ho amb eines de debò, fent servir el truc de l'apartat 5:

Aquest és el diagnòstic definitiu, i són dos fets oposats a la mateixa sortida:

O sigui: aurora-api pot parlar amb aurora-db; simplement no sap com es diu. El problema mai no va ser de tallafocs, ni de ports, ni de PostgreSQL: és de resolució de noms.

I la causa és una característica molt concreta de Docker: la xarxa bridge per defecte no té DNS intern entre contenidors. Només les xarxes definides per l'usuari el tenen. Ningú no t'ho havia dit fins ara perquè és exactament el tema de la lliçó vinent.

I no podries posar la IP directament i acabar abans?

Podries, i seria un error. Aquestes IPs les assigna Docker en l'ordre d'arrencada: reinicia la màquina, canvia l'ordre dels contenidors i 172.17.0.2 serà un altre. Escriure IPs a mà és construir un castell sobre sorra. La solució correcta —una xarxa pròpia on els noms funcionin— és la primera pràctica de la lliçó 03-05, i ara ja saps exactament per què la necessites.

La incògnita del mòdul queda tancada. Només falta aplicar la solució.

Símptoma: docker ps mostra Up 40 seconds (unhealthy) a aurora-api. Què significa exactament i d'on surt aquest veredicte?

L'històric complet és a .State.Health.Log, un array amb els últims cinc intents:

Llegeix-ho amb calma, perquè explica tota la història:

Aquest 503 no és casual: el vas escriure tu a la lliçó 01-07. L'endpoint /salut retorna 200 només si la base de dades i la memòria cau responen, i 503 en qualsevol altre cas:

I ara el matís que separa un unhealthy real d'un fals positiu:

El contenidor està sa; el servei no. El procés node viu, escolta al 3000 i respon en 173 mil·lisegons. El que està trencat són les seves dependències. El HEALTHCHECK està fent exactament el que li vas demanar: informar que aquest contenidor no està en condicions d'atendre trànsit.

Els quatre estats de salut possibles:

I el detall que sorprèn tothom: unhealthy no fa res per si sol. Docker Engine no reinicia el contenidor, no el treu de rotació ni avisa ningú; es limita a marcar-lo i a emetre un esdeveniment health_status. Qui actua sobre aquesta informació és un orquestrador (Swarm a la lliçó 06-03, Kubernetes a la 06-05) o tu, mirant docker ps. Ni tan sols la política --restart reacciona a un unhealthy, i aquest matís s'explica a la lliçó 03-07.

Deixa aurora-api tal com està: a la lliçó vinent es posarà healthy tot sol.

• Començar per entrar al contenidor. El 70 % de les avaries es veuen a docker logs en deu segons. Segueix l'ordre: estat → registres → configuració → dins.
• Depurar amb --rm. Si el contenidor s'esborra en morir, no hi ha registres, ni inspect, ni autòpsia. Durant la investigació, sense --rm.
• Buscar registres d'una aplicació que escriu en un fitxer. docker logs buit no significa "no passa res": comprova on escriu realment el procés.
• Instal·lar eines al contenidor "per arreglar-lo". Es perden en recrear-lo. Per diagnosticar, un contenidor efímer amb netshoot; per arreglar, el Dockerfile.
• Confondre ECONNREFUSED amb ENOTFOUND. El primer diu "el nom s'ha resolt però ningú no escolta allà"; el segon, "no sé qui és aquest". Són dues avaries diferents i porten a llocs diferents.
• Llegir docker stats sense límits configurats. La columna LIMIT mostra tota la RAM del host i el MEM % resulta enganyosament tranquil·litzador.
• Creure que unhealthy reinicia alguna cosa. Docker Engine només el marca. Sense orquestrador, ningú no actua.
• Bolcar docker inspect sencer al terminal. Són 200 línies de JSON. Fes servir --format o jq i vés directe a la dada.
• Consell: desa àlies per a les consultes d'inspect que repeteixis. Per exemple dip() { docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}' "$1"; }.
• Consell: docker events en un segon terminal mentre reprodueixes la fallada. Veure el die amb el seu exitCode a l'instant exacte val més que deu conjectures.

Llança aquest contenidor, que fallarà a propòsit, i fes la investigació completa sense tornar-lo a executar:

Respon amb comandes concretes: en quin estat està i amb quin codi va sortir?, aquest codi apunta a Docker o a l'aplicació?, què va escriure a stdout i què a stderr, per separat?, quines variables d'entorn tenia configurades?, quina era la seva comanda efectiva?, quant de temps va estar viu (calcula-ho amb StartedAt i FinishedAt)?

Arrenca un contenidor web-mut amb nginx:alpine sense publicar cap port. Després, sense instal·lar-hi res a dins i sense recrear-lo:

1. Esbrina la seva adreça IP.
2. Comprova des d'un contenidor efímer de netshoot que Nginx respon al seu port 80.
3. Demostra que des del host, amb curl localhost:80, no respon, i explica per què això no contradiu el punt anterior.
4. Esbrina quins processos corren a dins sense fer servir docker exec.

Crea una imatge aurora-api:fals-sa a partir d'auroralibros/aurora-api:1.2.0 que substitueixi el HEALTHCHECK per un que comprovi simplement que el procés existeix (CMD pgrep node || exit 1). Arrenca-la sense base de dades ni memòria cau i compara, amb comandes, l'estat de salut que reporta enfront del d'auroralibros/aurora-api:1.2.0 en les mateixes condicions. Després respon: quin dels dos healthchecks és "millor"?, en quina situació concreta el segon t'hauria evitat un incident i en quina t'hauria donat una falsa alarma?

Solució a l'exercici 1

El codi 78 està al rang 1–124, així que és de l'aplicació, no de Docker. Un 125 hauria significat un error del mateix docker run, un 127 un executable inexistent i un 137 un senyal. Aquí, el programa va decidir sortir amb aquest número, així que l'explicació és al seu codi i als seus registres.

La separació de fluxos és el que dona el diagnòstic: a stdout hi ha soroll informatiu i a stderr hi ha la causa real. En un registre entremesclat de 500 línies, aquest filtre és la diferència entre trobar-ho i no trobar-ho.

Confirmat: MODE estava definida i API_KEY no apareix enlloc, que és just el que denunciava el stderr.

Va viure 2,17 segons, coherents amb el sleep 2 de la comanda. Aquest càlcul és més útil del que sembla: un contenidor que viu mil·lisegons sol fallar en arrencar; un que viu hores i després mor apunta a una fuita de memòria o a un esdeveniment extern.

Solució a l'exercici 2

2. Comprovar que respon, des de netshoot:

Nginx funciona perfectament. Una altra manera, compartint directament la seva pila de xarxa:

3. Des del host:

No hi ha cap contradicció: el contenidor escolta al port 80 de la seva pròpia pila de xarxa, però com que no es va publicar cap port amb -p, no existeix cap regla que reenviï el port 80 del host cap a ell. La connectivitat existeix dins de la xarxa de Docker (on viu netshoot) i no existeix des del host. És just la distinció entre "publicar un port" i "que dos contenidors es parlin" que es formalitza a la lliçó 03-05.

4. Processos sense docker exec:

docker top l'executa el dimoni al host, així que no necessita entrar al contenidor ni que la imatge tingui ps. I de propina es veu la bona pràctica de Nginx: el master corre com a root i els workers com l'usuari 101.

Solució a l'exercici 3

Dos contenidors idèntics en tot llevat de la seva comprovació de salut, i veredictes oposats. El de l'esquerra diu estar sa; cap dels dos no pot servir ni un sol llibre.

El healthcheck fals respon 0 perquè pgrep node troba el procés. I té tota la raó: el procés està viu. Simplement està mesurant el que no importa.

Les respostes:

• El d'auroralibros/aurora-api:1.2.0 és millor en aquest escenari, perquè comprova la capacitat real de donar servei (una petició HTTP d'extrem a extrem, que al seu torn consulta la base de dades i la memòria cau) en comptes de la mera existència d'un procés.
• Quan t'hauria salvat el segon (pgrep): quan la caiguda és d'una dependència i no vols que totes les teves rèpliques es declarin malaltes alhora. Si PostgreSQL cau 30 segons, amb el healthcheck estricte les deu rèpliques de l'API passen a unhealthy simultàniament, l'orquestrador les treu de rotació i et quedes amb un tall total en comptes d'un servei degradat que encara serveix el que hi ha a la memòria cau. És el conegut efecte dòmino dels healthchecks massa profunds.
• Quan t'hauria donat una falsa alarma... o pitjor, cap: quan el procés de Node està viu però el seu bucle d'esdeveniments està bloquejat, el pool de connexions esgotat o responent 500 a tot. pgrep diria "sa" indefinidament mentre els usuaris veuen errors. Aquest escenari és literalment el que va motivar HEALTHCHECK a la lliçó 02-04.

La solució professional, que ja apuntaves a l'exercici 3 de la lliçó 02-04, és separar dos endpoints: un de vivacitat (/salut/viu, superficial, per decidir reinicis) i un altre de disponibilitat (/salut, profund, per decidir si rep trànsit). És la distinció entre liveness i readiness que es desenvolupa a la lliçó 06-05.

Tens un mètode, i això val més que la llista de comandes: està corrent? → què diuen els registres? → com està configurat? → què passa a dins?, en aquest ordre i sense saltar-se passos. Saps que un Created assenyala un executable inexistent, que un 125 significa que el contenidor ni es va crear i no hi ha res a inspeccionar, i que un codi entre 1 i 124 mena directament a docker logs.

Manegues docker logs amb les seves finestres de temps, el seu --tail i el seu -f que pots tallar amb Ctrl+C sense por, i tens gravada la regla d'or: els contenidors registren a stdout i stderr, mai en un fitxer, i saps separar els dos fluxos amb una redirecció perquè l'error aparegui sol. Entres amb docker exec triant el shell correcte segons la base, saps que -u root et dona privilegis encara que la imatge declari USER node, i —el més valuós— saps depurar imatges mínimes sense eines llançant un contenidor efímer de netshoot que comparteix els namespaces de xarxa i de processos del malalt, sense embrutar la imatge de producció.

Del JSON de docker inspect n'extreus la dada exacta amb plantilles Go i jq, amb una taula de consultes per a IP, xarxes, ports, muntatges, entorn, salut, codi de sortida i reinicis, i saps que aquesta mateixa comanda mostra les contrasenyes en clar, raó per la qual les variables d'entorn no són un mecanisme de secrets. Amb docker top veus els processos des del host encara que la imatge no tingui ps, amb docker stats interpretes les set columnes —i has descobert que els teus contenidors no tenen cap límit de memòria— i amb docker events reconstrueixes què va passar i quan.

I has tancat la investigació que arrossegaves des del mòdul 2. aurora-api, aurora-db i aurora-cache són a la mateixa xarxa i amb connectivitat plena entre ells: nc -zv 172.17.0.2 5432 respon succeeded. El que falla és una sola cosa, i ara la saps anomenar amb precisió: nslookup aurora-db retorna NXDOMAIN, perquè la xarxa bridge per defecte no té DNS intern entre contenidors. No és un tallafocs, ni un port, ni PostgreSQL: és que l'API no sap com es diu la seva base de dades.

Només falta aplicar la solució, i és més curta que el diagnòstic. A la lliçó següent, Xarxes a Docker, veuràs per què cada contenidor té la seva pròpia pila de xarxa i el seu propi localhost, compararàs els drivers bridge, host i none, i entendràs la diferència decisiva entre la bridge per defecte i una xarxa definida per l'usuari, on el DNS intern resol noms de contenidor automàticament. Crearàs aurora-net, recrearàs els tres serveis dins seu, i executaràs per fi aquell curl http://localhost:3000/llibres que fa sis lliçons que espera per retornar-te El jardín de senderos que se bifurcan, Rayuela i els altres sis títols. Després afegiràs aurora-web com a proxy invers, i la plataforma d'Aurora Libros estarà viva de debò.