Build- och runtime-loggar: felsök Dockup-distributioner

Build- och runtime-loggar besvarar olika frågor. Build-loggar förklarar hur källkod blev en image och varför processen misslyckades. Runtime-loggar förklarar vad den byggda applikationen gjorde efter att containern eller Kubernetes-workloaden startade.

Att läsa fel loggström slösar tid. Ett saknat beroende under image-bygget visas aldrig i runtime-loggar, medan en image som byggts utan problem men kraschar vid uppstart kan ha helt rena build-loggar.

Vad är skillnaden mellan build- och runtime-loggar?

Använd distributionssteget för att välja rätt ström:

Steg	Typisk status	Rätt logg	Vanliga fel
Kloning	cloning	Build	Åtkomst till repository, branch
Installation av beroenden	building	Build	Lockfile, registry, paket
Kompilering/bundling	building	Build	Typfel, minne, saknade filer
Image-start	deploying	Runtime och health	Startkommando, port, behörigheter
Körande tjänst	running	Runtime	Undantag, avbrott i beroenden
Readiness-gate	deploying	Runtime plus health-konfiguration	Fel sökväg, långsam uppstart

Läs den senaste build-outputen:

dockup logs production/api --build --json

Läs runtime-output från den körande tjänsten:

dockup logs production/api --json

Begär fler runtime-rader när den relevanta händelsen är äldre:

dockup logs production/api -n 500 --json

JSON-svaret identifierar mål och loggtyp, vilket hjälper en agent att undvika att slå ihop orelaterade strömmar.

Hur fungerar dockup logs --build --follow?

Follow-läget strömmar nya rader genom att polla den aktuella snapshoten:

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

I JSON-läge är outputen NDJSON: ett objekt per rad och per batch. En konsument kan bearbeta varje rad stegvis.

En sista batch markerar buildens slutliga resultat. Kommandot avslutas automatiskt när distributionen lyckas eller misslyckas och returnerar en exit-kod som inte är noll vid fel. Det gör kommandot lämpligt för en agent eller ett CI-jobb utan en manuellt skriven statusloop.

Runtime-follow fungerar på liknande sätt:

dockup logs production/api -f --json

Varje batch innehåller restarted. När restarted:true innebär det att containern startades om eller att den sparade loggbufferten rullades över, så Dockup skickar hela den aktuella snapshoten igen i stället för att tyst tappa rader.

Standardintervallet för polling är 2 sekunder. Använd det dokumenterade --interval endast när det finns ett specifikt behov av att ändra frekvensen.

Hur felsöker du en misslyckad build?

Börja med det slutliga distributionsresultatet:

dockup deploy production/api --wait --json

När kommandot avslutas med `deploy_failed hämtar du build-loggen och letar efter det första orsaksfelet, inte det sista följdfelet.

En användbar ordningsföljd är:

1. Bekräfta mål och distributions-ID.
2. Identifiera klonings-, installations-, kompilerings- eller imagesteget.
3. Hitta det första felet som inte kan åtgärdas genom retry.
4. Jämför build-metoden med repositoryts avsikt.
5. Återskapa från en ren kloning om möjligt.
6. Gör en avgränsad ändring.
7. Distribuera igen med --wait.

Vanliga Nixpacks-fel är en oigenkänd projektrot, saknad lockfile, avsaknad av ett konventionellt startskript eller krav på ett native-paket. Vanliga Dockerfile-fel är felaktig build context, en saknad kopierad artefakt, en otillgänglig base image eller en felande RUN-instruktion.

Guiden Nixpacks vs Dockerfile innehåller en beslutsöversikt för val av build-system.

Försök inte åtgärda ett deterministiskt build-fel genom att öka timeouten på 900 sekunder. En timeoutändring hjälper vid en legitimt lång build, men reparerar inte ett kommando som avslutades med ett fel.

Hur felsöker du en runtime-krasch eller ett health-fel?

En image som byggts utan problem kan ändå fallera innan trafiken växlas över. Kontrollera tjänstens status och runtime-output:

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

Leta efter:

• Processen avslutas omedelbart efter start.
• Applikationen binder till fel port.
• Applikationen lyssnar på 127.0.0.1 i stället för på alla interface.
• En obligatorisk environment-nyckel saknas.
• Anslutningen till databasen eller Redis misslyckas.
• Filbehörigheter blockerar uppstarten.
• Health-sökvägen returnerar en status som inte visar framgång.
• Uppstarten tar längre tid än vad de konfigurerade försöken tillåter.
• En migration misslyckas eller körs parallellt.

Health-konfigurationen kan inspekteras eller uppdateras:

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

Försvaga inte health-gaten bara för att få en trasig release att passera. Om uppstarten legitimt behöver mer tid ändrar du policyn med stöd i fakta och behåller en endpoint som fortfarande bekräftar readiness.

Ändringar i environment kräver en ny distribution. Om en saknad secret åtgärdas ska du distribuera igen och vänta; en omstart av den gamla containern tillämpar inte den nya önskade environment-konfigurationen.

Hur bör agenter parsa NDJSON utan att förlora exit-koden?

En agent eller ett skript bör läsa varje JSON-rad och samtidigt bevara processens status. Undvik att pipea till ett kommando som maskerar den ursprungliga exit-koden utan pipefail.

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

Med pipefail förblir ett misslyckat Dockup-kommando ett icke-nollvärde i pipelinen, även om tee slutfördes utan problem.

En konsument kan inspektera varje objekt separat:

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

Spara det råa NDJSON-artefaktet. Ett läsbart utdrag är användbart i en pull request eller incident, men originalfälten bevarar omstartsmarkörer, status och slutförandesignaler.

De allmänna principerna för maskingränssnitt förklaras i AI agent CLI design.

Vad är en repeterbar runbook för felsökning av distributioner?

Använd denna beslutsväg:

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

Klassificera sedan incidenten:

Klassificering	Bevis	Nästa åtgärd
Källa/build	Fel i build-loggen	Åtgärda repository eller build-definition
Konfiguration	Saknad/felaktig env eller port	Korrigera konfigurationen och distribuera igen
Readiness	Appen körs, health misslyckas	Åtgärda endpointen eller motivera tidsinställningen
Runtime-beroende	Anslutningsundantag	Kontrollera databas/nätverk/credentials
Regression	Föregående version fungerade	Överväg rollback med känt ID
Osäkerhet kring plattformen	Timeout, inget slutstatus	Kontrollera status innan nytt försök

Rulla endast tillbaka efter att ha identifierat en tidigare känd distribution:

dockup rollback <deploymentId> production/api --json

Spara det misslyckade distributions-ID:t och loggarna först. En rollback återställer tjänstens tillgänglighet, men förklarar inte grundorsaken.

Artikeln om zero-downtime deployments förklarar varför en misslyckad readiness-gate kan skydda live-trafik.

Hur gör man produktionsloggar användbara?

Dockup kan hämta output, men det är applikationen som styr loggarnas kvalitet. Föredra strukturerade poster för enskilda händelser med tidsstämplar, allvarlighetsgrad, request- eller trace-ID:n, komponentnamn och en säker felbeskrivning.

Logga aldrig access tokens, databas-URL:er, lösenord, fullständiga authorization headers eller personuppgifter som inte behövs för driften. Secret-maskning i Dockup-konfigurationen redigerar inte godtycklig application output.

Logga uppstartsfakta som är säkra och möjliga att diagnostisera:

• Applikationsversion eller commit.
• Miljönamn.
• Lyssnande port.
• Aktiverade feature-namn utan secret-värden.
• Databasens host-klass, inte lösenordet.
• Migrationsversion.
• Readiness för health-endpointen.

Mall för incidenttidslinje

Dokumentera:

1. Distributions-ID och källcommit.
2. Tidsstämplar för distributionsstart och slutförande.
3. Det första orsaksfelet i build eller runtime.
4. Resultatet från health-gaten.
5. Återställningskommando och distributions-ID.
6. Tidsfönstret för användarpåverkan.
7. Ansvarig för uppföljningen.

Uptime-data ger tillgänglighet och svarstid på minutnivå:

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

Resultatet innehåller genomsnittlig svarstid och p95-svarstid. Kombinera detta med build- och runtime-loggar för att skilja en distributionsincident från en längre prestandaregression.

Använd Dockup CLI reference för aktuella loggflaggor och security best practices för säker applikationsloggning.

Korrelatera loggar med distributionshistoriken

En rad är användbar först när den kan kopplas till rätt release. Spara distributions-ID, commit-hash och starttid tillsammans med loggartefakten. När två releaser sker nära varandra kan enbart tidsstämplar vara missvisande.

dockup deployments production/api -n 20 --json

Distributionshistoriken visar vilken källa som var aktiv och vilken release som nådde ett slutgiltigt tillstånd. En agent bör inte tillskriva ett runtime-undantag till den senaste committen innan tjänstens status bekräftar att committen faktiskt distribuerades.

Undvik att exponera secrets via loggar

Ett misslyckat anslutningsförsök frestar ofta utvecklare att skriva ut hela URL:en. Logga i stället protokoll, maskad host, databasnamn och felkategori. För tokens ska du endast logga ett säkert fingerprint som genererats före lagring, när organisationen har en policy för detta.

Granska artefakter från misslyckade builds innan du delar dem utanför teamet. Package-manager- och Docker-output kan innehålla privata repository-URL:er, registry-användarnamn eller kommandoargument även när Dockup maskerar lagrade environment-secrets korrekt.

Detta gör build- och runtime-loggar tillräckligt säkra för gemensam felsökning.

Bevara ett minimalt evidenspaket

Spara distributionsresultatets JSON, build-loggen, relevant runtime-utdrag, tjänstens status och valt distributions-ID för återställningen för varje misslyckad release. Paketet är tillräckligt litet för rutinmässig användning och tillräckligt komplett för att en annan operatör ska kunna fortsätta utan att köra osäkra mutationer igen.

Bekräfta åtgärden, inte bara den nya builden

När den korrigerade distributionen lyckas ska du upprepa den felande requesten eller uppstartssituationen och bevaka runtime-outputen för att se om problemet återkommer. Avsluta incidenten först när det ursprungliga symptomet saknas, health-gaten passerar och det förväntade produktionsbeteendet har observerats.

Slut loopen

Dokumentera den verifierade åtgärden.

Börja med en verifierbar distribution

Tvinga en test-build att misslyckas, fånga dess NDJSON-ström och exit-kod och verifiera sedan att din runbook väljer build-loggen i stället för runtime-loggen.

Starta gratis på app.dockup.ai. Free-planen kostar 0 USD per månad, inkluderar en startkredit på 10 USD och stöder en workspace, tre databaser och tre distributioner.

FAQ

Vad är skillnaden mellan Dockups build-loggar och runtime-loggar?

Build-loggar omfattar kloning, installation av beroenden, kompilering och skapande av images. Runtime-loggar omfattar den startade applikationscontainern eller pods.

Hur följer jag Dockups build-loggar live?

Använd dockup logs med --build och --follow, eller -f. Med --json skickar kommandot NDJSON-batcher och avslutas när distributionen når sitt slutgiltiga tillstånd.

Varför avslutas build follow med en exit-kod som inte är noll?

Kommandot bevarar distributionsresultatet. En misslyckad build måste göra att det anropande skalet, CI-jobbet eller agentuppgiften misslyckas i stället för att se ut som en lyckad loggström.

Vad betyder restarted:true i output från runtime follow?

Det visar att containern startades om eller att den sparade bufferten rullades över, så Dockup skickade den aktuella snapshoten igen i stället för att tyst förlora rader.

Bör applikationsloggar innehålla environment-secrets?

Nej. Dockup maskerar läsningar från lagrad konfiguration, men kan inte göra godtyckliga secrets som skrivs ut av applikationen säkra. Redigera credentials i applikationens loggningslager.