Log di build e runtime: eseguire il debug dei deployment Dockup

I log di build e runtime rispondono a domande diverse. I log di build spiegano come il codice sorgente è diventato un'immagine e perché il processo non è riuscito. I log di runtime spiegano cosa ha fatto l'applicazione dopo l'avvio del container o del workload Kubernetes.

Leggere lo stream sbagliato fa perdere tempo. Una dipendenza mancante durante la costruzione dell'immagine non comparirà mai nei log di runtime, mentre un'immagine creata correttamente che va in crash all'avvio può avere un output di build perfettamente pulito.

Qual è la differenza tra log di build e log di runtime?

Usa la fase del deployment per scegliere lo stream:

Fase	Stato tipico	Log corretto	Errori comuni
Clonazione	cloning	Build	Accesso al repository, branch
Installazione delle dipendenze	building	Build	Lockfile, registry, package
Compilazione/bundle	building	Build	Errori di tipo, memoria, file mancanti
Avvio dell'immagine	deploying	Runtime e health	Comando di avvio, porta, permessi
Servizio in esecuzione	running	Runtime	Eccezioni, indisponibilità delle dipendenze
Controllo di readiness	deploying	Runtime più configurazione health	Path errato, avvio lento

Leggi l'ultimo output di build:

dockup logs production/api --build --json

Leggi l'output di runtime del servizio in esecuzione:

dockup logs production/api --json

Richiedi più righe di runtime quando l'evento rilevante è meno recente:

dockup logs production/api -n 500 --json

La risposta JSON identifica la destinazione e il tipo di log, aiutando un agent a evitare di unire stream non correlati.

Come funziona dockup logs --build --follow?

La modalità follow trasmette le nuove righe eseguendo il polling dello snapshot corrente:

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

In modalità JSON, l'output è NDJSON: un oggetto per riga e per batch. Un consumer può elaborare ogni riga in modo incrementale.

Un batch finale indica il risultato terminale della build. Il comando si interrompe automaticamente quando il deployment riesce o fallisce e restituisce un valore diverso da zero in caso di errore. Questo lo rende adatto a un agent o a un job CI senza dover scrivere un loop per controllare manualmente lo stato.

Il follow del runtime funziona in modo analogo:

dockup logs production/api -f --json

Ogni batch include restarted. Quando restarted:true, il container è stato riavviato oppure il buffer conservato è ricominciato da capo; Dockup emette quindi nuovamente l'intero snapshot corrente invece di eliminare le righe senza segnalarlo.

L'intervallo di polling predefinito è di 2 secondi. Usa --interval come documentato solo quando c'è una necessità specifica di modificare la frequenza.

Come si diagnostica una build fallita?

Inizia dal risultato terminale del deployment:

dockup deploy production/api --wait --json

Quando termina con deploy_failed, recupera il log di build e individua il primo errore causale, non l'ultimo messaggio a cascata.

Una sequenza utile è:

1. Conferma la destinazione e l'ID del deployment.
2. Identifica la fase di clonazione, installazione, compilazione o creazione dell'immagine.
3. Individua il primo errore non ripetibile.
4. Confronta il metodo di build con l'intento del repository.
5. Se possibile, riproduci il problema partendo da una clonazione pulita.
6. Apporta una singola modifica mirata.
7. Esegui nuovamente il deployment con --wait.

Tra gli errori comuni di Nixpacks ci sono una root del progetto non riconosciuta, un lockfile mancante, l'assenza di uno script di avvio convenzionale o la necessità di un package nativo. Gli errori comuni dei Dockerfile includono un contesto di build errato, un artefatto non copiato, un'immagine di base non disponibile o un'istruzione RUN che fallisce.

La guida Nixpacks vs Dockerfile fornisce una mappa decisionale per il sistema di build.

Evita di risolvere un errore di build deterministico aumentando il timeout di 900 secondi. Modificare il timeout aiuta una build legittimamente lunga; non corregge un comando terminato con un errore.

Come si diagnostica un crash del runtime o un errore di health?

Un'immagine creata correttamente può comunque fallire prima del passaggio del traffico. Controlla lo stato del servizio e l'output di runtime:

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

Cerca:

• Il processo termina subito dopo l'avvio.
• L'applicazione si collega alla porta sbagliata.
• L'applicazione è in ascolto su 127.0.0.1 invece che su tutte le interfacce.
• Manca una variabile d'ambiente necessaria.
• La connessione al database o a Redis fallisce.
• I permessi dei file impediscono l'avvio.
• Il path di health restituisce uno status non positivo.
• L'avvio richiede più tempo dei retry consentiti dalla configurazione.
• Una migration fallisce o viene eseguita contemporaneamente.

La configurazione health può essere consultata o aggiornata:

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

Non indebolire il controllo di health solo per far passare una release non funzionante. Se l'avvio richiede legittimamente più tempo, modifica la policy sulla base di dati concreti e mantieni un endpoint che dimostri comunque la readiness.

Le modifiche all'ambiente richiedono un nuovo deployment. Se risolvi il problema di un secret mancante, esegui nuovamente il deployment e attendi; riavviare il vecchio container non applica il nuovo ambiente desiderato.

Come devono analizzare gli agent gli NDJSON senza perdere l'exit code?

Un agent o uno script dovrebbe leggere ogni riga JSON preservando lo status del processo. Evita di eseguire il pipe verso un comando che nasconde l'exit originale senza pipefail.

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

Con pipefail, un comando Dockup fallito mantiene il valore diverso da zero dell'intera pipeline anche se tee termina correttamente.

Un consumer può esaminare ogni oggetto in modo indipendente:

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

Conserva l'artefatto NDJSON originale. Un estratto leggibile è utile per una pull request o un incidente, ma i campi originali preservano i marker di riavvio, lo status e i segnali di completamento.

I principi generali delle interfacce per macchine sono spiegati in AI agent CLI design.

Qual è un runbook ripetibile per il debugging dei deployment?

Segui questo percorso decisionale:

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

Quindi classifica l'incidente:

Classificazione	Evidenza	Azione successiva
Sorgente/build	Errore nel log di build	Correggi il repository o la definizione della build
Configurazione	Variabile d'ambiente o porta mancante/errata	Correggi la configurazione ed esegui nuovamente il deployment
Readiness	L'applicazione è in esecuzione, ma l'health fallisce	Correggi l'endpoint o modifica i tempi se giustificato
Dipendenza di runtime	Eccezione di connessione	Controlla database/rete/credenziali
Regressione	La versione precedente funzionava	Valuta un rollback tramite ID noto
Incertezza della piattaforma	Timeout, nessuno stato terminale	Controlla lo stato prima di riprovare

Esegui il rollback solo dopo aver identificato un deployment precedente noto:

dockup rollback <deploymentId> production/api --json

Conserva prima l'ID e i log del deployment fallito. Un rollback ripristina la disponibilità del servizio; non spiega la causa principale.

L'articolo sui deployment zero-downtime spiega perché un controllo di readiness fallito può proteggere il traffico live.

Come si rendono utili i log di produzione?

Dockup può recuperare l'output, ma la qualità dei log dipende dall'applicazione. Preferisci record strutturati, con un singolo evento per record, che includano timestamp, gravità, ID della richiesta o della trace, nome del componente e una descrizione sicura dell'errore.

Non registrare mai access token, URL del database, password, header di autorizzazione completi o dati personali non necessari per le attività operative. Il masking dei secret nella configurazione Dockup non esegue il redacting di un output arbitrario dell'applicazione.

Registra informazioni di avvio sicure e utili per la diagnosi:

• Versione dell'applicazione o commit.
• Nome dell'ambiente.
• Porta in ascolto.
• Nomi delle feature abilitate, senza valori segreti.
• Classe dell'host del database, non la password.
• Versione della migration.
• Readiness dell'endpoint di health.

Modello di timeline dell'incidente

Registra:

1. ID del deployment e commit sorgente.
2. Timestamp di inizio del deploy e di raggiungimento dello stato terminale.
3. Primo errore causale di build o runtime.
4. Risultato del controllo di health.
5. Comando di ripristino e ID del deployment.
6. Intervallo di impatto sugli utenti.
7. Responsabile del follow-up.

I dati di uptime aggiungono disponibilità e tempo di risposta con granularità al minuto:

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

Il risultato include il tempo di risposta medio e p95. Combinalo con i log di build e runtime per distinguere un incidente di deployment da una regressione delle prestazioni più lunga.

Usa il riferimento della CLI Dockup per i flag dei log aggiornati e le best practice di sicurezza per registrare in sicurezza i log dell'applicazione.

Correlare i log con la cronologia dei deployment

Una riga è utile solo quando può essere associata alla release corretta. Conserva l'ID del deployment, l'hash del commit e l'ora di avvio insieme all'artefatto di log. Quando due release vengono eseguite a breve distanza, i soli timestamp possono trarre in inganno.

dockup deployments production/api -n 20 --json

La cronologia dei deployment stabilisce quale sorgente era attiva e quale release ha raggiunto uno stato terminale. Un agent non dovrebbe attribuire un'eccezione di runtime all'ultimo commit finché lo stato del servizio non conferma che quel commit è stato effettivamente distribuito.

Evitare l'esposizione di secret nei log

Un errore di connessione spesso induce gli sviluppatori a stampare l'URL completo. Registra invece il protocollo, l'host mascherato, il nome del database e la categoria dell'errore. Per i token, registra solo un fingerprint sicuro generato prima dell'archiviazione, quando l'organizzazione dispone di una policy in merito.

Controlla gli artefatti delle build fallite prima di condividerli al di fuori del team. L'output dei package manager e di Docker può contenere URL di repository privati, username dei registry o argomenti dei comandi anche quando Dockup maschera correttamente i secret d'ambiente archiviati.

In questo modo i log di build e runtime sono abbastanza sicuri per una diagnosi collaborativa.

Conservare un pacchetto minimo di evidenze

Per ogni release fallita, salva il JSON del risultato del deployment, il log di build, l'estratto di runtime rilevante, lo stato del servizio e l'ID del deployment di ripristino selezionato. Questo pacchetto è abbastanza piccolo per l'uso quotidiano e abbastanza completo da consentire a un secondo operatore di proseguire senza ripetere mutazioni incerte.

Confermare la correzione, non solo la nuova build

Dopo che il deployment corretto è riuscito, ripeti la richiesta o la condizione di avvio che causava il problema e osserva l'output di runtime per verificare che non si ripresenti. Chiudi l'incidente solo quando il sintomo originale è assente, il controllo di health è superato e il comportamento atteso in produzione è stato osservato.

Chiudere il ciclo

Documenta la correzione verificata.

Inizia con un deployment verificabile

Fai fallire intenzionalmente una build di test, acquisisci il suo stream NDJSON e l'exit code, quindi verifica che il runbook selezioni il log di build invece di quello di runtime.

Inizia gratuitamente su app.dockup.ai. Il piano Free costa $0 al mese, include $10 di credito iniziale e supporta un workspace, tre database e tre deployment.

FAQ

Qual è la differenza tra i log di build e i log di runtime di Dockup?

I log di build coprono la clonazione, l'installazione delle dipendenze, la compilazione e la creazione dell'immagine. I log di runtime coprono il container dell'applicazione o i pod avviati.

Come posso seguire in tempo reale i log di build di Dockup?

Usa dockup logs con --build e --follow, oppure -f. Con --json, il comando emette batch NDJSON e termina quando il deployment raggiunge lo stato terminale.

Perché il follow della build termina con un valore diverso da zero?

Preserva il risultato del deployment. Una build fallita deve far fallire la shell chiamante, il job CI o l'attività dell'agent, invece di apparire come uno stream di log riuscito.

Cosa significa restarted:true nell'output del follow del runtime?

Indica che il container è stato riavviato oppure che il buffer conservato è ricominciato da capo; Dockup ha quindi emesso nuovamente lo snapshot corrente invece di perdere le righe senza segnalarlo.

I log dell'applicazione devono contenere i secret dell'ambiente?

No. Dockup maschera le letture della configurazione archiviata, ma non può rendere sicuri secret arbitrari stampati dall'applicazione. Esegui il redacting delle credenziali a livello del logging dell'applicazione.