Buildovací a runtime logy: ladění nasazení v Dockup

Buildovací a runtime logy odpovídají na různé otázky. Buildovací logy vysvětlují, jak se ze zdrojového kódu stal image a proč tento proces selhal. Runtime logy ukazují, co spuštěná aplikace dělala po startu kontejneru nebo workloadu v Kubernetes.

Čtení nesprávného streamu vede ke ztrátě času. Chybějící závislost při sestavování image se v runtime logu nikdy neobjeví, zatímco image, která se po úspěšném sestavení zhroutí při startu, může mít buildovací výstup zcela bez chyb.

Jaký je rozdíl mezi buildovacími a runtime logy?

Stream vyberte podle fáze nasazení:

Fáze	Typický stav	Správný log	Běžná selhání
Klonování	cloning	Build	Přístup k repozitáři, větev
Instalace závislostí	building	Build	Lockfile, registry, balíček
Kompilace/bundling	building	Build	Chyby typů, paměť, chybějící soubory
Spuštění image	deploying	Runtime a health	Spouštěcí příkaz, port, oprávnění
Běžící služba	running	Runtime	Výjimky, výpadky závislostí
Readiness gate	deploying	Runtime a health konfigurace	Nesprávná cesta, pomalý start

Načtěte nejnovější buildovací výstup:

dockup logs production/api --build --json

Načtěte runtime výstup běžící služby:

dockup logs production/api --json

Pokud je relevantní událost starší, vyžádejte více řádků runtime logu:

dockup logs production/api -n 500 --json

JSON odpověď identifikuje cíl a typ logu, což agentovi pomáhá neslučovat nesouvisející streamy.

Jak funguje dockup logs --build --follow?

Režim follow streamuje nové řádky pomocí dotazování aktuálního snapshotu:

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

V režimu JSON je výstup ve formátu NDJSON: jeden objekt na řádek a jednu dávku. Konzument může každý řádek zpracovávat průběžně.

Poslední dávka označuje konečný výsledek buildu. Příkaz se po úspěšném nebo neúspěšném dokončení nasazení sám zastaví a při selhání skončí s nenulovým návratovým kódem. Díky tomu je vhodný pro agenta nebo CI úlohu bez ručně napsané smyčky pro kontrolu stavu.

Sledování runtime logu funguje podobně:

dockup logs production/api -f --json

Každá dávka obsahuje hodnotu restarted. Pokud je restarted:true, kontejner se restartoval nebo došlo k rotaci uchovávaného logového bufferu, takže Dockup znovu odešle celý aktuální snapshot namísto tichého vynechání řádků.

Výchozí interval dotazování je 2 sekundy. Dokumentovaný parametr --interval použijte pouze tehdy, když potřebujete konkrétně změnit frekvenci.

Jak diagnostikovat neúspěšný build?

Začněte konečným výsledkem nasazení:

dockup deploy production/api --wait --json

Pokud příkaz skončí stavem deploy_failed, načtěte buildovací log a najděte první příčinnou chybu, nikoli poslední zprávu z řetězce následných chyb.

Užitečný postup:

1. Ověřte cíl a ID nasazení.
2. Určete fázi klonování, instalace, kompilace nebo image.
3. Najděte první chybu, která není určena k opakování.
4. Porovnejte metodu buildu se záměrem repozitáře.
5. Pokud je to možné, zopakujte postup z čistého klonu.
6. Proveďte jednu cílenou změnu.
7. Znovu nasaďte s parametrem --wait.

Mezi běžná selhání Nixpacks patří nerozpoznaný kořen projektu, chybějící lockfile, chybějící konvenční startovací skript nebo požadavek na nativní balíček. Mezi běžná selhání Dockerfile patří nesprávný build context, chybějící zkopírovaný artefakt, nedostupný base image nebo selhávající instrukce RUN.

Průvodce Nixpacks vs Dockerfile nabízí rozhodovací mapu pro výběr buildovacího systému.

Deterministickou chybu buildu se nesnažte opravit prodloužením timeoutu z 900 sekund. Změna timeoutu pomůže legitimně dlouhému buildu, ale neopraví příkaz, který skončil chybou.

Jak diagnostikovat pád runtime nebo selhání health checku?

Úspěšně sestavená image může stále selhat před přepnutím provozu. Zkontrolujte stav služby a runtime výstup:

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

Hledejte například:

• Proces skončí okamžitě po spuštění.
• Aplikace naslouchá na nesprávném portu.
• Aplikace naslouchá na 127.0.0.1 namísto všech rozhraní.
• Chybí požadovaný klíč prostředí.
• Připojení k databázi nebo Redis selže.
• Oprávnění k souborům blokují spuštění.
• Health endpoint vrací stav, který neoznačuje úspěch.
• Start trvá déle, než dovoluje nastavený počet opakování.
• Migrace selže nebo běží souběžně.

Konfiguraci health checku můžete zobrazit nebo aktualizovat:

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

Neoslabujte readiness gate jen proto, aby prošlo nefunkční vydání. Pokud spuštění oprávněně vyžaduje více času, upravte pravidla na základě důkazů a zachovejte endpoint, který stále potvrzuje připravenost.

Změny prostředí vyžadují nové nasazení. Pokud opravíte chybějící secret, nasaďte znovu a počkejte; restart starého kontejneru nové požadované prostředí nepoužije.

Jak mají agenti zpracovávat NDJSON bez ztráty návratového kódu?

Agent nebo skript by měl číst každý JSON řádek a současně zachovat stav procesu. Vyhněte se rourám do příkazu, který bez pipefail skryje původní návratový kód.

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

S nastavením pipefail zůstane při selhání příkazu Dockup celý pipeline nenulový, i když tee úspěšně dokončí svou práci.

Konzument může každý objekt zkontrolovat samostatně:

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

Nezahazujte původní NDJSON artefakt. Čitelný výpis je užitečný pro pull request nebo incident, ale původní pole zachovávají značky restartů, stav i signály dokončení.

Obecné principy rozhraní pro stroje vysvětluje článek Návrh CLI pro AI agenty.

Jak vytvořit opakovatelný runbook pro ladění nasazení?

Použijte tuto rozhodovací cestu:

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

Poté incident klasifikujte:

Klasifikace	Důkaz	Další akce
Zdrojový kód/build	Chyba v buildovacím logu	Opravte repozitář nebo definici buildu
Konfigurace	Chybějící/nesprávné prostředí nebo port	Opravte konfiguraci a nasaďte znovu
Připravenost	Aplikace běží, health check selhává	Opravte endpoint nebo odůvodněné časování
Runtime závislost	Výjimka při připojení	Zkontrolujte databázi/síť/přihlašovací údaje
Regrese	Předchozí verze fungovala	Zvažte rollback podle známého ID
Nejistota platformy	Timeout, chybějící konečný stav	Před opakováním zkontrolujte stav

Rollback proveďte až po identifikaci známého předchozího nasazení:

dockup rollback <deploymentId> production/api --json

Nejprve uložte ID neúspěšného nasazení a logy. Rollback obnoví dostupnost služby, ale nevysvětlí kořenovou příčinu.

Článek nasazení bez výpadku vysvětluje, proč může neúspěšný readiness gate chránit provoz.

Jak zajistit, aby byly produkční logy užitečné?

Dockup dokáže výstup načíst, kvalitu logů však řídí aplikace. Preferujte strukturované záznamy jedné události s časovým razítkem, závažností, ID požadavku nebo trace ID, názvem komponenty a bezpečným popisem chyby.

Nikdy nezapisujte access tokeny, URL databází, hesla, kompletní autorizační hlavičky ani osobní údaje, které nejsou pro provoz nezbytné. Maskování secretů v konfiguraci Dockup neodstraní citlivé údaje z libovolného výstupu aplikace.

Zapisujte bezpečné a diagnosticky užitečné informace o startu:

• Verze aplikace nebo commit.
• Název prostředí.
• Port, na kterém aplikace naslouchá.
• Názvy zapnutých funkcí bez hodnot secretů.
• Třída hostitele databáze, nikoli heslo.
• Verze migrace.
• Připravenost health endpointu.

Šablona časové osy incidentu

Zaznamenejte:

1. ID nasazení a zdrojový commit.
2. Čas zahájení nasazení a čas ukončení.
3. První příčinnou chybu buildu nebo runtime.
4. Výsledek readiness gate.
5. Příkaz pro obnovu a ID nasazení.
6. Časový rozsah dopadu na uživatele.
7. Osobu odpovědnou za následné kroky.

Data o dostupnosti přidávají dostupnost a dobu odezvy na úrovni minut:

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

Výsledek obsahuje průměrnou dobu odezvy a p95. Zkombinujte je s buildovacími a runtime logy, abyste odlišili incident při nasazení od dlouhodobější regrese výkonu.

Aktuální parametry logů najdete v referenci Dockup CLI a bezpečné logování aplikací v článku bezpečnostní doporučení.

Korelujte logy s historií nasazení

Řádek logu je užitečný pouze tehdy, když ho lze přiřadit ke správnému vydání. Vedle artefaktu s logy ukládejte ID nasazení, hash commitu a čas spuštění. Pokud dvě vydání proběhnou krátce po sobě, samotná časová razítka mohou být zavádějící.

dockup deployments production/api -n 20 --json

Historie nasazení určuje, který zdrojový kód byl aktivní a které vydání dosáhlo konečného stavu. Agent by neměl runtime výjimku připsat nejnovějšímu commitu, dokud stav služby nepotvrdí, že tento commit byl skutečně nasazen.

Zabraňte úniku secretů prostřednictvím logů

Selhání připojení často svádí vývojáře k vypsání celé URL. Místo toho zapisujte protokol, maskovaného hostitele, název databáze a kategorii chyby. U tokenů zapisujte pouze bezpečný fingerprint vygenerovaný před uložením, pokud pro to má organizace stanovenou politiku.

Před sdílením artefaktů neúspěšného buildu mimo tým je zkontrolujte. Výstup package manageru a Dockeru může obsahovat URL soukromých repozitářů, uživatelská jména registrů nebo argumenty příkazů, i když Dockup správně maskuje uložené secrets prostředí.

Díky tomu jsou buildovací a runtime logy dostatečně bezpečné pro společnou diagnostiku.

Zachovejte minimální balíček důkazů

Pro každé neúspěšné vydání uložte JSON s výsledkem nasazení, buildovací log, relevantní výřez runtime logu, stav služby a vybrané ID nasazení pro obnovu. Tento balíček je dostatečně malý pro běžné použití a zároveň dostatečně úplný, aby druhý operátor mohl pokračovat bez opakování nejistých mutací.

Ověřte opravu, nejen nový build

Po úspěšném nasazení opravené verze zopakujte neúspěšný požadavek nebo podmínku při startu a sledujte runtime výstup, zda se problém nevrací. Incident uzavřete až tehdy, když původní symptom zmizí, readiness gate projde a je potvrzeno očekávané chování v produkci.

Uzavřete celý cyklus

Zdokumentujte ověřenou opravu.

Začněte nasazením, které lze ověřit

Vynuceně nechte jeden testovací build selhat, zachyťte jeho NDJSON stream a návratový kód a poté ověřte, že váš runbook vybere buildovací log namísto runtime logu.

Začněte zdarma na app.dockup.ai. Tarif Free stojí 0 $ měsíčně, zahrnuje počáteční kredit 10 $ a podporuje jeden workspace, tři databáze a tři nasazení.

FAQ

Jaký je rozdíl mezi buildovacími a runtime logy Dockup?

Buildovací logy pokrývají klonování, instalaci závislostí, kompilaci a tvorbu image. Runtime logy pokrývají spuštěný aplikační kontejner nebo pody.

Jak mohu živě sledovat buildovací logy Dockup?

Použijte dockup logs s --build a --follow nebo -f. S parametrem --json příkaz vypisuje dávky ve formátu NDJSON a končí při dosažení konečného stavu nasazení.

Proč follow buildu končí s nenulovým návratovým kódem?

Zachovává výsledek nasazení. Neúspěšný build musí způsobit selhání volajícího shellu, CI úlohy nebo úlohy agenta, nikoli vypadat jako úspěšný stream logů.

Co znamená restarted:true ve výstupu sledování runtime logu?

Znamená to, že se kontejner restartoval nebo došlo k rotaci uchovávaného bufferu, takže Dockup znovu odeslal aktuální snapshot namísto tiché ztráty řádků.

Měly by logy aplikace obsahovat secrets prostředí?

Ne. Dockup maskuje načítání uložené konfigurace, ale nedokáže zabezpečit libovolné secrets vypsané aplikací. Přihlašovací údaje redigujte ve vrstvě logování aplikace.