Build- en runtime-logboeken: Dockup-deployments debuggen

Build- en runtime-logboeken beantwoorden verschillende vragen. Build-logboeken leggen uit hoe broncode in een image is omgezet en waarom dat proces is mislukt. Runtime-logboeken leggen uit wat de gebouwde applicatie deed nadat de container of Kubernetes-workload was gestart.

De verkeerde stream lezen kost tijd. Een ontbrekende dependency tijdens het bouwen van de image verschijnt nooit in runtime-logboeken, terwijl een succesvolle image die bij het opstarten crasht, perfect schone build-output kan hebben.

Wat is het verschil tussen build- en runtime-logboeken?

Gebruik de deploymentfase om de juiste stream te kiezen:

Fase	Typische status	Juiste logboek	Veelvoorkomende fouten
Klonen	cloning	Build	Repositorytoegang, branch
Dependencies installeren	building	Build	Lockfile, registry, package
Compileren/bundelen	building	Build	Typefouten, geheugen, ontbrekende bestanden
Image starten	deploying	Runtime en health	Startopdracht, poort, rechten
Service actief	running	Runtime	Exceptions, uitval van dependencies
Readiness-gate	deploying	Runtime plus health-configuratie	Verkeerd pad, trage start

Lees de meest recente build-output:

dockup logs production/api --build --json

Lees runtime-output van de actieve service:

dockup logs production/api --json

Vraag meer runtime-regels op wanneer de relevante gebeurtenis ouder is:

dockup logs production/api -n 500 --json

De JSON-response identificeert het doel en het type logboek. Zo kan een agent voorkomen dat niet-gerelateerde streams worden samengevoegd.

Hoe werkt dockup logs --build --follow?

De follow-modus streamt nieuwe regels door de huidige snapshot te pollen:

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

In JSON-modus is de output NDJSON: één object per regel en per batch. Een consumer kan elke regel incrementeel verwerken.

Een laatste batch markeert het terminale buildresultaat. De opdracht stopt automatisch wanneer de deployment slaagt of mislukt en retourneert bij een fout een non-zero exitcode. Daardoor is deze geschikt voor een agent of CI-job zonder handgeschreven statuslus.

Runtime-follow werkt op vergelijkbare wijze:

dockup logs production/api -f --json

Elke batch bevat restarted. Wanneer restarted:true, is de container opnieuw gestart of is de bewaarde logbuffer gerold. Dockup stuurt dan de volledige huidige snapshot opnieuw uit in plaats van stilletjes regels over te slaan.

Het standaardpollingsinterval is 2 seconden. Gebruik --interval alleen wanneer er een specifieke reden is om de frequentie aan te passen.

Hoe diagnosticeer je een mislukte build?

Begin met het terminale deploymentresultaat:

dockup deploy production/api --wait --json

Wanneer dit eindigt met deploy_failed, haal je het build-logboek op en zoek je naar de eerste oorzakelijke fout, niet naar het laatste cascadebericht.

Een bruikbare volgorde is:

1. Bevestig het doel en de deployment-ID.
2. Bepaal de clone-, install-, compile- of imagefase.
3. Zoek de eerste niet-herhaalbare fout.
4. Vergelijk de buildmethode met de bedoeling van de repository.
5. Reproduceer het probleem indien mogelijk vanuit een schone clone.
6. Voer één gerichte wijziging door.
7. Voer opnieuw een deployment uit met --wait.

Veelvoorkomende Nixpacks-fouten zijn een niet-herkende projectroot, een ontbrekende lockfile, een ontbrekend conventioneel startscript of een vereiste voor een native package. Veelvoorkomende Dockerfile-fouten zijn een incorrecte buildcontext, een ontbrekend gekopieerd artifact, een niet-beschikbare base image of een mislukte RUN-instructie.

De handleiding Nixpacks vs Dockerfile bevat een beslisoverzicht voor buildsystemen.

Probeer een deterministische buildfout niet op te lossen door de timeout van 900 seconden te verhogen. Een timeoutwijziging helpt bij een legitiem lange build, maar herstelt geen opdracht die met een fout is geëindigd.

Hoe diagnosticeer je een runtime-crash of health-fout?

Een succesvolle image kan nog steeds falen voordat het verkeer wordt omgeleid. Inspecteer de servicestatus en runtime-output:

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

Let op:

• Het proces wordt direct na het starten beëindigd.
• De applicatie bindt aan de verkeerde poort.
• De applicatie luistert op 127.0.0.1 in plaats van op alle interfaces.
• Een vereiste omgevingsvariabele ontbreekt.
• De verbinding met de database of Redis mislukt.
• Bestandsrechten blokkeren het opstarten.
• Het health-pad retourneert een niet-succesvolle status.
• Het opstarten duurt langer dan de geconfigureerde retries toestaan.
• Een migratie mislukt of wordt gelijktijdig uitgevoerd.

De health-configuratie kan worden geïnspecteerd of bijgewerkt:

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

Verzwak de health-gate niet alleen om een defecte release te laten slagen. Als het opstarten legitiem meer tijd nodig heeft, pas je het beleid aan op basis van bewijs en behoud je een endpoint dat readiness nog steeds aantoont.

Voor wijzigingen in de omgeving is een nieuwe deployment vereist. Als een ontbrekend secret is hersteld, deploy je opnieuw en wacht je; het herstarten van de oude container past de nieuwe gewenste omgeving niet toe.

Hoe moeten agents NDJSON parseren zonder de exitcode te verliezen?

Een agent of script moet elke JSON-regel lezen en tegelijkertijd de processtatus behouden. Vermijd piping naar een opdracht die de oorspronkelijke exitcode maskeert zonder pipefail.

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

Met pipefail blijft een mislukte Dockup-opdracht ervoor zorgen dat de pipeline een non-zero status heeft, ook al is tee succesvol afgerond.

Een consumer kan elk object afzonderlijk inspecteren:

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

Bewaar het onbewerkte NDJSON-artifact. Een leesbaar fragment is nuttig voor een pull request of incident, maar de oorspronkelijke velden bewaren restart-markers, status en voltooiingssignalen.

De algemene principes voor machine-interfaces worden uitgelegd in AI agent CLI design.

Wat is een herhaalbaar runbook voor deployment-debugging?

Gebruik deze beslisroute:

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

Classificeer het incident vervolgens:

Classificatie	Bewijs	Volgende actie
Broncode/build	Fout in build-logboek	Repository of builddefinitie herstellen
Configuratie	Ontbrekende/verkeerde omgeving of poort	Configuratie corrigeren en opnieuw deployen
Readiness	Applicatie draait, health faalt	Endpoint of onderbouwde timing aanpassen
Runtime-dependency	Connection-exception	Database, netwerk of credentials controleren
Regressie	Vorige versie werkte	Bekende deployment-ID overwegen voor rollback
Onzekerheid over platform	Timeout, geen terminale status	Status inspecteren vóór opnieuw proberen

Rollback pas nadat je een bekende vorige deployment hebt geïdentificeerd:

dockup rollback <deploymentId> production/api --json

Bewaar eerst de mislukte deployment-ID en de logboeken. Een rollback herstelt de beschikbaarheid van de service, maar verklaart de hoofdoorzaak niet.

Het artikel over zero-downtime deployments legt uit waarom een mislukte readiness-gate live verkeer kan beschermen.

Hoe maak je productielogboeken nuttig?

Dockup kan output ophalen, maar de applicatie bepaalt de kwaliteit van de logboeken. Gebruik bij voorkeur gestructureerde records met één gebeurtenis per record, timestamps, severity, request- of trace-ID's, de componentnaam en een veilige beschrijving van de fout.

Log nooit access tokens, database-URL's, wachtwoorden, volledige authorization headers of persoonsgegevens die niet nodig zijn voor de operatie. Secret masking in de Dockup-configuratie redigeert niet willekeurige applicatie-output.

Log veilige en diagnostisch bruikbare feiten over het opstarten:

• Applicatieversie of commit.
• Omgevingsnaam.
• Luisterende poort.
• Ingeschakelde featurenamen zonder secretwaarden.
• Databasehostklasse, niet het wachtwoord.
• Migratieversie.
• Readiness van het health-endpoint.

Template voor de incidenttijdlijn

Leg het volgende vast:

1. Deployment-ID en broncommit.
2. Tijdstippen van de start en terminale status van de deployment.
3. Eerste oorzakelijke build- of runtimefout.
4. Resultaat van de health-gate.
5. Herstelopdracht en deployment-ID.
6. Periode van gebruikersimpact.
7. Verantwoordelijke voor de opvolging.

Uptimegegevens voegen beschikbaarheid en responstijd op minutenniveau toe:

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

Het resultaat bevat de gemiddelde en p95-responstijd. Combineer dit met build- en runtime-logboeken om een deploymentincident te onderscheiden van een langere performanceregressie.

Gebruik de Dockup CLI reference voor de actuele logflags en security best practices voor veilige applicatielogging.

Logboeken correleren met de deploymentgeschiedenis

Een regel is alleen nuttig wanneer deze aan de juiste release kan worden gekoppeld. Bewaar de deployment-ID, commit-hash en starttijd naast het log-artifact. Wanneer twee releases kort na elkaar plaatsvinden, kunnen alleen timestamps misleidend zijn.

dockup deployments production/api -n 20 --json

De deploymentgeschiedenis laat zien welke bron actief was en welke release een terminale status bereikte. Een agent mag een runtime-exception niet aan de laatste commit toeschrijven voordat de servicestatus bevestigt dat die commit daadwerkelijk is gedeployed.

Voorkom dat secrets via logboeken uitlekken

Een mislukte verbinding kan ontwikkelaars ertoe verleiden de volledige URL te printen. Log in plaats daarvan het protocol, de gemaskeerde host, de databasenaam en de foutcategorie. Log voor tokens alleen een veilige fingerprint die vóór opslag is gegenereerd, wanneer de organisatie hiervoor beleid heeft.

Controleer artifacts van mislukte builds voordat je ze buiten het team deelt. Output van package managers en Docker kan private repository-URL's, registry-gebruikersnamen of command arguments bevatten, ook wanneer Dockup opgeslagen omgevingssecrets correct maskeert.

Zo zijn build- en runtime-logboeken veilig genoeg voor gezamenlijke diagnose.

Bewaar een minimale evidencebundel

Bewaar voor elke mislukte release de JSON van het deploymentresultaat, het build-logboek, het relevante runtime-fragment, de servicestatus en de geselecteerde deployment-ID voor herstel. Deze bundel is klein genoeg voor routinematig gebruik en volledig genoeg om een tweede operator zonder het opnieuw uitvoeren van onzekere mutaties te laten doorgaan.

Bevestig de oplossing, niet alleen de nieuwe build

Herhaal na een succesvolle gecorrigeerde deployment het mislukte request of de betreffende opstartconditie en houd de runtime-output in de gaten om herhaling vast te stellen. Sluit het incident pas wanneer het oorspronkelijke symptoom afwezig is, de health-gate slaagt en het verwachte productiegedrag is waargenomen.

Rond de cyclus af

Documenteer de geverifieerde oplossing.

Begin met een verifieerbare deployment

Laat bewust één testbuild mislukken, leg de NDJSON-stream en exitcode vast en controleer vervolgens of je runbook het build-logboek selecteert in plaats van het runtime-logboek.

Start gratis bij app.dockup.ai. Het Free-plan kost $0 per maand, bevat $10 aan starttegoed en ondersteunt één workspace, drie databases en drie deployments.

FAQ

Wat is het verschil tussen Dockup-build-logboeken en runtime-logboeken?

Build-logboeken omvatten het klonen, installeren van dependencies, compileren en maken van de image. Runtime-logboeken omvatten de gestarte applicatiecontainer of pods.

Hoe volg ik Dockup-build-logboeken live?

Gebruik dockup logs met --build en --follow, of -f. Met --json geeft de opdracht NDJSON-batches uit en eindigt deze bij de terminale status van de deployment.

Waarom eindigt build follow met een non-zero status?

De deploymentuitkomst blijft behouden. Een mislukte build moet de aanroepende shell, CI-job of agenttaak laten falen in plaats van eruit te zien als een succesvolle logstream.

Wat betekent restarted:true in runtime-follow-output?

Dit geeft aan dat de container opnieuw is gestart of dat de bewaarde buffer is gerold. Daarom heeft Dockup de huidige snapshot opnieuw uitgegeven in plaats van stilletjes regels te verliezen.

Mogen applicatielogboeken omgevingssecrets bevatten?

Nee. Dockup maskeert het uitlezen van opgeslagen configuratie, maar kan willekeurige secrets die door de applicatie worden geprint niet veilig maken. Redigeer credentials in de logginglaag van de applicatie.