Cómo depurar contenedores de Docker en Debian 13

Introducción

En este tutorial, aprenderás a depurar contenedores Docker utilizando técnicas prácticas y amigables para principiantes. Identificarás problemas verificando el estado del contenedor, analizando registros, inspeccionando la configuración y accediendo al entorno del contenedor. Este enfoque te ayuda a comprender rápidamente por qué falla un contenedor y cómo solucionarlo.

Objetivo final: Al final de este tutorial, podrás identificar y solucionar problemas comunes de contenedores Docker utilizando registros, inspección y herramientas de análisis en tiempo de ejecución.

Requisitos previos

• Público objetivo: Administradores de sistemas principiantes
• Tiempo estimado: ~30 minutos
• Sistema operativo: Debian 13
• Software: Docker 24.0 o posterior
• Permisos: Usuario con privilegios de sudo o miembro del grupo docker
• Requisitos de hardware: Al menos 2 GB de RAM y 10 GB de espacio libre en disco
• Requisitos de red: Acceso a Internet para descargar imágenes, no se requieren puertos específicos para este tutorial
• Requisitos: Uso básico de la línea de comandos y un servicio Docker en ejecución
• Compatibilidad: Probado en Debian 13 y funciona en Debian 12 y Ubuntu 22.04

Paso 1: Verificar la Información del Sistema Docker

Antes de depurar un contenedor específico, verifica que Docker en sí esté funcionando correctamente.
Ejecuta el siguiente comando:

docker system info

Verás información detallada sobre el entorno Docker, incluyendo:

• Versión del servidor
• Controlador de almacenamiento
• Número de contenedores e imágenes
• Disponibilidad de CPU y memoria
• Directorio raíz de Docker

Esto te ayuda a confirmar que:

• Docker está funcionando correctamente
• El sistema tiene suficientes recursos
• No hay problemas de configuración global

Para verificar el estado del servicio Docker:

systemctl status docker

Verás si el servicio Docker está activo. Si no está funcionando, inícialo:

sudo systemctl start docker

Ahora deberías ver el servicio en estado activo.

Paso 2: Verificar el Estado del Contenedor

Ejecuta el siguiente comando:

docker ps

Verás una lista de contenedores en ejecución con detalles como ID del contenedor, imagen y estado. Si tu contenedor aparece con el estado "Up", está actualmente en ejecución.

Para incluir contenedores detenidos:

docker ps -a

Ahora verás todos los contenedores. Si tu contenedor muestra "Exited", significa que se ha detenido debido a un error o ha completado su ejecución.

Paso 3: Ver los Registros del Contenedor

Los registros muestran lo que la aplicación dentro del contenedor produce. Este es el paso más importante para depurar. Puedes obtener <CONTAINER_ID> a través del comando docker ps descrito en el paso 2.

Ejecuta:

docker logs <CONTAINER_ID>

Verás la salida de la aplicación, incluidos errores y advertencias. Busca mensajes que indiquen fallos como archivos faltantes o errores de conexión.

Para seguir los registros en tiempo real:

docker logs -f <CONTAINER_ID>

Verás nuevas entradas de registro a medida que aparecen. Esto es útil al reiniciar un contenedor y observar su comportamiento.

Para ver solo los registros recientes:

docker logs --tail 50 <CONTAINER_ID>

Verás las últimas 50 líneas de salida. Esto te ayuda a centrarte en los eventos más recientes.

Paso 4: Inspeccionar el Estado del Contenedor

Docker almacena información detallada sobre cada contenedor.

Ejecuta:

docker inspect <CONTAINER_ID>

Verás una salida JSON estructurada con detalles de configuración y tiempo de ejecución.

Para verificar el estado del contenedor:

docker inspect -f '{{.State.Status}}' <CONTAINER_ID>

Verás un valor simple como "running" o "exited", que confirma el estado del contenedor.

Para verificar el código de salida:

docker inspect -f '{{.State.ExitCode}}' <CONTAINER_ID>

Verás un número. Un valor de 0 significa éxito, mientras que cualquier valor distinto de cero indica un error.

Para verificar la política de reinicio:

docker inspect -f '{{.HostConfig.RestartPolicy.Name}}' <CONTAINER_ID>

Verás si el contenedor está configurado para reiniciarse automáticamente.

Códigos de salida comunes que puedes ver:

• 0 – El proceso se completó con éxito sin errores. Esto generalmente significa que el contenedor se detuvo normalmente. Por ejemplo, un script terminó su tarea y salió.
• 1 – Ocurrió un error general. Este es el código de falla más común y generalmente significa que algo dentro de la aplicación falló, como un archivo faltante, configuración inválida o error de tiempo de ejecución.
• 125 – Docker no pudo ejecutar el contenedor. Esto generalmente indica un problema con el comando docker run en sí, como opciones inválidas o parámetros incorrectos.
• 126 – El comando dentro del contenedor no se puede ejecutar. Esto a menudo significa problemas de permisos o que el archivo no es ejecutable.
• 127 – El comando no se encontró. Esto generalmente significa que el binario o script especificado no existe dentro del contenedor.
• 137 – El contenedor se detuvo a la fuerza. Esto a menudo ocurre cuando el sistema se queda sin memoria y mata el proceso del contenedor.
• 139 – El contenedor se bloqueó con un fallo de segmentación. Esto indica un error grave de la aplicación, a menudo relacionado con problemas de acceso a la memoria.
• 143 – El contenedor se detuvo de manera ordenada. Esto generalmente ocurre cuando ejecutas docker stop y el contenedor se apaga correctamente.

Paso 5: Acceder al Entorno del Contenedor

A veces, los registros no son suficientes. Puedes ingresar al contenedor para inspeccionarlo directamente.

Ejecuta:

docker exec -it <CONTAINER_ID> /bin/bash

Ingresas a una shell interactiva dentro del contenedor.

Si bash no está disponible:

docker exec -it <CONTAINER_ID> /bin/sh

Ahora puedes explorar el contenedor.

Verifica los procesos del contenedor en ejecución desde el host:

docker top <CONTAINER_ID>

Verás procesos activos dentro del contenedor. Si falta el proceso principal, el contenedor puede detenerse.

Paso 6: Monitorear el Uso de Recursos

Los contenedores pueden fallar debido a recursos limitados.

Ejecuta:

docker stats

Verás el uso en tiempo real de CPU, memoria y red para todos los contenedores.

Para monitorear un contenedor específico:

docker stats <CONTAINER_ID>

Verás una tabla en vivo que se actualiza continuamente con el uso de recursos para todos los contenedores en ejecución. Cada fila representa un contenedor, y cada columna muestra un tipo específico de uso de recursos.
Las columnas más importantes son:

• CPU % – Muestra cuánto CPU está usando el contenedor. Valores altos pueden indicar procesamiento intensivo o código ineficiente.
• MEM USAGE / LIMIT – Muestra cuánta memoria está usando el contenedor en comparación con su límite. Si el uso está cerca del límite, el contenedor puede ralentizarse o detenerse.
• MEM % – Porcentaje de memoria utilizada en relación con el límite.
• NET I/O – Tráfico de red. Esto muestra cuántos datos ha recibido y enviado el contenedor. Valores altos pueden indicar actividad de red intensa.
• BLOCK I/O – Actividad de lectura y escritura en disco. Esta columna muestra cuántos datos ha leído y escrito el contenedor en el disco.
• PIDs – Número de procesos en ejecución dentro del contenedor. Un número muy alto puede indicar una fuga de procesos o una aplicación descontrolada.

Paso 7: Verificar Eventos de Docker

Docker registra eventos que describen lo que está sucediendo a nivel del sistema y del contenedor. Estos eventos te ayudan a entender cuándo un contenedor inicia, se detiene, falla o se reinicia.
Ejecuta el siguiente comando:

docker events

Verás un flujo en vivo de eventos como inicio, detención y reinicio de contenedores. La salida se actualiza continuamente en tiempo real.

Filtrar Eventos para un Contenedor Específico

Ejecuta:

docker events --filter container=<CONTAINER_ID>

Verás solo eventos relacionados con el contenedor seleccionado. Esto te ayuda a centrarte en una sola carga de trabajo.

Mostrar Eventos de un Rango de Tiempo Específico

Para ver eventos desde un punto específico en el tiempo:

docker events --since 10m

Verás eventos de los últimos 10 minutos.

Para definir tanto la hora de inicio como la de finalización:

docker events --since 2026-01-01T10:00:00 --until 2026-01-01T11:00:00

Verás eventos que ocurrieron dentro de ese rango de tiempo.

Formatear la Salida de Eventos

Ejecuta:

docker events --format '{{.Time}} {{.Type}} {{.Action}} {{.Actor.ID}}'

Verás una salida formateada con campos seleccionados. Esto facilita la lectura o integración con scripts.

Filtrar Tipos de Eventos Específicos

Puedes filtrar eventos para centrarte en problemas específicos.

Contenedores que se Detienen o Fallan

Ejecuta:

docker events --filter event=die

Verás eventos cuando los contenedores se detienen. Esto ayuda a identificar apagados inesperados.

Eventos de Falta de Memoria

Ejecuta:

docker events --filter event=oom

Verás eventos cuando un contenedor es detenido debido a límites de memoria. Esto es crítico para diagnosticar problemas de recursos.

Reinicios de Contenedores

Ejecuta:

docker events --filter event=restart

Verás cuando los contenedores se reinician. Eventos de reinicio frecuentes pueden indicar un bucle de fallos.

Combinar Filtros y Rango de Tiempo

Ejecuta:

docker events --since 10m --filter event=die

Verás eventos de detención de contenedores de los últimos 10 minutos. Esto ayuda a reducir fallos recientes.

Paso 8: Verificar el Uso del Disco y Limpiar Imágenes No Utilizadas

Docker almacena imágenes, contenedores, volúmenes y caché en el disco. Con el tiempo, los datos no utilizados pueden consumir un espacio significativo y causar problemas.

Ejecuta el siguiente comando:

docker system df

Verás un resumen del uso del disco, incluyendo:

• Imágenes
• Contenedores
• Volúmenes locales
• Caché de compilación

Cada sección muestra:

• Conteo total
• Elementos activos
• Tamaño
• Espacio recuperable

Esto te ayuda a entender cuánto espacio en disco está utilizando Docker y cuánto se puede limpiar.

Para ver imágenes no utilizadas ejecuta:

docker images -f dangling=true

Verás imágenes que no están etiquetadas y no son utilizadas por ningún contenedor. Estas son candidatas seguras para su eliminación.

Para eliminar imágenes no utilizadas ejecuta:

docker image prune

Se te pedirá confirmación. Después de la confirmación, las imágenes no utilizadas se eliminan y se libera espacio en disco.

Para eliminar todas las imágenes no utilizadas, no solo las colgantes:

docker image prune -a

Eliminarás todas las imágenes que no son utilizadas por ningún contenedor.

Verificación y Pruebas

• Ejecuta docker ps y confirma que el estado del contenedor es correcto.
• Ejecuta docker logs y verifica que los errores se identifiquen o resuelvan.
• Ejecuta docker inspect y confirma que el estado y el código de salida coincidan con las expectativas.
• Usa docker exec para confirmar que los procesos están en ejecución dentro del contenedor.
• Si la depuración es exitosa, el contenedor debería permanecer en estado de ejecución sin errores críticos en los registros.

Revertir Cambios

Si realizaste cambios durante la depuración, puedes restaurar un estado limpio.

Detén un contenedor:

docker stop <CONTAINER_ID>

Verás la confirmación de que el contenedor se ha detenido.

Elimina un contenedor:

docker rm <CONTAINER_ID>

Verás la confirmación de que el contenedor se ha eliminado.

Recrea el contenedor:

docker run <OPTIONS> <IMAGE_NAME>

Se crea un nuevo contenedor a partir de la imagen.

Solución de Problemas

El contenedor sale inmediatamente

Verifica docker logs para mensajes de error. Estos generalmente explican el problema.

No se puede acceder al contenedor

Asegúrate de que esté en ejecución usando docker ps.

No hay registros disponibles

Asegúrate de que la aplicación escriba salida en stdout o stderr.

El contenedor se reinicia repetidamente

Verifica la política de reinicio y los registros para identificar bucles de fallos.

Uso elevado de recursos

Usa docker stats para confirmar picos de CPU o memoria.

Conclusión

Has aprendido a depurar contenedores Docker verificando su estado, analizando registros, inspeccionando la configuración y accediendo al entorno del contenedor. Estas técnicas te permiten identificar y resolver problemas comunes rápidamente. Como siguiente paso, explora la depuración de Docker Compose y sistemas de registro centralizados para gestionar múltiples contenedores.