Logs de build e runtime: depuração de deployments no Dockup

Os logs de build e runtime respondem a perguntas diferentes. Os logs de build explicam como o código-fonte se tornou uma imagem e por que esse processo falhou. Os logs de runtime explicam o que a aplicação criada fez depois que o container ou workload do Kubernetes foi iniciado.

Ler o stream errado desperdiça tempo. Uma dependência ausente durante a construção da imagem nunca aparecerá nos logs de runtime, enquanto uma imagem criada com sucesso que falha na inicialização pode ter uma saída de build perfeitamente limpa.

Qual é a diferença entre logs de build e runtime?

Use a etapa do deployment para escolher o stream:

Etapa	Status típico	Log correto	Falhas comuns
Clone	cloning	Build	Acesso ao repositório, branch
Instalação de dependências	building	Build	Lockfile, registry, pacote
Compilação/bundle	building	Build	Erros de tipo, memória, arquivos ausentes
Inicialização da imagem	deploying	Runtime e health	Comando de inicialização, porta, permissões
Serviço em execução	running	Runtime	Exceções, indisponibilidade de dependências
Verificação de readiness	deploying	Runtime e configuração de health	Path incorreto, inicialização lenta

Leia a saída de build mais recente:

dockup logs production/api --build --json

Leia a saída de runtime do serviço em execução:

dockup logs production/api --json

Solicite mais linhas de runtime quando o evento relevante for mais antigo:

dockup logs production/api -n 500 --json

A resposta JSON identifica o alvo e o tipo de log, ajudando um agente a não misturar streams não relacionados.

Como funciona o dockup logs --build --follow?

O modo follow transmite novas linhas fazendo polling do snapshot atual:

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

No modo JSON, a saída é NDJSON: um objeto por linha e por batch. Um consumidor pode processar cada linha incrementalmente.

Um batch final indica o resultado terminal do build. O comando para sozinho quando o deployment é concluído com sucesso ou falha e retorna um código diferente de zero em caso de falha. Isso o torna adequado para um agente ou job de CI sem um loop de status escrito manualmente.

O follow de runtime funciona de forma semelhante:

dockup logs production/api -f --json

Cada batch inclui restarted. Quando restarted:true, o container foi reiniciado ou o buffer de logs retido foi rotacionado; por isso, o Dockup reenvia o snapshot atual completo em vez de descartar linhas silenciosamente.

O intervalo padrão de polling é de 2 segundos. Use --interval, conforme documentado, somente quando houver uma necessidade específica de alterar a cadência.

Como diagnosticar um build com falha?

Comece pelo resultado terminal do deployment:

dockup deploy production/api --wait --json

Quando ele terminar com deploy_failed, recupere o log de build e encontre o primeiro erro causal, não a última mensagem em cascata.

Uma sequência útil é:

1. Confirme o alvo e o ID do deployment.
2. Identifique a etapa de clone, instalação, compilação ou imagem.
3. Encontre o primeiro erro que não seja passível de retry.
4. Compare o método de build com a intenção do repositório.
5. Reproduza a partir de um clone limpo, se possível.
6. Faça uma única alteração focada.
7. Faça o redeploy com --wait.

Falhas comuns do Nixpacks incluem uma raiz de projeto não reconhecida, lockfile ausente, script de inicialização convencional inexistente ou necessidade de um pacote nativo. Falhas comuns de Dockerfile incluem um contexto de build incorreto, artefato não copiado, imagem base indisponível ou instrução RUN com falha.

O guia Nixpacks vs Dockerfile apresenta um mapa de decisão dos sistemas de build.

Evite corrigir um erro determinístico de build aumentando o timeout de 900 segundos. Alterar o timeout ajuda quando o build é legitimamente demorado; isso não corrige um comando que terminou com erro.

Como diagnosticar um crash de runtime ou uma falha de health?

Uma imagem criada com sucesso ainda pode falhar antes da mudança do tráfego. Inspecione o estado do serviço e a saída de runtime:

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

Procure por:

• O processo termina imediatamente após a inicialização.
• A aplicação usa a porta errada.
• A aplicação escuta em 127.0.0.1 em vez de todas as interfaces.
• Uma variável de ambiente obrigatória está ausente.
• A conexão com o banco de dados ou o Redis falha.
• As permissões de arquivo impedem a inicialização.
• O path de health retorna um status diferente de sucesso.
• A inicialização demora mais do que o número de retries configurado permite.
• Uma migration falha ou é executada em paralelo.

A configuração de health pode ser consultada ou atualizada:

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

Não enfraqueça a verificação de health apenas para fazer uma release com problemas passar. Se a inicialização realmente precisar de mais tempo, altere a política com base em evidências e mantenha um endpoint que continue comprovando a readiness.

Alterações de ambiente exigem um novo deployment. Se um secret ausente for corrigido, faça o deploy novamente e aguarde; reiniciar o container antigo não aplica o novo ambiente desejado.

Como os agentes devem analisar NDJSON sem perder o código de saída?

Um agente ou script deve ler cada linha JSON preservando o status do processo. Evite fazer pipe para um comando que mascare o código de saída original sem pipefail.

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

Com pipefail, um comando do Dockup que falhar mantém o pipeline com status diferente de zero, mesmo que o tee seja concluído com sucesso.

Um consumidor pode inspecionar cada objeto de forma independente:

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

Mantenha o artefato NDJSON bruto. Um trecho legível por humanos é útil para um pull request ou incidente, mas os campos originais preservam marcadores de restart, status e sinais de conclusão.

Os princípios gerais de interfaces para máquinas são explicados em design de CLI para agentes de IA.

Qual é um runbook repetível para depuração de deployments?

Use este caminho de decisão:

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

Em seguida, classifique o incidente:

Classificação	Evidência	Próxima ação
Código-fonte/build	Erro no log de build	Corrigir o repositório ou a definição de build
Configuração	Variável de ambiente ou porta ausente/incorreta	Corrigir a configuração e fazer redeploy
Readiness	A aplicação executa, mas o health falha	Corrigir o endpoint ou ajustar o tempo com justificativa
Dependência de runtime	Exceção de conexão	Verificar banco de dados/rede/credencial
Regressão	A versão anterior funcionava	Considerar rollback pelo ID conhecido
Incerteza da plataforma	Timeout, sem estado terminal	Inspecionar o status antes de tentar novamente

Faça rollback somente depois de identificar um deployment anterior conhecido:

dockup rollback <deploymentId> production/api --json

Preserve primeiro o ID do deployment com falha e os logs. Um rollback restaura a disponibilidade do serviço; ele não explica a causa raiz.

O artigo sobre deployments sem downtime explica por que uma verificação de readiness com falha pode proteger o tráfego ativo.

Como tornar os logs de produção úteis?

O Dockup pode recuperar a saída, mas a aplicação controla a qualidade dos logs. Prefira registros estruturados de evento único com timestamps, severidade, IDs de requisição ou trace, nome do componente e uma descrição segura do erro.

Nunca registre tokens de acesso, URLs de banco de dados, senhas, headers de autorização completos ou dados pessoais que não sejam necessários para as operações. O mascaramento de secrets na configuração do Dockup não redige automaticamente qualquer saída da aplicação.

Registre fatos de inicialização que sejam seguros e úteis para diagnóstico:

• Versão da aplicação ou commit.
• Nome do ambiente.
• Porta de escuta.
• Nomes das features habilitadas, sem valores secretos.
• Classe do host do banco de dados, não a senha.
• Versão da migration.
• Readiness do endpoint de health.

Template de linha do tempo do incidente

Registre:

1. ID do deployment e commit de origem.
2. Timestamps de início e término do deployment.
3. Primeiro erro causal de build ou runtime.
4. Resultado da verificação de health.
5. Comando de recuperação e ID do deployment.
6. Período de impacto para os usuários.
7. Responsável pelo acompanhamento.

Os dados de uptime acrescentam disponibilidade e tempo de resposta em nível de minuto:

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

O resultado inclui o tempo médio e o tempo de resposta p95. Combine-o com logs de build e runtime para diferenciar um incidente de deployment de uma regressão de performance mais prolongada.

Consulte a referência da CLI do Dockup para conhecer as flags de log atuais e as boas práticas de segurança para registrar logs da aplicação com segurança.

Correlacione os logs com o histórico de deployments

Uma linha só é útil quando pode ser associada à release correta. Armazene o ID do deployment, o hash do commit e o horário de início junto ao artefato de log. Quando duas releases acontecem próximas uma da outra, os timestamps sozinhos podem induzir ao erro.

dockup deployments production/api -n 20 --json

O histórico de deployments estabelece qual código-fonte estava ativo e qual release alcançou um estado terminal. Um agente não deve atribuir uma exceção de runtime ao commit mais recente antes que o estado do serviço confirme que esse commit foi realmente deployed.

Evite a exposição de secrets por meio dos logs

Uma conexão com falha frequentemente leva os desenvolvedores a imprimir a URL completa. Em vez disso, registre o protocolo, o host mascarado, o nome do banco de dados e a categoria do erro. Para tokens, registre apenas uma fingerprint segura gerada antes do armazenamento, quando a organização tiver uma política para isso.

Revise os artefatos de builds com falha antes de compartilhá-los fora da equipe. A saída de package managers e Docker pode conter URLs de repositórios privados, nomes de usuário de registries ou argumentos de comandos, mesmo quando o Dockup mascara corretamente os secrets de ambiente armazenados.

Isso torna os logs de build e runtime seguros o suficiente para um diagnóstico colaborativo.

Preserve um pacote mínimo de evidências

Para cada release com falha, salve o JSON do resultado do deployment, o log de build, o trecho de runtime relevante, o status do serviço e o ID do deployment de recuperação selecionado. Esse pacote é pequeno o suficiente para o uso rotineiro e completo o suficiente para que outro operador continue o trabalho sem repetir mutações incertas.

Confirme a correção, não apenas o novo build

Depois que o deployment corrigido for concluído com sucesso, repita a requisição ou a condição de inicialização que causava a falha e observe a saída de runtime para verificar se o problema voltou. Encerre o incidente somente quando o sintoma original estiver ausente, a verificação de health passar e o comportamento esperado em produção for observado.

Feche o ciclo

Documente a correção verificada.

Comece com um deployment verificável

Force um build de teste a falhar, capture o stream NDJSON e o código de saída e, em seguida, verifique se o runbook seleciona o log de build em vez do log de runtime.

Comece gratuitamente em app.dockup.ai. O plano Free custa US$ 0 por mês, inclui US$ 10 em crédito inicial e oferece suporte a um workspace, três bancos de dados e três deployments.

FAQ

Qual é a diferença entre os logs de build e runtime do Dockup?

Os logs de build abrangem clone, instalação de dependências, compilação e criação da imagem. Os logs de runtime abrangem o container da aplicação ou os pods já iniciados.

Como acompanho os logs de build do Dockup em tempo real?

Use dockup logs com --build e --follow, ou -f. Com --json, o comando emite batches NDJSON e termina quando o deployment alcança um estado terminal.

Por que o build follow retorna um código diferente de zero?

Ele preserva o resultado do deployment. Um build com falha deve fazer o shell, job de CI ou tarefa do agente chamador falhar, em vez de parecer um stream de logs concluído com sucesso.

O que significa restarted:true na saída do runtime follow?

Isso indica que o container foi reiniciado ou que o buffer retido foi rotacionado; por isso, o Dockup emitiu novamente o snapshot atual em vez de perder linhas silenciosamente.

Os logs da aplicação devem conter secrets de ambiente?

Não. O Dockup mascara leituras da configuração armazenada, mas não consegue tornar seguros secrets arbitrários impressos pela aplicação. Redija as credenciais na camada de logging da aplicação.