Logs de build y runtime: depura despliegues de Dockup

Los logs de build y runtime responden a preguntas distintas. Los logs de build explican cómo el código fuente se convirtió en una imagen y por qué falló ese proceso. Los logs de runtime explican qué hizo la aplicación compilada después de iniciar el contenedor o la carga de trabajo de Kubernetes.

Leer el stream equivocado hace perder tiempo. Una dependencia ausente durante la construcción de la imagen nunca aparecerá en los logs de runtime, mientras que una imagen correcta que se bloquea al iniciar puede tener una salida de build completamente limpia.

¿Cuál es la diferencia entre los logs de build y los de runtime?

Usa la fase del despliegue para elegir el stream:

Fase	Estado habitual	Log correcto	Fallos habituales
Clonado	cloning	Build	Acceso al repositorio, rama
Instalación de dependencias	building	Build	Lockfile, registry, paquete
Compilación/bundle	building	Build	Errores de tipos, memoria, archivos ausentes
Inicio de la imagen	deploying	Runtime y health	Comando de inicio, puerto, permisos
Servicio en ejecución	running	Runtime	Excepciones, interrupciones de dependencias
Comprobación de readiness	deploying	Runtime y configuración de health	Ruta incorrecta, inicio lento

Lee la salida de build más reciente:

dockup logs production/api --build --json

Lee la salida de runtime del servicio en ejecución:

dockup logs production/api --json

Solicita más líneas de runtime cuando el evento relevante sea más antiguo:

dockup logs production/api -n 500 --json

La respuesta JSON identifica el destino y el tipo de log, lo que ayuda a un agente a evitar la combinación de streams no relacionados.

¿Cómo funciona dockup logs --build --follow?

El modo follow transmite las líneas nuevas mediante consultas periódicas de la instantánea actual:

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

En modo JSON, la salida es NDJSON: un objeto por línea y por lote. Un consumidor puede procesar cada línea de forma incremental.

Un lote final marca el resultado terminal del build. El comando se detiene automáticamente cuando el despliegue tiene éxito o falla, y devuelve un código distinto de cero en caso de error. Esto lo hace adecuado para un agente o un job de CI sin necesidad de escribir un bucle de comprobación de estado.

El follow de runtime funciona de forma similar:

dockup logs production/api -f --json

Cada lote incluye restarted. Cuando restarted:true, el contenedor se ha reiniciado o el buffer de logs conservado ha rotado, por lo que Dockup vuelve a emitir la instantánea completa actual en lugar de descartar líneas silenciosamente.

El intervalo de consulta predeterminado es de 2 segundos. Usa --interval, tal como se documenta, solo cuando haya una necesidad concreta de cambiar la frecuencia.

¿Cómo se diagnostica un build fallido?

Empieza por el resultado terminal del despliegue:

dockup deploy production/api --wait --json

Cuando termina con deploy_failed, recupera el build log y busca el primer error causal, no el último mensaje en cascada.

Una secuencia útil es:

1. Confirma el destino y el ID del despliegue.
2. Identifica la fase de clonado, instalación, compilación o imagen.
3. Busca el primer error que no sea reintentable.
4. Compara el método de build con la intención del repositorio.
5. Reproduce el problema desde un clonado limpio si es posible.
6. Haz un único cambio específico.
7. Vuelve a desplegar con --wait.

Entre los fallos habituales de Nixpacks se incluyen una raíz de proyecto no reconocida, la ausencia de un lockfile, la falta de un script de inicio convencional o la necesidad de un paquete nativo. Entre los fallos habituales de Dockerfile se incluyen un contexto de build incorrecto, la ausencia de un artefacto copiado, una imagen base no disponible o una instrucción RUN fallida.

La guía Nixpacks vs Dockerfile ofrece un mapa de decisión para elegir el sistema de build.

Evita solucionar un error de build determinista aumentando el timeout de 900 segundos. Cambiar el timeout ayuda cuando el build legítimamente tarda mucho; no corrige un comando que terminó con un error.

¿Cómo se diagnostica un crash de runtime o un fallo de health?

Una imagen correcta aún puede fallar antes de pasar el tráfico. Inspecciona el estado del servicio y la salida de runtime:

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

Busca lo siguiente:

• El proceso termina inmediatamente después de iniciarse.
• La aplicación se enlaza al puerto incorrecto.
• La aplicación escucha en 127.0.0.1 en lugar de hacerlo en todas las interfaces.
• Falta una variable de entorno necesaria.
• Falla la conexión con la base de datos o Redis.
• Los permisos de archivos impiden el inicio.
• La ruta de health devuelve un estado que no indica éxito.
• El inicio tarda más de lo que permiten los reintentos configurados.
• Una migración falla o se ejecuta simultáneamente.

La configuración de health se puede consultar o actualizar:

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

No debilites la barrera de health solo para hacer pasar un release defectuoso. Si el inicio necesita legítimamente más tiempo, cambia la política basándote en evidencias y conserva un endpoint que siga demostrando la readiness.

Los cambios de entorno requieren volver a desplegar. Si corriges un secret ausente, vuelve a desplegar y espera; reiniciar el contenedor antiguo no aplica el nuevo entorno deseado.

¿Cómo deben analizar los agentes NDJSON sin perder el código de salida?

Un agente o script debe leer cada línea JSON y conservar el estado del proceso. Evita canalizar la salida a un comando que oculte el código de salida original sin pipefail.

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

Con pipefail, un comando de Dockup fallido mantiene el pipeline en estado distinto de cero aunque tee termine correctamente.

Un consumidor puede inspeccionar cada objeto de forma independiente:

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

Conserva el artefacto NDJSON sin modificar. Un extracto legible para humanos resulta útil para un pull request o un incidente, pero los campos originales conservan los marcadores de reinicio, el estado y las señales de finalización.

Los principios generales de las interfaces para máquinas se explican en diseño de CLI para agentes de IA.

¿Cuál es un runbook repetible para depurar despliegues?

Usa esta ruta de decisión:

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

Después, clasifica el incidente:

Clasificación	Evidencia	Siguiente acción
Código fuente/build	Error en el build log	Corrige el repositorio o la definición del build
Configuración	Variable de entorno o puerto ausente/incorrecto	Corrige la configuración y vuelve a desplegar
Readiness	La aplicación funciona, pero health falla	Corrige el endpoint o el tiempo de forma justificada
Dependencia de runtime	Excepción de conexión	Comprueba la base de datos, la red y las credenciales
Regresión	La versión anterior funcionaba	Considera un rollback mediante un ID conocido
Incertidumbre de plataforma	Timeout, sin estado terminal	Inspecciona el estado antes de reintentar

Haz rollback solo después de identificar un despliegue anterior conocido:

dockup rollback <deploymentId> production/api --json

Conserva primero el ID del despliegue fallido y los logs. Un rollback restaura la disponibilidad del servicio; no explica la causa raíz.

El artículo sobre despliegues sin downtime explica por qué una barrera de readiness fallida puede proteger el tráfico activo.

¿Cómo se pueden hacer útiles los logs de producción?

Dockup puede recuperar la salida, pero la aplicación controla la calidad de los logs. Prefiere registros estructurados de un único evento con marcas de tiempo, severity, IDs de request o trace, nombre del componente y una descripción segura del error.

No registres nunca access tokens, URLs de bases de datos, contraseñas, headers de autorización completos ni datos personales que no sean necesarios para las operaciones. El enmascaramiento de secrets en la configuración de Dockup no redacta una salida arbitraria de la aplicación.

Registra datos de inicio que sean seguros y permitan diagnosticar problemas:

• Versión de la aplicación o commit.
• Nombre del entorno.
• Puerto de escucha.
• Nombres de las features activadas, sin valores secretos.
• Clase de host de la base de datos, no la contraseña.
• Versión de la migración.
• Readiness del endpoint de health.

Plantilla de línea de tiempo de un incidente

Registra:

1. ID del despliegue y commit de origen.
2. Marcas de tiempo de inicio y finalización del despliegue.
3. Primer error causal de build o runtime.
4. Resultado de la barrera de health.
5. Comando de recuperación e ID del despliegue.
6. Intervalo de impacto para los usuarios.
7. Responsable del seguimiento.

Los datos de uptime añaden disponibilidad y tiempo de respuesta con precisión de un minuto:

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

El resultado incluye el tiempo de respuesta medio y p95. Combínalo con los logs de build y runtime para distinguir un incidente de despliegue de una regresión de rendimiento más prolongada.

Consulta la referencia de Dockup CLI para conocer los flags actuales de logs y las buenas prácticas de seguridad para registrar eventos de aplicación de forma segura.

Correlaciona los logs con el historial de despliegues

Una línea solo resulta útil cuando se puede asociar al release correcto. Guarda el ID del despliegue, el hash del commit y la hora de inicio junto al artefacto de logs. Cuando se producen dos releases con poca diferencia, las marcas de tiempo por sí solas pueden inducir a error.

dockup deployments production/api -n 20 --json

El historial de despliegues establece qué código fuente estaba activo y qué release alcanzó un estado terminal. Un agente no debe atribuir una excepción de runtime al commit más reciente hasta que el estado del servicio confirme que ese commit se desplegó realmente.

Evita exponer secrets a través de los logs

Un fallo de conexión suele tentar a los desarrolladores a imprimir la URL completa. En su lugar, registra el protocolo, el host enmascarado, el nombre de la base de datos y la categoría del error. En el caso de los tokens, registra únicamente una huella segura generada antes del almacenamiento cuando la organización tenga una política para ello.

Revisa los artefactos de builds fallidos antes de compartirlos fuera del equipo. La salida de los gestores de paquetes y de Docker puede contener URLs de repositorios privados, nombres de usuario de registries o argumentos de comandos, incluso cuando Dockup enmascara correctamente los secrets de entorno almacenados.

Esto hace que los logs de build y runtime sean lo bastante seguros para el diagnóstico colaborativo.

Conserva un paquete mínimo de evidencias

Para cada release fallido, guarda el JSON del resultado del despliegue, el build log, el extracto de runtime relevante, el estado del servicio y el ID del despliegue de recuperación seleccionado. Este paquete es suficientemente pequeño para el uso habitual y suficientemente completo para que otro operador pueda continuar sin volver a ejecutar mutaciones inciertas.

Confirma la solución, no solo el nuevo build

Después de que el despliegue corregido termine correctamente, repite la request fallida o la condición de inicio y observa la salida de runtime para comprobar si vuelve a aparecer. Cierra el incidente solo cuando el síntoma original haya desaparecido, la barrera de health se supere y se observe el comportamiento esperado en producción.

Cierra el ciclo

Documenta la solución verificada.

Empieza con un despliegue verificable

Fuerza un build de prueba a fallar, captura su stream NDJSON y su código de salida, y verifica que tu runbook seleccione el build log en lugar del runtime log.

Empieza gratis en app.dockup.ai. El plan Free cuesta 0 $ al mes, incluye un crédito inicial de 10 $ y admite un workspace, tres bases de datos y tres despliegues.

Preguntas frecuentes

¿Cuál es la diferencia entre los logs de build de Dockup y los logs de runtime?

Los logs de build abarcan el clonado, la instalación de dependencias, la compilación y la creación de la imagen. Los logs de runtime abarcan el contenedor de la aplicación o los pods ya iniciados.

¿Cómo puedo seguir en directo los logs de build de Dockup?

Usa dockup logs con --build y --follow, o -f. Con --json, el comando emite lotes NDJSON y termina cuando el despliegue alcanza un estado terminal.

¿Por qué el follow del build termina con un código distinto de cero?

Conserva el resultado del despliegue. Un build fallido debe hacer fallar al shell, job de CI o tarea del agente que lo invoca, en lugar de parecer un stream de logs correcto.

¿Qué significa restarted:true en la salida del follow de runtime?

Indica que el contenedor se reinició o que el buffer conservado rotó, por lo que Dockup volvió a emitir la instantánea actual en lugar de perder líneas silenciosamente.

¿Los logs de la aplicación deben contener secrets de entorno?

No. Dockup enmascara las lecturas de la configuración almacenada, pero no puede hacer seguros los secrets arbitrarios que imprime la aplicación. Redacta las credenciales en la capa de logging de la aplicación.