Build- og runtime-logfiler: Fejlfind Dockup-deployments

Build- og runtime-logfiler besvarer forskellige spørgsmål. Build-logfiler forklarer, hvordan kildekode blev til et image, og hvorfor processen mislykkedes. Runtime-logfiler forklarer, hvad den buildede applikation gjorde, efter containeren eller Kubernetes-workloaden blev startet.

Hvis du læser den forkerte stream, spilder du tid. En manglende dependency under image-konstruktionen vises aldrig i runtime-logfiler, mens et image, der blev bygget korrekt, men crasher ved opstart, kan have helt fejlfri build-output.

Hvad er forskellen på build- og runtime-logfiler?

Vælg stream ud fra deployment-stadiet:

Stadie	Typisk status	Korrekt log	Almindelige fejl
Kloning	cloning	Build	Adgang til repository, branch
Installation af dependencies	building	Build	Lockfile, registry, package
Kompilering/bundling	building	Build	Typefejl, hukommelse, manglende filer
Opstart af image	deploying	Runtime og health	Startkommando, port, rettigheder
Kørende service	running	Runtime	Exceptions, udfald hos dependencies
Readiness-gate	deploying	Runtime plus health-konfiguration	Forkert sti, langsom opstart

Læs det seneste build-output:

dockup logs production/api --build --json

Læs runtime-output fra den kørende service:

dockup logs production/api --json

Hent flere runtime-linjer, når den relevante hændelse ligger længere tilbage:

dockup logs production/api -n 500 --json

JSON-svaret identificerer target og logtype, så en agent undgår at blande irrelevante streams sammen.

Hvordan fungerer dockup logs --build --follow?

Follow mode streamer nye linjer ved at polle det aktuelle snapshot:

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

I JSON mode er outputtet NDJSON: ét objekt pr. linje og pr. batch. En consumer kan behandle hver linje inkrementelt.

En afsluttende batch markerer det endelige build-resultat. Kommandoen stopper automatisk, når deploymentet lykkes eller mislykkes, og returnerer en non-zero exit-kode ved fejl. Det gør den velegnet til en agent eller et CI-job uden en håndskrevet status-loop.

Runtime follow fungerer på samme måde:

dockup logs production/api -f --json

Hver batch indeholder restarted. Når restarted:true, blev containeren genstartet, eller den gemte logbuffer blev rullet, så Dockup udsender hele det aktuelle snapshot igen i stedet for stille at miste linjer.

Standardintervallet for polling er 2 sekunder. Brug kun den dokumenterede --interval, når der er et konkret behov for at ændre frekvensen.

Hvordan fejlfinder du et mislykket build?

Begynd med det endelige deployment-resultat:

dockup deploy production/api --wait --json

Når kommandoen afsluttes med deploy_failed, skal du hente build-loggen og finde den første årsagsbestemmende fejl – ikke den sidste følgefejl.

En nyttig rækkefølge er:

1. Bekræft target og deployment-ID.
2. Identificér clone-, install-, compile- eller image-stadiet.
3. Find den første fejl, der ikke kan løses med en retry.
4. Sammenhold build-metoden med repositoryets hensigt.
5. Genskab problemet fra en ren clone, hvis det er muligt.
6. Foretag én målrettet ændring.
7. Udfør deployment igen med --wait.

Almindelige Nixpacks-fejl omfatter en ukendt project root, manglende lockfile, et manglende konventionelt startscript eller et krav om en native package. Almindelige Dockerfile-fejl omfatter en forkert build context, et manglende kopieret artifact, et utilgængeligt base image eller en fejlslagen RUN-instruktion.

Guiden Nixpacks vs Dockerfile indeholder et beslutningskort for build-systemer.

Undgå at løse en deterministisk build-fejl ved at øge timeouten på 900 sekunder. En ændring af timeouten hjælper ved et legitimt langt build, men løser ikke en kommando, der afsluttede med en fejl.

Hvordan fejlfinder du et runtime-crash eller en health-fejl?

Et vellykket image kan stadig fejle, før trafikken skifter over. Undersøg servicestatus og runtime-output:

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

Se efter:

• Processen afsluttes umiddelbart efter opstart.
• Applikationen binder til den forkerte port.
• Applikationen lytter på 127.0.0.1 i stedet for på alle interfaces.
• En påkrævet environment key mangler.
• Forbindelsen til databasen eller Redis mislykkes.
• Filtilladelser blokerer opstart.
• Health-stien returnerer en status, der ikke indikerer succes.
• Opstarten tager længere tid, end de konfigurerede retries tillader.
• En migration mislykkes eller kører samtidigt med en anden.

Health-konfigurationen kan inspiceres eller opdateres:

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

Du bør ikke svække health-gaten blot for at få et ødelagt release til at gå igennem. Hvis opstarten reelt kræver mere tid, skal du ændre politikken på baggrund af dokumentation og bevare et endpoint, der stadig bekræfter readiness.

Ændringer i environment kræver et nyt deployment. Hvis en manglende secret bliver rettet, skal du deploye igen og vente; en genstart af den gamle container anvender ikke det nye ønskede environment.

Hvordan bør agenter parse NDJSON uden at miste exit-koden?

En agent eller et script bør læse hver JSON-linje og samtidig bevare processtatussen. Undgå at pipe til en kommando, der skjuler den oprindelige exit-kode, uden pipefail.

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

Med pipefail forbliver en fejlet Dockup-kommando non-zero, selvom tee blev gennemført uden fejl.

En consumer kan inspicere hvert objekt separat:

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

Gem det rå NDJSON-artifact. Et læsevenligt uddrag er nyttigt i en pull request eller en incident, men de oprindelige felter bevarer restart-markører, status og completion-signaler.

De generelle principper for machine interfaces forklares i AI agent CLI design.

Hvad er en reproducerbar runbook til fejlfinding af deployments?

Brug denne beslutningssti:

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

Klassificér derefter incidenten:

Klassifikation	Dokumentation	Næste handling
Kildekode/build	Fejl i build-loggen	Ret repository eller build-definition
Konfiguration	Manglende/forkert env eller port	Ret konfigurationen, og udfør deployment igen
Readiness	Appen kører, men health fejler	Ret endpointet eller den begrundede timing
Runtime-dependency	Connection-exception	Kontrollér database/netværk/credentials
Regression	Den tidligere version virkede	Overvej rollback til et kendt ID
Usikkerhed om platformen	Timeout, ingen afsluttende status	Undersøg status før retry

Rul kun tilbage, når du har identificeret et kendt tidligere deployment:

dockup rollback <deploymentId> production/api --json

Gem det fejlede deployment-ID og logfilerne først. Et rollback gendanner service availability, men forklarer ikke den grundlæggende årsag.

Artiklen om zero-downtime deployments forklarer, hvorfor en fejlet readiness-gate kan beskytte live-trafikken.

Hvordan gør du production-logfiler nyttige?

Dockup kan hente output, men det er applikationen, der styrer logkvaliteten. Foretræk strukturerede records med én hændelse pr. record, timestamps, severity, request- eller trace-ID’er, komponentnavn og en sikker fejlbeskrivelse.

Log aldrig access tokens, database-URL’er, passwords, komplette authorization headers eller persondata, der ikke er nødvendige for driften. Secret masking i Dockup-konfigurationen redigerer ikke vilkårligt applikationsoutput.

Log opstartsfakta, som er sikre og kan bruges til fejlfinding:

• Applikationsversion eller commit.
• Environment-navn.
• Lytteport.
• Aktiverede feature-navne uden secret-værdier.
• Database-hostens klasse, men ikke passwordet.
• Migrationsversion.
• Readiness for health-endpointet.

Skabelon til incident-tidslinje

Registrér:

1. Deployment-ID og source commit.
2. Tidspunkt for deploymentstart og afslutning.
3. Den første årsagsbestemmende build- eller runtime-fejl.
4. Resultatet af health-gaten.
5. Recovery-kommando og deployment-ID.
6. Tidsrum med brugerens påvirkning.
7. Ansvarlig for opfølgning.

Uptime-data tilføjer tilgængelighed og svartid på minutniveau:

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

Resultatet indeholder gennemsnitlig svartid og p95-svartid. Kombinér det med build- og runtime-logfiler for at skelne mellem en deployment-incident og en længerevarende performance-regression.

Brug Dockup CLI-reference til de aktuelle log-flags og bedste praksis for sikkerhed til sikker applikationslogging.

Korreler logfiler med deploymenthistorikken

En linje er kun nyttig, når den kan knyttes til det korrekte release. Gem deployment-ID, commit hash og starttidspunkt sammen med log-artifactet. Når to releases finder sted tæt på hinanden, kan timestamps alene være misvisende.

dockup deployments production/api -n 20 --json

Deploymenthistorikken fastslår, hvilken kildekode der var aktiv, og hvilket release der nåede en afsluttende status. En agent bør ikke tilskrive en runtime-exception til det seneste commit, før servicestatus bekræfter, at dette commit faktisk blev deployet.

Undgå eksponering af secrets via logfiler

En fejlet forbindelse frister ofte udviklere til at udskrive hele URL’en. Log i stedet protokollen, en maskeret host, databasenavnet og fejlkategorien. For tokens skal du kun logge et sikkert fingerprint, der blev genereret før lagring, hvis organisationen har en politik for dette.

Gennemgå artifacts fra fejlede builds, før du deler dem uden for teamet. Package-manager- og Docker-output kan indeholde private repository-URL’er, registry-brugernavne eller kommandoargumenter, selvom Dockup korrekt maskerer gemte environment-secrets.

Det gør build- og runtime-logfiler tilstrækkeligt sikre til fælles fejlfinding.

Gem en minimal dokumentationspakke

Gem deployment-resultatets JSON, build-loggen, et relevant runtime-uddrag, servicestatus og det valgte deployment-ID til recovery for hvert fejlet release. Denne pakke er lille nok til rutinemæssig brug og komplet nok til, at en anden operatør kan fortsætte uden at gentage usikre mutationer.

Bekræft rettelsen – ikke kun det nye build

Når det korrigerede deployment lykkes, skal du gentage den fejlede request eller opstartsbetingelse og holde øje med runtime-output for at se, om problemet vender tilbage. Luk først incidenten, når det oprindelige symptom er væk, health-gaten passerer, og den forventede produktionsadfærd er observeret.

Afslut forløbet

Dokumentér den verificerede rettelse.

Begynd med et deployment, der kan verificeres

Tving ét test-build til at fejle, gem dets NDJSON-stream og exit-kode, og kontrollér derefter, at din runbook vælger build-loggen i stedet for runtime-loggen.

Start gratis på app.dockup.ai. Free-planen koster $0 pr. måned, inkluderer $10 i startkredit og understøtter ét workspace, tre databaser og tre deployments.

FAQ

Hvad er forskellen på Dockup-build-logfiler og runtime-logfiler?

Build-logfiler dækker kloning, installation af dependencies, kompilering og oprettelse af images. Runtime-logfiler dækker den startede applikationscontainer eller pods.

Hvordan følger jeg Dockup-build-logfiler live?

Brug dockup logs med --build og --follow eller -f. Med --json udsender kommandoen NDJSON-batches og afsluttes ved deploymentets endelige status.

Hvorfor afsluttes build follow med en non-zero exit-kode?

Kommandoen bevarer deployment-resultatet. Et fejlet build skal få det kaldende shell, CI-job eller agent-task til at fejle i stedet for at ligne en vellykket logstream.

Hvad betyder restarted:true i runtime follow-output?

Det angiver, at containeren blev genstartet, eller at den gemte buffer blev rullet, så Dockup udsendte det aktuelle snapshot igen i stedet for stille at miste linjer.

Bør applikationslogfiler indeholde environment-secrets?

Nej. Dockup maskerer læsning af gemt konfiguration, men kan ikke gøre vilkårlige secrets, som applikationen udskriver, sikre. Redigér credentials i applikationens logging-lag.