Logs build και runtime: Εντοπισμός σφαλμάτων σε deployments του Dockup

Τα logs build και runtime απαντούν σε διαφορετικά ερωτήματα. Τα logs build εξηγούν πώς ο πηγαίος κώδικας μετατράπηκε σε image και γιατί απέτυχε αυτή η διαδικασία. Τα logs runtime εξηγούν τι έκανε η εφαρμογή μετά την εκκίνηση του container ή του workload στο Kubernetes.

Η ανάγνωση του λάθος stream σπαταλά χρόνο. Μια εξάρτηση που λείπει κατά τη δημιουργία του image δεν θα εμφανιστεί ποτέ στα logs runtime, ενώ ένα επιτυχημένο image που καταρρέει κατά την εκκίνηση μπορεί να έχει απολύτως καθαρό output στο build.

Ποια είναι η διαφορά μεταξύ logs build και runtime;

Χρησιμοποιήστε το στάδιο του deployment για να επιλέξετε το σωστό stream:

Στάδιο	Τυπική κατάσταση	Σωστό log	Συνήθεις αποτυχίες
Clone	cloning	Build	Πρόσβαση στο repository, branch
Εγκατάσταση dependencies	building	Build	Lockfile, registry, package
Compile/bundle	building	Build	Type errors, μνήμη, αρχεία που λείπουν
Εκκίνηση image	deploying	Runtime και health	Εντολή εκκίνησης, port, δικαιώματα
Υπηρεσία σε λειτουργία	running	Runtime	Exceptions, διακοπές dependencies
Readiness gate	deploying	Runtime και ρυθμίσεις health	Λάθος path, αργή εκκίνηση

Διαβάστε το πιο πρόσφατο output του build:

dockup logs production/api --build --json

Διαβάστε το output runtime από την υπηρεσία που εκτελείται:

dockup logs production/api --json

Ζητήστε περισσότερες γραμμές runtime όταν το σχετικό event είναι παλαιότερο:

dockup logs production/api -n 500 --json

Η απόκριση JSON προσδιορίζει το target και τον τύπο log, βοηθώντας ένα agent να μην ενώνει άσχετα streams.

Πώς λειτουργεί το dockup logs --build --follow;

Η λειτουργία follow μεταδίδει νέες γραμμές κάνοντας polling στο τρέχον snapshot:

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

Σε λειτουργία JSON, το output είναι NDJSON: ένα object ανά γραμμή και ανά batch. Ένας consumer μπορεί να επεξεργάζεται κάθε γραμμή σταδιακά.

Ένα τελικό batch σηματοδοτεί το τελικό αποτέλεσμα του build. Η εντολή τερματίζει αυτόματα όταν το deployment ολοκληρωθεί με επιτυχία ή αποτύχει και επιστρέφει non-zero exit code σε περίπτωση αποτυχίας. Αυτό την καθιστά κατάλληλη για agent ή CI job χωρίς χειροκίνητο status loop.

Το runtime follow λειτουργεί με παρόμοιο τρόπο:

dockup logs production/api -f --json

Κάθε batch περιλαμβάνει το restarted. Όταν είναι restarted:true, το container επανεκκινήθηκε ή έγινε rollover στο διατηρούμενο buffer logs, επομένως το Dockup εκπέμπει ξανά ολόκληρο το τρέχον snapshot αντί να απορρίψει σιωπηλά γραμμές.

Το προεπιλεγμένο διάστημα polling είναι 2 δευτερόλεπτα. Χρησιμοποιήστε το τεκμηριωμένο --interval μόνο όταν υπάρχει συγκεκριμένη ανάγκη αλλαγής της συχνότητας.

Πώς διαγιγνώσκετε ένα αποτυχημένο build;

Ξεκινήστε από το τελικό αποτέλεσμα του deployment:

dockup deploy production/api --wait --json

Όταν τερματίσει με deploy_failed, ανακτήστε το build log και εντοπίστε το πρώτο αιτιώδες σφάλμα, όχι το τελευταίο cascade message.

Μια χρήσιμη ακολουθία είναι:

1. Επιβεβαιώστε το target και το deployment ID.
2. Εντοπίστε το στάδιο clone, install, compile ή image.
3. Βρείτε το πρώτο σφάλμα που δεν μπορεί να αντιμετωπιστεί με retry.
4. Συγκρίνετε τη μέθοδο build με την πρόθεση του repository.
5. Αναπαραγάγετε το πρόβλημα από καθαρό clone, αν είναι εφικτό.
6. Κάντε μία στοχευμένη αλλαγή.
7. Κάντε redeploy με --wait.

Στις συνηθισμένες αποτυχίες του Nixpacks περιλαμβάνονται μη αναγνωρισμένο project root, lockfile που λείπει, απουσία συμβατικού start script ή απαίτηση για native package. Οι συνηθισμένες αποτυχίες σε Dockerfile περιλαμβάνουν λανθασμένο build context, artifact που δεν αντιγράφηκε, base image που δεν είναι διαθέσιμο ή αποτυχία σε εντολή RUN.

Ο οδηγός Nixpacks έναντι Dockerfile παρέχει έναν χάρτη αποφάσεων για τα build systems.

Αποφύγετε να διορθώσετε ένα ντετερμινιστικό σφάλμα build αυξάνοντας το timeout των 900 δευτερολέπτων. Η αλλαγή timeout βοηθά ένα νόμιμα μεγάλο build· δεν διορθώνει μια εντολή που τερμάτισε με σφάλμα.

Πώς διαγιγνώσκετε ένα crash runtime ή μια αποτυχία health;

Ένα επιτυχημένο image μπορεί και πάλι να αποτύχει πριν από τη μεταφορά της κίνησης. Ελέγξτε την κατάσταση της υπηρεσίας και το output runtime:

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

Αναζητήστε τα εξής:

• Η διεργασία τερματίζει αμέσως μετά την εκκίνηση.
• Η εφαρμογή κάνει bind στο λάθος port.
• Η εφαρμογή ακούει στο 127.0.0.1 αντί για όλες τις διεπαφές.
• Απουσιάζει απαιτούμενο environment key.
• Η σύνδεση με τη βάση δεδομένων ή το Redis αποτυγχάνει.
• Τα δικαιώματα αρχείων εμποδίζουν την εκκίνηση.
• Το health path επιστρέφει status που δεν δηλώνει επιτυχία.
• Η εκκίνηση διαρκεί περισσότερο από όσο επιτρέπουν τα ρυθμισμένα retries.
• Ένα migration αποτυγχάνει ή εκτελείται ταυτόχρονα με άλλο.

Μπορείτε να ελέγξετε ή να ενημερώσετε τη ρύθμιση health:

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

Μην αποδυναμώνετε το health gate απλώς για να περάσει ένα προβληματικό release. Αν η εκκίνηση χρειάζεται νόμιμα περισσότερο χρόνο, αλλάξτε την πολιτική βάσει στοιχείων και διατηρήστε ένα endpoint που εξακολουθεί να επιβεβαιώνει το readiness.

Οι αλλαγές στο environment απαιτούν redeployment. Αν διορθωθεί ένα secret που έλειπε, κάντε ξανά deploy και περιμένετε· η επανεκκίνηση του παλιού container δεν εφαρμόζει το νέο επιθυμητό environment.

Πώς πρέπει οι agents να αναλύουν NDJSON χωρίς να χάνουν το exit code;

Ένα agent ή script πρέπει να διαβάζει κάθε γραμμή JSON διατηρώντας ταυτόχρονα το status της διεργασίας. Αποφύγετε το piping σε εντολή που αποκρύπτει το αρχικό exit code χωρίς pipefail.

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

Με pipefail, μια αποτυχημένη εντολή του Dockup διατηρεί non-zero status σε ολόκληρο το pipeline, παρόλο που το tee ολοκληρώθηκε με επιτυχία.

Ένας consumer μπορεί να εξετάζει κάθε object ανεξάρτητα:

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

Διατηρήστε το αρχικό artifact NDJSON. Ένα ευανάγνωστο απόσπασμα είναι χρήσιμο για pull request ή incident, αλλά τα αρχικά fields διατηρούν τους restart markers, το status και τα completion signals.

Οι γενικές αρχές για machine interfaces εξηγούνται στο σχεδιασμό CLI για AI agents.

Ποιο είναι ένα επαναλήψιμο runbook για τον εντοπισμό σφαλμάτων σε deployments;

Χρησιμοποιήστε την εξής διαδρομή αποφάσεων:

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

Στη συνέχεια, ταξινομήστε το incident:

Ταξινόμηση	Στοιχεία	Επόμενη ενέργεια
Source/build	Σφάλμα στο build log	Διορθώστε το repository ή τον ορισμό build
Configuration	Environment ή port που λείπει/είναι λανθασμένο	Διορθώστε τη ρύθμιση και κάντε redeploy
Readiness	Η εφαρμογή εκτελείται, αλλά το health αποτυγχάνει	Διορθώστε το endpoint ή τον τεκμηριωμένο χρονισμό
Runtime dependency	Connection exception	Ελέγξτε database/network/credential
Regression	Η προηγούμενη έκδοση λειτουργούσε	Εξετάστε rollback με γνωστό ID
Platform uncertainty	Timeout, απουσία τελικής κατάστασης	Ελέγξτε το status πριν από retry

Κάντε rollback μόνο αφού εντοπίσετε ένα γνωστό προηγούμενο deployment:

dockup rollback <deploymentId> production/api --json

Διατηρήστε πρώτα το deployment ID και τα logs της αποτυχίας. Ένα rollback αποκαθιστά τη διαθεσιμότητα της υπηρεσίας· δεν εξηγεί τη βασική αιτία.

Το άρθρο deployments χωρίς downtime εξηγεί γιατί ένα αποτυχημένο readiness gate μπορεί να προστατεύσει την ενεργή κίνηση.

Πώς γίνονται χρήσιμα τα logs παραγωγής;

Το Dockup μπορεί να ανακτήσει output, αλλά η ποιότητα των logs ελέγχεται από την εφαρμογή. Προτιμήστε δομημένα records ενός event, με timestamps, severity, request ή trace IDs, όνομα component και ασφαλή περιγραφή σφάλματος.

Μην καταγράφετε access tokens, URLs βάσεων δεδομένων, passwords, πλήρη authorization headers ή προσωπικά δεδομένα που δεν είναι απαραίτητα για τη λειτουργία. Το secret masking στη ρύθμιση του Dockup δεν κάνει redact αυθαίρετο output της εφαρμογής.

Καταγράψτε ασφαλή και διαγνώσιμα στοιχεία εκκίνησης:

• Έκδοση εφαρμογής ή commit.
• Όνομα environment.
• Port στο οποίο ακούει η εφαρμογή.
• Ονόματα ενεργοποιημένων features χωρίς τιμές secrets.
• Κατηγορία host βάσης δεδομένων, όχι password.
• Έκδοση migration.
• Readiness του health endpoint.

Πρότυπο χρονολογίου incident

Καταγράψτε:

1. Deployment ID και source commit.
2. Timestamps έναρξης και τελικής κατάστασης του deploy.
3. Το πρώτο αιτιώδες σφάλμα build ή runtime.
4. Το αποτέλεσμα του health gate.
5. Την εντολή αποκατάστασης και το deployment ID.
6. Το χρονικό διάστημα επίδρασης στους χρήστες.
7. Τον υπεύθυνο για τις επόμενες ενέργειες.

Τα δεδομένα uptime προσθέτουν διαθεσιμότητα και χρόνο απόκρισης ανά λεπτό:

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

Το αποτέλεσμα περιλαμβάνει τον μέσο χρόνο απόκρισης και τον χρόνο απόκρισης p95. Συνδυάστε τα με τα logs build και runtime για να διακρίνετε ένα incident deployment από μια πιο μακροχρόνια υποβάθμιση απόδοσης.

Χρησιμοποιήστε το reference του Dockup CLI για τα τρέχοντα flags των logs και τις βέλτιστες πρακτικές ασφάλειας για ασφαλή καταγραφή από την εφαρμογή.

Συσχετίστε τα logs με το ιστορικό των deployments

Μια γραμμή είναι χρήσιμη μόνο όταν μπορεί να συνδεθεί με το σωστό release. Αποθηκεύστε το deployment ID, το commit hash και την ώρα έναρξης μαζί με το artifact των logs. Όταν δύο releases πραγματοποιούνται με μικρή χρονική απόσταση, τα timestamps από μόνα τους μπορεί να είναι παραπλανητικά.

dockup deployments production/api -n 20 --json

Το ιστορικό των deployments αποσαφηνίζει ποιο source ήταν ενεργό και ποιο release έφτασε σε τελική κατάσταση. Ένα agent δεν πρέπει να αποδίδει ένα exception runtime στο πιο πρόσφατο commit προτού το service state επιβεβαιώσει ότι το συγκεκριμένο commit έγινε πράγματι deploy.

Αποφύγετε την έκθεση secrets μέσω των logs

Μια αποτυχημένη σύνδεση συχνά ωθεί τους developers να εκτυπώσουν ολόκληρο το URL. Αντί γι’ αυτό, καταγράψτε το protocol, ένα masked host, το όνομα της βάσης δεδομένων και την κατηγορία του σφάλματος. Για tokens, καταγράψτε μόνο ένα ασφαλές fingerprint που δημιουργήθηκε πριν από την αποθήκευση, όταν ο οργανισμός διαθέτει σχετική πολιτική.

Ελέγξτε τα artifacts αποτυχημένων builds πριν τα μοιραστείτε εκτός της ομάδας. Το output των package managers και του Docker μπορεί να περιέχει URLs ιδιωτικών repositories, usernames registries ή arguments εντολών, ακόμη και όταν το Dockup κάνει σωστά mask τα αποθηκευμένα environment secrets.

Έτσι, τα logs build και runtime είναι αρκετά ασφαλή για συνεργατική διάγνωση.

Διατηρήστε ένα ελάχιστο πακέτο στοιχείων

Για κάθε αποτυχημένο release, αποθηκεύστε το JSON του αποτελέσματος deployment, το build log, το σχετικό απόσπασμα runtime, το service status και το deployment ID της επιλεγμένης αποκατάστασης. Αυτό το πακέτο είναι αρκετά μικρό για συστηματική χρήση και αρκετά πλήρες ώστε ένας δεύτερος operator να συνεχίσει χωρίς να επαναλάβει αβέβαιες μεταβολές.

Επιβεβαιώστε τη διόρθωση, όχι μόνο το νέο build

Αφού ολοκληρωθεί με επιτυχία το διορθωμένο deployment, επαναλάβετε το request ή τη συνθήκη εκκίνησης που προκαλούσε την αποτυχία και παρακολουθήστε το output runtime για τυχόν επανεμφάνιση. Κλείστε το incident μόνο όταν το αρχικό σύμπτωμα απουσιάζει, το health gate περνά και παρατηρείται η αναμενόμενη συμπεριφορά στην παραγωγή.

Ολοκληρώστε τον κύκλο

Καταγράψτε τη διορθωμένη λύση που επαληθεύτηκε.

Ξεκινήστε με ένα deployment που μπορεί να επαληθευτεί

Προκαλέστε σκόπιμα την αποτυχία ενός test build, αποθηκεύστε το NDJSON stream και το exit code του και στη συνέχεια επιβεβαιώστε ότι το runbook επιλέγει το build log αντί για το runtime log.

Ξεκινήστε δωρεάν στο app.dockup.ai. Το Free plan κοστίζει $0 τον μήνα, περιλαμβάνει αρχικό credit $10 και υποστηρίζει ένα workspace, τρεις βάσεις δεδομένων και τρία deployments.

FAQ

Ποια είναι η διαφορά μεταξύ των build logs και των runtime logs του Dockup;

Τα build logs καλύπτουν το cloning, την εγκατάσταση dependencies, το compilation και τη δημιουργία image. Τα runtime logs καλύπτουν το container ή τα pods της εφαρμογής που ξεκίνησε.

Πώς παρακολουθώ ζωντανά τα build logs του Dockup;

Χρησιμοποιήστε το dockup logs με --build και --follow ή με -f. Με --json, η εντολή εκπέμπει batches NDJSON και ολοκληρώνεται όταν το deployment φτάσει σε τελική κατάσταση.

Γιατί το build follow τερματίζει με non-zero exit code;

Διατηρεί το αποτέλεσμα του deployment. Ένα αποτυχημένο build πρέπει να αποτυγχάνει στο calling shell, στο CI job ή στο task του agent, αντί να εμφανίζεται ως επιτυχημένο stream logs.

Τι σημαίνει το restarted:true στο output του runtime follow;

Σημαίνει ότι το container επανεκκινήθηκε ή έγινε rollover στο διατηρούμενο buffer, επομένως το Dockup εξέπεμψε ξανά το τρέχον snapshot αντί να χάσει σιωπηλά γραμμές.

Πρέπει τα logs της εφαρμογής να περιέχουν environment secrets;

Όχι. Το Dockup κάνει mask στις αναγνώσεις αποθηκευμένων ρυθμίσεων, αλλά δεν μπορεί να κάνει ασφαλή αυθαίρετα secrets που εκτυπώνει η εφαρμογή. Κάντε redact των credentials στο επίπεδο καταγραφής της εφαρμογής.