Docker Container Logs

docker logs y opciones

Los contenedores Docker generan información de logging durante su ejecución que resulta fundamental para el desarrollo y diagnóstico de problemas. El comando docker logs permite acceder a toda esta información de forma sencilla y eficiente.

Cuando ejecutas un contenedor, Docker captura automáticamente todo lo que la aplicación envía a stdout y stderr, almacenando estos logs de forma centralizada. Esta funcionalidad es especialmente útil cuando trabajas con aplicaciones que no tienen acceso directo al sistema de archivos del host.

Uso básico del comando docker logs

La sintaxis básica del comando es straightforward:

docker logs [OPCIONES] CONTENEDOR

Para ver los logs de un contenedor en ejecución, simplemente utiliza su nombre o ID:

docker logs mi-nginx

Este comando muestra todo el historial de logs del contenedor desde su inicio. Si el contenedor ha estado ejecutándose durante mucho tiempo, la salida puede ser extensa.

Opciones esenciales para filtrar logs

Docker logs incluye múltiples opciones que permiten filtrar y controlar la salida según tus necesidades específicas:

Limitando la cantidad de líneas con --tail:

# Mostrar solo las últimas 50 líneas
docker logs --tail 50 mi-nginx

# Mostrar solo las últimas 10 líneas (más común)
docker logs --tail 10 mi-nginx

La opción --tail es especialmente útil cuando solo necesitas ver actividad reciente sin cargar todo el historial de logs.

Seguimiento en tiempo real con --follow:

# Seguir los logs en tiempo real (similar a tail -f)
docker logs --follow mi-nginx
docker logs -f mi-nginx

# Combinando follow con tail para ver las últimas líneas y seguir
docker logs --follow --tail 20 mi-nginx

El flag --follow (o su versión corta -f) mantiene la conexión activa y muestra nuevos logs conforme se generan, siendo ideal para monitorización en tiempo real durante el desarrollo.

Filtrado temporal con --since y --until

Para analizar logs en períodos específicos, Docker proporciona opciones de filtrado temporal:

# Logs desde hace 1 hora
docker logs --since 1h mi-nginx

# Logs desde hace 30 minutos
docker logs --since 30m mi-nginx

# Logs desde una fecha específica
docker logs --since "2024-01-15T10:00:00" mi-nginx

# Logs hasta una fecha específica
docker logs --until "2024-01-15T12:00:00" mi-nginx

Puedes combinar ambas opciones para obtener logs de un rango temporal específico:

# Logs entre las 10:00 y las 12:00 de hoy
docker logs --since "2024-01-15T10:00:00" --until "2024-01-15T12:00:00" mi-nginx

Añadiendo timestamps con --timestamps

Por defecto, Docker logs no muestra marcas de tiempo. Para incluirlas, utiliza la opción --timestamps:

docker logs --timestamps mi-nginx

Esto añade la fecha y hora exacta a cada línea de log:

2024-01-15T14:30:45.123456789Z 192.168.1.100 - - [15/Jan/2024:14:30:45 +0000] "GET / HTTP/1.1" 200 612
2024-01-15T14:30:46.234567890Z 192.168.1.101 - - [15/Jan/2024:14:30:46 +0000] "GET /favicon.ico HTTP/1.1" 404 555

Combinando opciones para análisis efectivo

Las opciones del comando docker logs son especialmente potentes cuando se combinan:

# Ver los últimos 25 logs con timestamps y seguir nuevos logs
docker logs --follow --tail 25 --timestamps mi-nginx

# Logs de la última hora con timestamps
docker logs --since 1h --timestamps mi-postgresql

# Seguir logs desde hace 10 minutos
docker logs --follow --since 10m mi-mysql

Casos de uso prácticos

Debugging durante desarrollo:

# Monitorizar una aplicación web en desarrollo
docker logs --follow --tail 50 mi-app-web

Análisis de problemas específicos:

# Revisar logs de las últimas 2 horas con timestamps
docker logs --since 2h --timestamps mi-api

Monitorización de bases de datos:

# Ver inicialización de MySQL
docker logs --timestamps mi-mysql

# Seguir logs de PostgreSQL en tiempo real
docker logs --follow mi-postgresql

Consideraciones importantes

Es importante recordar que docker logs solo funciona con contenedores que envían su salida a stdout/stderr. Algunas aplicaciones escriben logs directamente a archivos, por lo que no aparecerán mediante este comando.

Los logs se almacenan en el sistema de archivos del host Docker, y su ubicación específica depende del driver de logging configurado. El comportamiento predeterminado utiliza el driver json-file, que almacena logs en formato JSON en el directorio del contenedor.

El comando docker logs no modifica ni elimina los logs existentes, simplemente los lee y muestra. Para gestionar el tamaño y rotación de logs, es necesario configurar opciones específicas del driver de logging correspondiente.

Drivers de logging

Docker utiliza drivers de logging para determinar cómo se almacenan y gestionan los logs de los contenedores. Estos drivers definen el formato, ubicación y comportamiento de rotación de los logs, ofreciendo flexibilidad para adaptarse a diferentes entornos y necesidades operativas.

Cada contenedor puede configurarse con un driver específico, permitiendo estrategias de logging personalizadas según el tipo de aplicación o requisitos de infraestructura. Por defecto, Docker Engine utiliza el driver json-file, aunque existen múltiples opciones disponibles.

Driver json-file (predeterminado)

El driver json-file es el mecanismo de logging por defecto en Docker. Almacena los logs en formato JSON en el sistema de archivos local del host Docker, específicamente en /var/lib/docker/containers/<container-id>/<container-id>-json.log.

# Configurar explícitamente el driver json-file (es el predeterminado)
docker run --log-driver json-file nginx

Este driver incluye metadatos adicionales en cada entrada de log, como timestamps, stream (stdout/stderr) y información del contenedor:

{
  "log": "192.168.1.100 - - [15/Jan/2024:14:30:45 +0000] \"GET / HTTP/1.1\" 200 612\n",
  "stream": "stdout",
  "time": "2024-01-15T14:30:45.123456789Z"
}

Configuración de rotación para json-file:

# Limitar tamaño máximo y número de archivos de log
docker run --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  nginx

Las opciones de rotación incluyen:

• max-size: Tamaño máximo por archivo (por defecto: -1, sin límite)
• max-file: Número máximo de archivos de log (por defecto: 1)
• compress: Comprimir archivos rotados (por defecto: disabled)

Driver local

El driver local es una alternativa optimizada al json-file que ofrece mejor rendimiento y compresión automática. Está diseñado para reducir el uso de espacio en disco manteniendo la compatibilidad con docker logs.

# Usar el driver local con rotación automática
docker run --log-driver local \
  --log-opt max-size=20m \
  --log-opt max-file=5 \
  mysql:8.0

Este driver almacena logs en un formato binario optimizado y aplica compresión automáticamente, siendo especialmente útil para contenedores que generan gran volumen de logs.

Ventajas del driver local:

• Mejor rendimiento en escritura
• Compresión automática de logs
• Menor uso de espacio en disco
• Compatible con docker logs

Driver none

El driver none deshabilita completamente el logging del contenedor. Los logs no se almacenan en ningún lugar y no están disponibles mediante docker logs.

# Ejecutar contenedor sin logging
docker run --log-driver none nginx

Este driver es útil para contenedores temporales o cuando el logging se gestiona internamente por la aplicación. Ten en cuenta que una vez configurado, no podrás acceder a los logs mediante los comandos estándar de Docker.

Driver syslog

El driver syslog envía logs directamente al daemon syslog del sistema host, integrándose con la infraestructura de logging existente del servidor.

# Enviar logs a syslog local
docker run --log-driver syslog \
  --log-opt syslog-address=unix:///dev/log \
  --log-opt tag="mi-aplicacion" \
  nginx

Configuración con syslog remoto:

# Enviar logs a servidor syslog remoto
docker run --log-driver syslog \
  --log-opt syslog-address=tcp://192.168.1.100:514 \
  --log-opt tag="{{.Name}}/{{.ID}}" \
  postgresql:15

Las opciones disponibles incluyen:

• syslog-address: Dirección del servidor syslog (local o remoto)
• tag: Etiqueta para identificar logs en syslog
• syslog-facility: Facility de syslog (por defecto: daemon)

Driver journald

En sistemas que utilizan systemd, el driver journald envía logs directamente al journal del sistema, aprovechando las capacidades avanzadas de systemd para gestión de logs.

# Enviar logs al journal de systemd
docker run --log-driver journald \
  --log-opt tag="mi-app-{{.Name}}" \
  nginx

Para consultar estos logs, utiliza journalctl en lugar de docker logs:

# Ver logs del contenedor en journald
journalctl CONTAINER_NAME=mi-nginx

# Seguir logs en tiempo real
journalctl -f CONTAINER_NAME=mi-nginx

Configuración global de drivers

Puedes configurar el driver predeterminado para todos los contenedores modificando el archivo de configuración del daemon Docker (/etc/docker/daemon.json):

{
  "log-driver": "local",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Después de modificar la configuración, reinicia el daemon Docker:

sudo systemctl restart docker

Configuración por contenedor vs global

La configuración de logging puede aplicarse a nivel de contenedor o globalmente:

# Sobrescribir configuración global para un contenedor específico
docker run --log-driver json-file \
  --log-opt max-size=50m \
  --log-opt max-file=2 \
  mysql:8.0

La configuración a nivel de contenedor siempre prevalece sobre la configuración global del daemon, proporcionando flexibilidad para casos específicos.

Consideraciones de rendimiento y almacenamiento

Los diferentes drivers tienen impacto variable en el rendimiento y uso de almacenamiento:

• json-file: Fácil de usar, compatible con todas las funciones de Docker, pero puede consumir más espacio
• local: Mejor rendimiento y compresión, ideal para aplicaciones con alto volumen de logs
• syslog/journald: Integración con sistemas de logging existentes, pero docker logs no funciona
• none: Sin overhead, pero pierdes capacidad de debugging

Buenas prácticas para drivers de logging

Para entornos de desarrollo, json-file o local son las mejores opciones, manteniendo accesibilidad mediante docker logs y configurando rotación adecuada:

docker run --log-driver local \
  --log-opt max-size=20m \
  --log-opt max-file=3 \
  mi-aplicacion-dev

En entornos de producción, considera syslog o journald para integración con sistemas de monitorización centralizados:

docker run --log-driver syslog \
  --log-opt syslog-address=tcp://log-server:514 \
  --log-opt tag="prod-{{.Name}}" \
  mi-aplicacion-prod

La elección del driver adecuado depende de tus requisitos específicos de observabilidad, retención de logs y integración con la infraestructura existente.