Jurnalele de build și runtime: depanarea deploymenturilor Dockup

Jurnalele de build și runtime răspund la întrebări diferite. Jurnalele de build explică modul în care codul sursă a fost transformat într-o imagine și de ce a eșuat procesul. Jurnalele de runtime explică ce a făcut aplicația după pornirea containerului sau a workloadului Kubernetes.

Citirea fluxului greșit duce la pierdere de timp. O dependență lipsă în timpul construirii imaginii nu va apărea niciodată în jurnalele de runtime, în timp ce o imagine creată cu succes, dar care se închide la pornire, poate avea un output de build perfect curat.

Care este diferența dintre jurnalele de build și cele de runtime?

Folosește etapa deploymentului pentru a alege fluxul potrivit:

Etapă	Status obișnuit	Jurnalul corect	Eșecuri frecvente
Clonare	cloning	Build	Acces la repository, branch
Instalarea dependențelor	building	Build	Lockfile, registry, package
Compilare/bundle	building	Build	Erori de tipuri, memorie, fișiere lipsă
Pornirea imaginii	deploying	Runtime și health	Comanda de pornire, port, permisiuni
Serviciu în execuție	running	Runtime	Excepții, indisponibilitatea dependențelor
Verificarea readiness	deploying	Runtime și configurația health	Path incorect, pornire lentă

Citește cel mai recent output de build:

dockup logs production/api --build --json

Citește outputul de runtime al serviciului în execuție:

dockup logs production/api --json

Solicită mai multe linii de runtime atunci când evenimentul relevant este mai vechi:

dockup logs production/api -n 500 --json

Răspunsul JSON identifică ținta și tipul jurnalului, ceea ce ajută un agent să evite combinarea unor fluxuri fără legătură.

Cum funcționează dockup logs --build --follow?

Modul follow transmite liniile noi prin interogarea periodică a snapshotului curent:

dockup logs production/api --build -f --json

În modul JSON, outputul este NDJSON: câte un obiect pe linie și pe batch. Un consumator poate procesa incremental fiecare linie.

Un batch final marchează rezultatul terminal al buildului. Comanda se oprește automat când deploymentul reușește sau eșuează și returnează un cod de ieșire diferit de zero în caz de eșec. Astfel, poate fi folosită de un agent sau de un job CI fără o buclă de status scrisă manual.

Follow pentru runtime funcționează în mod similar:

dockup logs production/api -f --json

Fiecare batch include restarted. Când restarted:true, containerul a fost repornit sau bufferul păstrat a fost rotit, iar Dockup retransmite întregul snapshot curent în loc să elimine liniile în tăcere.

Intervalul implicit de polling este de 2 secunde. Folosește --interval documentat doar atunci când există un motiv concret pentru schimbarea frecvenței.

Cum diagnostichezi un build eșuat?

Începe cu rezultatul terminal al deploymentului:

dockup deploy production/api --wait --json

Când comanda se încheie cu deploy_failed, preia jurnalul de build și caută prima eroare cauzală, nu ultimul mesaj din cascadă.

O secvență utilă este:

1. Confirmă ținta și ID-ul deploymentului.
2. Identifică etapa de clonare, instalare, compilare sau construire a imaginii.
3. Găsește prima eroare care nu poate fi rezolvată prin retry.
4. Compară metoda de build cu intenția repository-ului.
5. Reproduce problema folosind un clone curat, dacă este posibil.
6. Fă o singură modificare bine delimitată.
7. Rulează din nou deploymentul cu --wait.

Eșecurile frecvente în Nixpacks includ un root de proiect nerecunoscut, un lockfile lipsă, absența unui script convențional de pornire sau necesitatea unui package nativ. Eșecurile frecvente în Dockerfile includ un build context incorect, un artifact care nu a fost copiat, o imagine de bază indisponibilă sau o instrucțiune RUN care eșuează.

Ghidul Nixpacks vs Dockerfile oferă o hartă decizională pentru sistemul de build.

Nu încerca să repari o eroare de build deterministă mărind timeoutul de 900 de secunde. Modificarea timeoutului ajută la un build legitim, dar lung; nu repară o comandă care s-a încheiat cu o eroare.

Cum diagnostichezi un crash de runtime sau un eșec de health check?

O imagine creată cu succes poate eșua totuși înainte de comutarea traficului. Inspectează starea serviciului și outputul de runtime:

dockup status production/api --json
dockup logs production/api --json
dockup health production/api --json

Caută:

• Procesul se închide imediat după pornire.
• Aplicația se leagă la portul greșit.
• Aplicația ascultă pe 127.0.0.1 în loc să asculte pe toate interfețele.
• Lipsește o cheie de mediu necesară.
• Conexiunea la baza de date sau la Redis eșuează.
• Permisiunile pentru fișiere blochează pornirea.
• Path-ul de health returnează un status care indică eșecul.
• Pornirea durează mai mult decât permit retry-urile configurate.
• O migrare eșuează sau rulează concurent.

Configurația health poate fi inspectată sau actualizată:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

Nu slăbi verificarea health doar pentru a face un release defect să treacă. Dacă pornirea are nevoie în mod legitim de mai mult timp, modifică politica pe baza unor dovezi și păstrează un endpoint care confirmă în continuare readiness-ul.

Modificările de mediu necesită un nou deployment. Dacă repari un secret lipsă, rulează din nou deploymentul și așteaptă finalizarea; repornirea containerului vechi nu aplică noul mediu dorit.

Cum ar trebui agenții să parseze NDJSON fără să piardă codul de ieșire?

Un agent sau un script ar trebui să citească fiecare linie JSON, păstrând în același timp statusul procesului. Evită redirecționarea către o comandă care maschează codul de ieșire original fără pipefail.

set -o pipefail
dockup logs production/api --build -f --json \
  | tee build-stream.ndjson

Cu pipefail, o comandă Dockup eșuată menține pipeline-ul în starea non-zero, chiar dacă tee s-a încheiat cu succes.

Un consumator poate inspecta fiecare obiect independent:

while IFS= read -r line; do
  printf '%s\n' "$line" | jq -r '.lines[]?'
done < build-stream.ndjson

Păstrează artifactul NDJSON brut. Un extras ușor de citit este util pentru un pull request sau un incident, dar câmpurile originale păstrează markerii de restart, statusul și semnalele de finalizare.

Principiile generale pentru interfețe destinate mașinilor sunt explicate în designul CLI pentru agenți AI.

Care este un runbook repetabil pentru depanarea deploymenturilor?

Folosește această cale decizională:

dockup status production/api --json
dockup deployments production/api -n 5 --json
dockup logs production/api --build --json
dockup logs production/api --json

Apoi clasifică incidentul:

Clasificare	Dovezi	Acțiunea următoare
Sursă/build	Eroare în jurnalul de build	Repară repository-ul sau definiția buildului
Configurație	Variabilă de mediu sau port lipsă/greșit	Corectează configurația și rulează din nou deploymentul
Readiness	Aplicația rulează, dar health eșuează	Repară endpointul sau ajustează justificat temporizarea
Dependență de runtime	Excepție de conexiune	Verifică baza de date/rețeaua/credentialele
Regresie	Versiunea anterioară funcționa	Ia în calcul rollbackul la un ID cunoscut
Incertitudine de platformă	Timeout, fără stare terminală	Inspectează statusul înainte de retry

Revino la o versiune anterioară doar după identificarea unui deployment anterior cunoscut:

dockup rollback <deploymentId> production/api --json

Păstrează mai întâi ID-ul deploymentului eșuat și jurnalele. Un rollback restabilește disponibilitatea serviciului; nu explică însă cauza principală.

Articolul despre deploymenturi cu zero downtime explică de ce o verificare readiness eșuată poate proteja traficul activ.

Cum pot fi făcute utile jurnalele de producție?

Dockup poate prelua outputul, dar aplicația controlează calitatea jurnalelor. Preferă înregistrări structurate, cu un singur eveniment, care includ timestampuri, severitate, ID-uri de request sau trace, numele componentei și o descriere sigură a erorii.

Nu înregistra niciodată tokenuri de acces, URL-uri de baze de date, parole, headere complete de autorizare sau date personale care nu sunt necesare pentru operațiuni. Mascarea secretelor din configurația Dockup nu redacționează outputul arbitrar al aplicației.

Înregistrează informații despre pornire care sunt sigure și utile pentru diagnosticare:

• Versiunea aplicației sau commitul.
• Numele mediului.
• Portul pe care ascultă aplicația.
• Numele feature-urilor activate, fără valorile secretelor.
• Categoria hostului bazei de date, nu parola.
• Versiunea migrației.
• Readiness-ul endpointului de health.

Șablon pentru cronologia incidentului

Înregistrează:

1. ID-ul deploymentului și commitul sursă.
2. Timestampurile de început și de final ale deploymentului.
3. Prima eroare cauzală de build sau runtime.
4. Rezultatul verificării health.
5. Comanda de recuperare și ID-ul deploymentului.
6. Intervalul de impact asupra utilizatorilor.
7. Persoana responsabilă de acțiunile ulterioare.

Datele de uptime adaugă disponibilitatea și timpul de răspuns la nivel de minut:

dockup uptime production/api --hours 24 --json

Rezultatul include timpul mediu de răspuns și timpul de răspuns p95. Combină-l cu jurnalele de build și runtime pentru a distinge un incident de deployment de o regresie de performanță mai îndelungată.

Folosește referința CLI Dockup pentru flagurile actuale ale jurnalelor și cele mai bune practici de securitate pentru logging sigur al aplicației.

Corelează jurnalele cu istoricul deploymenturilor

O linie este utilă doar atunci când poate fi asociată cu release-ul corect. Salvează ID-ul deploymentului, hash-ul commitului și ora de pornire alături de artifactul jurnalului. Când două release-uri au loc la interval scurt, numai timestampurile pot induce în eroare.

dockup deployments production/api -n 20 --json

Istoricul deploymenturilor stabilește ce sursă era activă și ce release a ajuns într-o stare terminală. Un agent nu ar trebui să atribuie o excepție de runtime celui mai recent commit până când starea serviciului nu confirmă că acel commit a fost implementat efectiv.

Evită expunerea secretelor prin jurnale

O conexiune eșuată îi poate tenta pe dezvoltatori să afișeze URL-ul complet. În schimb, înregistrează protocolul, hostul mascat, numele bazei de date și categoria erorii. Pentru tokenuri, înregistrează doar o amprentă sigură generată înainte de stocare, atunci când organizația are o politică în acest sens.

Verifică artifactele buildurilor eșuate înainte de a le distribui în afara echipei. Outputul package managerului și al Docker poate conține URL-uri către repository-uri private, nume de utilizatori pentru registry sau argumente de comandă, chiar și atunci când Dockup maschează corect secretele stocate în variabilele de mediu.

Astfel, jurnalele de build și runtime devin suficient de sigure pentru diagnosticare în colaborare.

Păstrează un pachet minim de dovezi

Pentru fiecare release eșuat, salvează JSON-ul rezultatului deploymentului, jurnalul de build, extrasul relevant de runtime, statusul serviciului și ID-ul deploymentului de recuperare selectat. Acest pachet este suficient de mic pentru utilizarea de rutină și suficient de complet pentru ca un al doilea operator să continue fără să repete mutații incerte.

Confirmă remedierea, nu doar noul build

După ce deploymentul corectat reușește, repetă requestul eșuat sau condiția de pornire și urmărește outputul de runtime pentru a verifica dacă problema reapare. Închide incidentul doar atunci când simptomul inițial a dispărut, verificarea health trece și comportamentul așteptat în producție este observat.

Încheie ciclul

Documentează remedierea verificată.

Începe cu un deployment verificabil

Forțează eșecul unui build de test, capturează fluxul NDJSON și codul de ieșire, apoi verifică dacă runbookul tău selectează jurnalul de build în locul jurnalului de runtime.

Începe gratuit pe app.dockup.ai. Planul Free costă 0 USD pe lună, include un credit inițial de 10 USD și oferă suport pentru un workspace, trei baze de date și trei deploymenturi.

Întrebări frecvente

Care este diferența dintre jurnalele de build și cele de runtime din Dockup?

Jurnalele de build acoperă clonarea, instalarea dependențelor, compilarea și crearea imaginii. Jurnalele de runtime acoperă containerul aplicației sau podurile pornite.

Cum urmăresc live jurnalele de build din Dockup?

Folosește dockup logs cu --build și --follow sau -f. Cu --json, comanda emite batchuri NDJSON și se încheie la starea terminală a deploymentului.

De ce se încheie build follow cu un cod diferit de zero?

Păstrează rezultatul deploymentului. Un build eșuat trebuie să eșueze în shellul apelant, în jobul CI sau în taskul agentului, în loc să pară un flux de jurnale reușit.

Ce înseamnă restarted:true în outputul runtime follow?

Indică faptul că containerul a fost repornit sau că bufferul păstrat a fost rotit, astfel încât Dockup a emis din nou snapshotul curent în loc să piardă liniile în tăcere.

Ar trebui ca jurnalele aplicației să conțină secrete din mediu?

Nu. Dockup maschează citirile configurației stocate, dar nu poate face sigure secretele arbitrare afișate de aplicație. Redactează credentialele la nivelul loggingului aplicației.