Build a runtime logy: ladenie nasadení v Dockup

Build a runtime logy odpovedajú na odlišné otázky. Build logy vysvetľujú, ako sa zo zdrojového kódu stal image a prečo tento proces zlyhal. Runtime logy vysvetľujú, čo vytvorená aplikácia robila po spustení kontajnera alebo workloadu v Kubernetes.

Čítanie nesprávneho streamu zbytočne predlžuje diagnostiku. Chýbajúca dependency počas vytvárania image sa v runtime logoch nikdy neobjaví, zatiaľ čo image, ktorý sa úspešne vytvoril, ale pri štarte spadne, môže mať úplne čistý build output.

Aký je rozdiel medzi build a runtime logmi?

Stream vyberte podľa fázy nasadenia:

Fáza	Typický stav	Správny log	Bežné zlyhania
Klonovanie	cloning	Build	Prístup k repozitáru, branch
Inštalácia dependencies	building	Build	Lockfile, registry, package
Kompilácia/bundle	building	Build	Type errors, nedostatok pamäte, chýbajúce súbory
Spustenie image	deploying	Runtime a health	Start command, port, oprávnenia
Bežiaca služba	running	Runtime	Exceptions, výpadky dependencies
Readiness gate	deploying	Runtime a health config	Nesprávna cesta, pomalý štart

Prečítajte si najnovší build output:

dockup logs production/api --build --json

Prečítajte si runtime output z bežiacej služby:

dockup logs production/api --json

Ak je relevantná udalosť staršia, vyžiadajte si viac runtime riadkov:

dockup logs production/api -n 500 --json

JSON odpoveď identifikuje cieľ a typ logu, čo agentovi pomáha vyhnúť sa spájaniu nesúvisiacich streamov.

Ako funguje dockup logs --build --follow?

Režim follow streamuje nové riadky pomocou polling-u aktuálneho snapshotu:

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

V režime JSON je výstup vo formáte NDJSON: jeden objekt na riadok a batch. Consumer môže každý riadok spracovať inkrementálne.

Posledný batch označuje finálny výsledok buildu. Príkaz sa po úspechu alebo zlyhaní nasadenia zastaví sám a pri zlyhaní skončí s nenulovým exit kódom. Vďaka tomu je vhodný pre agenta alebo CI job bez ručne napísanej status slučky.

Runtime follow funguje podobne:

dockup logs production/api -f --json

Každý batch obsahuje restarted. Keď je hodnota restarted:true, kontajner sa reštartoval alebo sa pretočil uchovávaný log buffer, takže Dockup znova odošle celý aktuálny snapshot namiesto tichého vynechania riadkov.

Predvolený interval polling-u je 2 sekundy. Zdokumentovaný parameter --interval použite iba vtedy, keď existuje konkrétny dôvod zmeniť frekvenciu.

Ako diagnostikovať neúspešný build?

Začnite finálnym výsledkom nasadenia:

dockup deploy production/api --wait --json

Ak príkaz skončí so stavom deploy_failed, načítajte build log a nájdite prvú príčinnú chybu, nie poslednú správu z kaskády.

Užitočný postup:

1. Potvrďte cieľ a ID nasadenia.
2. Identifikujte fázu klonovania, inštalácie, kompilácie alebo image.
3. Nájdite prvú chybu, pri ktorej nejde o retry.
4. Porovnajte metódu buildu so zámerom repozitára.
5. Ak je to možné, zopakujte problém z čistého klonu.
6. Urobte jednu cielenú zmenu.
7. Znova nasaďte s parametrom --wait.

Bežné zlyhania Nixpacks zahŕňajú nerozpoznaný root projektu, chýbajúci lockfile, chýbajúci konvenčný start script alebo požiadavku na native package. Bežné zlyhania Dockerfile zahŕňajú nesprávny build context, chýbajúci skopírovaný artefakt, nedostupný base image alebo zlyhávajúcu inštrukciu RUN.

Sprievodca Nixpacks vs Dockerfile poskytuje rozhodovaciu mapu pre build systémy.

Deterministickú chybu buildu sa nesnažte opraviť predĺžením timeoutu z 900 sekúnd. Zmena timeoutu pomôže pri legitímne dlhom builde, ale neopraví príkaz, ktorý skončil chybou.

Ako diagnostikovať runtime crash alebo zlyhanie health checku?

Úspešný image môže zlyhať ešte pred prepnutím trafficu. Skontrolujte stav služby a runtime output:

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

Hľadajte:

• Proces sa ihneď po štarte ukončí.
• Aplikácia sa binduje na nesprávny port.
• Aplikácia počúva na 127.0.0.1 namiesto všetkých rozhraní.
• Chýba požadovaný environment key.
• Pripojenie k databáze alebo Redis zlyhá.
• Oprávnenia k súborom blokujú štart.
• Health path vracia neúspešný status.
• Štart trvá dlhšie, než povoľuje nakonfigurovaný počet retry pokusov.
• Migrácia zlyhá alebo sa spustí súbežne.

Health konfiguráciu môžete skontrolovať alebo aktualizovať:

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

Health gate neoslabujte iba preto, aby prešiel nefunkčný release. Ak štart legitímne potrebuje viac času, upravte policy na základe dôkazov a ponechajte endpoint, ktorý naďalej overuje readiness.

Zmeny environmentu vyžadujú nové nasadenie. Ak opravíte chýbajúci secret, nasaďte znova a počkajte; reštart starého kontajnera novú požadovanú konfiguráciu environmentu nepoužije.

Ako majú agenti parsovať NDJSON bez straty exit kódu?

Agent alebo script by mal čítať každý JSON riadok a zároveň zachovať process status. Vyhnite sa pipe do príkazu, ktorý bez pipefail prekryje pôvodný exit kód.

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

S pipefail zostane pipeline nenulová, ak príkaz Dockup zlyhá, aj keď tee úspešne dokončí svoju činnosť.

Consumer môže každý objekt kontrolovať samostatne:

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

Pôvodný NDJSON artefakt si ponechajte. Čitateľný výňatok je užitočný v pull requeste alebo pri incidente, no pôvodné polia zachovávajú indikátory reštartu, status a signály dokončenia.

Všeobecné princípy machine interface vysvetľuje článok AI agent CLI design.

Čo obsahuje opakovateľný runbook na ladenie nasadenia?

Použite túto rozhodovaciu cestu:

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

Incident potom klasifikujte:

Klasifikácia	Dôkaz	Ďalšia akcia
Zdrojový kód/build	Chyba v build logu	Opravte repozitár alebo definíciu buildu
Konfigurácia	Chýbajúci/nesprávny env alebo port	Opravte konfiguráciu a nasaďte znova
Readiness	Aplikácia beží, health zlyháva	Opravte endpoint alebo odôvodnené časovanie
Runtime dependency	Connection exception	Skontrolujte databázu/sieť/credentials
Regression	Predchádzajúca verzia fungovala	Zvážte rollback na známe ID
Neistota na platforme	Timeout, chýbajúci finálny stav	Pred opakovaním skontrolujte status

Rollback vykonajte až po identifikácii známeho predchádzajúceho nasadenia:

dockup rollback <deploymentId> production/api --json

Najskôr uchovajte ID neúspešného nasadenia a logy. Rollback obnoví dostupnosť služby, ale nevysvetlí root cause.

Článok zero-downtime deployments vysvetľuje, prečo môže neúspešný readiness gate chrániť live traffic.

Ako zabezpečiť užitočnosť produkčných logov?

Dockup dokáže načítať output, no kvalitu logov riadi aplikácia. Uprednostnite štruktúrované záznamy jednej udalosti s timestampom, severity, request alebo trace ID, názvom komponentu a bezpečným popisom chyby.

Nikdy nelogujte access tokeny, URL databáz, heslá, celé authorization headers ani osobné údaje, ktoré nie sú potrebné na prevádzku. Maskovanie secretov v konfigurácii Dockupu nerediguje ľubovoľný output aplikácie.

Logujte bezpečné a diagnosticky užitočné fakty o štarte:

• Verziu aplikácie alebo commit.
• Názov environmentu.
• Port, na ktorom aplikácia počúva.
• Názvy zapnutých features bez hodnôt secretov.
• Triedu hosta databázy, nie heslo.
• Verziu migrácie.
• Readiness health endpointu.

Šablóna časovej osi incidentu

Zaznamenajte:

1. ID nasadenia a zdrojový commit.
2. Čas začiatku nasadenia a finálny timestamp.
3. Prvú príčinnú build alebo runtime chybu.
4. Výsledok health gate.
5. Recovery príkaz a ID nasadenia.
6. Interval vplyvu na používateľov.
7. Zodpovednú osobu pre ďalšie kroky.

Údaje o uptime dopĺňajú dostupnosť a response time na úrovni minút:

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

Výsledok obsahuje priemerný response time a p95 response time. Skombinujte ho s build a runtime logmi, aby ste odlíšili incident pri nasadení od dlhodobej regresie výkonu.

Aktuálne flagy pre logy nájdete v Dockup CLI reference a bezpečné logovanie aplikácií v security best practices.

Korelujte logy s históriou nasadení

Riadok je užitočný iba vtedy, keď ho možno priradiť k správnemu releasu. Spolu s artefaktom logu ukladajte ID nasadenia, hash commitu a čas začiatku. Keď sa dva releasy uskutočnia krátko po sebe, samotné timestampy môžu zavádzať.

dockup deployments production/api -n 20 --json

História nasadení určuje, ktorý zdrojový kód bol aktívny a ktorý release dosiahol finálny stav. Agent by nemal pripísať runtime exception najnovšiemu commitu, kým stav služby nepotvrdí, že tento commit bol skutočne nasadený.

Zabráňte úniku secretov cez logy

Neúspešné pripojenie často zvádza vývojárov k vypísaniu celej URL. Namiesto toho logujte protokol, maskovaného hosta, názov databázy a kategóriu chyby. Pri tokenoch logujte iba bezpečný fingerprint vygenerovaný pred uložením, ak na to má organizácia stanovenú policy.

Pred zdieľaním artefaktov neúspešného buildu mimo tímu ich skontrolujte. Output package managera a Dockeru môže obsahovať URL súkromných repozitárov, používateľské mená v registry alebo argumenty príkazov, aj keď Dockup správne maskuje uložené environment secrets.

Vďaka tomu sú build a runtime logy dostatočne bezpečné na spoločnú diagnostiku.

Uchovajte minimálny balík dôkazov

Pri každom neúspešnom release uložte JSON s výsledkom nasadenia, build log, relevantný runtime výňatok, status služby a vybrané ID recovery nasadenia. Tento balík je dostatočne malý na bežné používanie a zároveň dostatočne úplný na to, aby druhý operátor mohol pokračovať bez opakovania neistých mutácií.

Overte opravu, nielen nový build

Po úspešnom nasadení opraveného buildu zopakujte neúspešnú požiadavku alebo podmienku pri štarte a sledujte runtime output, či sa problém nevracia. Incident uzavrite až vtedy, keď pôvodný symptóm chýba, health gate prejde a pozorujete očakávané správanie v produkcii.

Uzavrite spätnú väzbu

Zdokumentujte overenú opravu.

Začnite s overiteľným nasadením

Nechajte jeden testovací build zámerne zlyhať, zachyťte jeho NDJSON stream a exit kód a potom overte, že váš runbook vyberie build log namiesto runtime logu.

Začnite bezplatne na app.dockup.ai. Free plán stojí 0 $ mesačne, zahŕňa počiatočný kredit 10 $ a podporuje jeden workspace, tri databázy a tri nasadenia.

FAQ

Aký je rozdiel medzi build logmi a runtime logmi v Dockup?

Build logy pokrývajú klonovanie, inštaláciu dependencies, kompiláciu a vytváranie image. Runtime logy pokrývajú spustený aplikačný kontajner alebo pody.

Ako môžem sledovať build logy Dockupu naživo?

Použite dockup logs s parametrami --build a --follow alebo -f. S parametrom --json príkaz emituje NDJSON batche a skončí vo finálnom stave nasadenia.

Prečo build follow končí s nenulovým exit kódom?

Zachováva výsledok nasadenia. Neúspešný build musí zlyhať v shelli, CI jobe alebo úlohe agenta, namiesto toho, aby vyzeral ako úspešný stream logov.

Čo znamená restarted:true vo výstupe runtime follow?

Označuje, že sa kontajner reštartoval alebo sa pretočil uchovávaný buffer, takže Dockup znova odoslal aktuálny snapshot namiesto tichej straty riadkov.

Mali by aplikačné logy obsahovať environment secrets?

Nie. Dockup maskuje načítanie uloženej konfigurácie, ale nedokáže zabezpečiť ľubovoľné secrety, ktoré vypíše aplikácia. Credentials redigujte na vrstve aplikačného logovania.