Build- und Runtime-Logs: Dockup-Deployments debuggen

Build- und Runtime-Logs beantworten unterschiedliche Fragen. Build-Logs erklären, wie aus Quellcode ein Image erstellt wurde und warum dieser Prozess fehlgeschlagen ist. Runtime-Logs zeigen, was die erstellte Anwendung nach dem Start des Containers oder der Kubernetes-Workload getan hat.

Den falschen Stream zu lesen, kostet Zeit. Eine fehlende Abhängigkeit während der Image-Erstellung wird niemals in Runtime-Logs auftauchen, während ein erfolgreich erstelltes Image, das beim Start abstürzt, einwandfreie Build-Ausgaben haben kann.

Was ist der Unterschied zwischen Build- und Runtime-Logs?

Wähle anhand der Deployment-Phase den passenden Stream:

Phase	Typischer Status	Passendes Log	Häufige Fehler
Klonen	cloning	Build	Repository-Zugriff, Branch
Abhängigkeiten installieren	building	Build	Lockfile, Registry, Paket
Kompilieren/Bundling	building	Build	Typfehler, Speicher, fehlende Dateien
Image-Start	deploying	Runtime und Health	Startbefehl, Port, Berechtigungen
Laufender Service	running	Runtime	Exceptions, Ausfälle von Abhängigkeiten
Readiness-Gate	deploying	Runtime plus Health-Konfiguration	Falscher Pfad, langsamer Start

Lies die aktuelle Build-Ausgabe:

dockup logs production/api --build --json

Lies die Runtime-Ausgabe des laufenden Services:

dockup logs production/api --json

Fordere mehr Runtime-Zeilen an, wenn das relevante Ereignis weiter zurückliegt:

dockup logs production/api -n 500 --json

Die JSON-Antwort identifiziert Ziel und Log-Typ. Das hilft einem Agenten, nicht zusammengehörige Streams zu vermischen.

Wie funktioniert dockup logs --build --follow?

Der Follow-Modus streamt neue Zeilen, indem er regelmäßig den aktuellen Snapshot abfragt:

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

Im JSON-Modus ist die Ausgabe NDJSON: ein Objekt pro Zeile und pro Batch. Ein Consumer kann jede Zeile inkrementell verarbeiten.

Ein abschließender Batch kennzeichnet das finale Build-Ergebnis. Der Befehl beendet sich selbstständig, wenn das Deployment erfolgreich ist oder fehlschlägt, und endet bei einem Fehler mit einem Wert ungleich null. Dadurch eignet er sich für einen Agenten oder CI-Job ohne eine selbst geschriebene Statusschleife.

Runtime-Follow funktioniert ähnlich:

dockup logs production/api -f --json

Jeder Batch enthält restarted. Wenn restarted:true gesetzt ist, wurde der Container neu gestartet oder der vorgehaltene Log-Puffer überschrieben. Dockup gibt dann den vollständigen aktuellen Snapshot erneut aus, statt Zeilen stillschweigend zu verlieren.

Das Standard-Abfrageintervall beträgt 2 Sekunden. Verwende --interval nur dann, wenn es einen konkreten Grund gibt, die Frequenz zu ändern.

Wie diagnostiziert man einen fehlgeschlagenen Build?

Beginne mit dem finalen Deployment-Ergebnis:

dockup deploy production/api --wait --json

Wenn der Befehl mit deploy_failed endet, rufe das Build-Log ab und suche nach dem ersten ursächlichen Fehler, nicht nach der letzten Folgefehlermeldung.

Eine sinnvolle Reihenfolge ist:

1. Ziel und Deployment-ID bestätigen.
2. Klon-, Installations-, Kompilierungs- oder Image-Phase bestimmen.
3. Den ersten nicht wiederholbaren Fehler finden.
4. Die Build-Methode mit der Absicht des Repositorys vergleichen.
5. Wenn möglich, aus einem sauberen Klon reproduzieren.
6. Eine gezielte Änderung vornehmen.
7. Mit --wait erneut deployen.

Häufige Nixpacks-Fehler sind ein nicht erkanntes Projektverzeichnis, ein fehlendes Lockfile, ein fehlendes konventionelles Start-Skript oder eine erforderliche native Paketabhängigkeit. Häufige Dockerfile-Fehler sind ein falscher Build-Kontext, ein fehlendes kopiertes Artefakt, ein nicht verfügbares Base-Image oder eine fehlschlagende RUN-Anweisung.

Der Leitfaden Nixpacks vs Dockerfile bietet eine Entscheidungshilfe für Build-Systeme.

Versuche nicht, einen deterministischen Build-Fehler durch Erhöhen des 900-Sekunden-Timeouts zu beheben. Eine Timeout-Änderung hilft bei einem legitimen langen Build, repariert aber keinen Befehl, der mit einem Fehler beendet wurde.

Wie diagnostiziert man einen Runtime-Absturz oder Health-Fehler?

Ein erfolgreich erstelltes Image kann noch vor der Umschaltung des Traffics fehlschlagen. Prüfe den Service-Status und die Runtime-Ausgabe:

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

Achte auf Folgendes:

• Der Prozess wird direkt nach dem Start beendet.
• Die Anwendung bindet an den falschen Port.
• Die Anwendung lauscht auf 127.0.0.1 statt auf allen Interfaces.
• Ein erforderlicher Environment-Key fehlt.
• Die Verbindung zur Datenbank oder zu Redis schlägt fehl.
• Dateiberechtigungen verhindern den Start.
• Der Health-Pfad liefert einen nicht erfolgreichen Status.
• Der Start dauert länger, als die konfigurierte Anzahl an Retries erlaubt.
• Eine Migration schlägt fehl oder läuft parallel.

Die Health-Konfiguration kann eingesehen oder aktualisiert werden:

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

Schwäche das Health-Gate nicht einfach ab, damit ein fehlerhaftes Release durchläuft. Wenn der Start berechtigterweise mehr Zeit benötigt, passe die Richtlinie anhand von Belegen an und behalte einen Endpunkt bei, der die Readiness weiterhin nachweist.

Änderungen an der Umgebung erfordern ein erneutes Deployment. Wenn ein fehlendes Secret korrigiert wurde, deploye erneut und warte; ein Neustart des alten Containers übernimmt die neue Zielumgebung nicht.

Wie parsen Agenten NDJSON, ohne den Exit-Code zu verlieren?

Ein Agent oder Skript sollte jede JSON-Zeile lesen und dabei den Prozessstatus bewahren. Vermeide es, in einen Befehl zu pipen, der den ursprünglichen Exit-Code ohne pipefail verdeckt.

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

Mit pipefail bleibt eine fehlgeschlagene Dockup-Ausführung innerhalb der Pipeline ungleich null, auch wenn tee erfolgreich abgeschlossen wurde.

Ein Consumer kann jedes Objekt unabhängig auswerten:

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

Bewahre das rohe NDJSON-Artefakt auf. Ein lesbarer Auszug ist für einen Pull Request oder einen Incident hilfreich, aber die ursprünglichen Felder bewahren Restart-Marker, Status und Abschluss-Signale.

Die allgemeinen Prinzipien für Maschinen-Schnittstellen werden in CLI-Design für KI-Agenten erklärt.

Wie sieht ein wiederholbarer Runbook zur Deployment-Diagnose aus?

Verwende diesen Entscheidungsweg:

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

Klassifiziere den Incident anschließend:

Klassifizierung	Beleg	Nächste Aktion
Quellcode/Build	Fehler im Build-Log	Repository oder Build-Definition korrigieren
Konfiguration	Fehlende/falsche Umgebung oder falscher Port	Konfiguration korrigieren und erneut deployen
Readiness	Anwendung läuft, Health schlägt fehl	Endpunkt oder begründete Zeitvorgabe korrigieren
Runtime-Abhängigkeit	Verbindungs-Exception	Datenbank, Netzwerk oder Zugangsdaten prüfen
Regression	Vorherige Version funktionierte	Bekannten Rollback per ID erwägen
Plattformunsicherheit	Timeout, kein finaler Status	Status vor einem erneuten Versuch prüfen

Führe einen Rollback erst durch, nachdem du ein bekanntes vorheriges Deployment identifiziert hast:

dockup rollback <deploymentId> production/api --json

Bewahre zuerst die ID und Logs des fehlgeschlagenen Deployments auf. Ein Rollback stellt die Service-Verfügbarkeit wieder her, erklärt aber nicht die eigentliche Ursache.

Der Artikel Deployments ohne Downtime erklärt, warum ein fehlgeschlagenes Readiness-Gate den Live-Traffic schützen kann.

Wie lassen sich Produktions-Logs sinnvoll nutzen?

Dockup kann Ausgaben abrufen, aber die Anwendung bestimmt deren Qualität. Bevorzuge strukturierte Records mit genau einem Ereignis pro Eintrag sowie Zeitstempel, Schweregrad, Request- oder Trace-IDs, Komponentennamen und einer sicheren Fehlerbeschreibung.

Logge niemals Access-Tokens, Datenbank-URLs, Passwörter, vollständige Authorization-Header oder personenbezogene Daten, die für den Betrieb nicht erforderlich sind. Das Maskieren von Secrets in der Dockup-Konfiguration redigiert keine beliebigen Anwendungsausgaben.

Logge sichere und diagnostisch hilfreiche Fakten zum Start:

• Anwendungsversion oder Commit.
• Umgebungsname.
• Listening-Port.
• Aktivierte Feature-Namen ohne Secret-Werte.
• Datenbank-Host-Klasse, nicht das Passwort.
• Migrationsversion.
• Readiness des Health-Endpunkts.

Vorlage für die Incident-Zeitleiste

Dokumentiere:

1. Deployment-ID und Source-Commit.
2. Zeitstempel von Deployment-Start und Abschluss.
3. Erster ursächlicher Build- oder Runtime-Fehler.
4. Ergebnis des Health-Gates.
5. Recovery-Befehl und Deployment-ID.
6. Zeitraum der Auswirkungen auf Nutzer.
7. Verantwortlicher für die Nachbereitung.

Uptime-Daten liefern Verfügbarkeit und Antwortzeit auf Minutenebene:

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

Das Ergebnis enthält die durchschnittliche Antwortzeit und die p95-Antwortzeit. Kombiniere diese Daten mit Build- und Runtime-Logs, um einen Deployment-Incident von einer länger anhaltenden Performance-Regression zu unterscheiden.

Verwende die Dockup-CLI-Referenz für die aktuellen Log-Flags und Best Practices zur Sicherheit für sicheres Application Logging.

Logs mit der Deployment-Historie korrelieren

Eine Log-Zeile ist nur dann nützlich, wenn sie dem richtigen Release zugeordnet werden kann. Speichere Deployment-ID, Commit-Hash und Startzeit zusammen mit dem Log-Artefakt. Wenn zwei Releases kurz hintereinander erfolgen, können Zeitstempel allein irreführend sein.

dockup deployments production/api -n 20 --json

Die Deployment-Historie zeigt, welcher Quellcode aktiv war und welches Release einen finalen Status erreicht hat. Ein Agent sollte eine Runtime-Exception nicht dem neuesten Commit zuordnen, bevor der Service-Status bestätigt, dass dieser Commit tatsächlich deployt wurde.

Durch Logs verursachte Secret-Exponierung vermeiden

Eine fehlgeschlagene Verbindung verleitet oft dazu, die vollständige URL auszugeben. Logge stattdessen Protokoll, maskierten Host, Datenbanknamen und Fehlerkategorie. Bei Tokens solltest du nur einen sicheren Fingerabdruck loggen, der vor der Speicherung erzeugt wurde, sofern die Organisation dafür eine Richtlinie hat.

Prüfe Artefakte fehlgeschlagener Builds, bevor du sie außerhalb des Teams teilst. Ausgaben von Paketmanagern und Docker können private Repository-URLs, Registry-Benutzernamen oder Kommandoargumente enthalten, selbst wenn Dockup gespeicherte Environment-Secrets korrekt maskiert.

Dadurch sind Build- und Runtime-Logs sicher genug für eine gemeinsame Diagnose.

Ein minimales Beweispaket aufbewahren

Speichere für jedes fehlgeschlagene Release das JSON des Deployment-Ergebnisses, das Build-Log, den relevanten Runtime-Auszug, den Service-Status und die ID des ausgewählten Recovery-Deployments. Dieses Paket ist klein genug für den routinemäßigen Einsatz und vollständig genug, damit ein zweiter Operator ohne unsichere Änderungen erneut ausführen zu müssen, weitermachen kann.

Nicht nur den neuen Build, sondern die Behebung bestätigen

Nachdem das korrigierte Deployment erfolgreich war, wiederhole die fehlgeschlagene Anfrage oder die Startbedingung und beobachte die Runtime-Ausgabe auf ein erneutes Auftreten. Schließe den Incident erst, wenn das ursprüngliche Symptom verschwunden ist, das Health-Gate erfolgreich durchlaufen wurde und das erwartete Verhalten in der Produktion beobachtet wird.

Den Prozess abschließen

Dokumentiere die verifizierte Behebung.

Mit einem überprüfbaren Deployment beginnen

Lass testweise einen Build fehlschlagen, erfasse seinen NDJSON-Stream und Exit-Code und überprüfe anschließend, dass dein Runbook das Build-Log statt des Runtime-Logs auswählt.

Kostenlos auf app.dockup.ai starten. Der Free-Tarif kostet 0 $ pro Monat, enthält ein Startguthaben von 10 $ und unterstützt einen Workspace, drei Datenbanken und drei Deployments.

FAQ

Was ist der Unterschied zwischen Dockup-Build-Logs und Runtime-Logs?

Build-Logs umfassen das Klonen, die Installation von Abhängigkeiten, die Kompilierung und die Image-Erstellung. Runtime-Logs umfassen den gestarteten Anwendungscontainer oder die gestarteten Pods.

Wie kann ich Dockup-Build-Logs live verfolgen?

Verwende dockup logs mit --build und --follow oder -f. Mit --json gibt der Befehl NDJSON-Batches aus und endet beim finalen Status des Deployments.

Warum endet Build-Follow mit einem Wert ungleich null?

Der Deployment-Status wird beibehalten. Ein fehlgeschlagener Build muss die aufrufende Shell, den CI-Job oder die Agent-Aufgabe fehlschlagen lassen, statt wie ein erfolgreicher Log-Stream auszusehen.

Was bedeutet restarted:true in der Runtime-Follow-Ausgabe?

Dies zeigt an, dass der Container neu gestartet oder der vorgehaltene Puffer überschrieben wurde. Dockup hat daher den aktuellen Snapshot erneut ausgegeben, statt Zeilen stillschweigend zu verlieren.

Sollten Anwendungs-Logs Environment-Secrets enthalten?

Nein. Dockup maskiert das Auslesen gespeicherter Konfigurationen, kann aber beliebige von der Anwendung ausgegebene Secrets nicht automatisch sicher machen. Redigiere Zugangsdaten auf der Logging-Ebene der Anwendung.