Configurar la rotación de logs de Docker con un controlador de logging: logging de Docker con journald y controlador de archivos local

Nivel: Experto
Tiempo estimado: ~20 minutos
Objetivo: Configurar la rotación de logs de Docker para garantizar una gestión de logs sin tiempo de inactividad y evitar el agotamiento del espacio en disco.

Introducción

Los logs de Docker sin gestionar pueden agotar rápidamente el almacenamiento del servidor. De forma predeterminada, el demonio de Docker escribe los logs con el formato json-file y sin límites de tamaño. Para mantener una infraestructura fiable, debe configurar la rotación de logs de Docker utilizando un controlador de logging de Docker escalable. Esta guía explica cómo implementar la rotación de logs de Docker de forma global, ya sea con el logging de Docker mediante journald o con el controlador de archivos local (local) de Docker. Elegir la configuración correcta garantiza una gestión de logs eficiente y la estabilidad del sistema.

Terminología

Antes de continuar, familiarícese con los siguientes conceptos básicos:

• Docker: plataforma para ejecutar aplicaciones en entornos aislados llamados contenedores.
• Logs de Docker: los flujos de salida capturados de Stdout (salida estándar) y Stderr (error estándar) de un contenedor.
• Rotación de logs: la práctica de archivar y eliminar logs antiguos para recuperar espacio.
• Controlador de logging (logging driver): el mecanismo que Docker utiliza para capturar, dar formato y enrutar los logs.
• Journald: el servicio de logging de systemd, ideal para el registro centralizado en el host.
• Controlador de archivos local (local): un controlador integrado de alto rendimiento, optimizado para el almacenamiento local.
• Json-file: el controlador predeterminado, que escribe los logs en formato JSON.
• Demonio de Docker: el servicio en segundo plano que gestiona las operaciones de Docker.
• Daemon.json: el archivo de configuración del demonio.
• Configuración del controlador de logs: la configuración de logging global o por contenedor.
• Opciones de log: parámetros específicos que se pasan al controlador.
• Max-size: el tamaño umbral a partir del cual se rota un archivo de log.
• Max-file: el número máximo de archivos rotados que se conservan.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

• Sistema operativo: Ubuntu 22.04 / 24.04 LTS, Debian 12 / 13, RHEL 9 / 10, AlmaLinux 9 / 10, Rocky Linux 9 / 10
• Docker: versión 24.x o posterior instalada
• Acceso: privilegios de sudo
• Conocimientos necesarios: administración de Linux y conceptos de Infraestructura como Código (IaC)

Paso 1: Comprender las diferencias entre los controladores json-file y local de Docker

Al evaluar los controladores json-file y local de Docker, el rendimiento y la sobrecarga determinan la elección. El controlador predeterminado json-file es sencillo, pero consume más CPU y espacio en disco debido al formato JSON. En cambio, el controlador de archivos local usa un formato binario de solo anexado (append-only) optimizado específicamente para la eficiencia de la rotación. En cargas de trabajo normales de producción, utilizar el controlador de archivos local (local) de Docker reduce la sobrecarga en disco y aplica la rotación de forma nativa y fiable.

Para comprobar su controlador actual, ejecute:

docker info --format '{{.LoggingDriver}}'

Salida esperada:

json-file

Si ve json-file, proceda a modificar la configuración de logging de Docker en daemon.json.

Paso 2: Configurar la rotación de logs de Docker con el controlador de archivos local (local)

Para aplicar límites globales a todos los contenedores, editará el archivo /etc/docker/daemon.json. Este es el método recomendado para la configuración de logging de Docker en daemon.json.

Abra el archivo de configuración:

Si /etc/docker/daemon.json no existe en su sistema, nano lo creará al guardar. Esto es normal: Docker utiliza valores predeterminados integrados cuando el archivo no existe.

sudo nano /etc/docker/daemon.json

Añada la siguiente configuración del controlador de logs:

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

Guarde y cierre el archivo. La nueva configuración se escribe en disco. Esta configuración aplica el controlador de forma global. Las opciones de log indican a Docker que rote los logs cuando alcancen los 50 megabytes (max-size en los logs de Docker) y que conserve un máximo de 3 archivos (max-file en los logs de Docker). Tenga en cuenta que el controlador local sigue admitiendo de forma nativa estas restricciones explícitas de tamaño y número de archivos, a diferencia de journald.

Reinicie el demonio de Docker para aplicar los cambios. El servicio docker.service gestiona los contenedores, por lo que al reiniciarlo se aplican los límites:

sudo systemctl restart docker

Perderá la conectividad con el demonio durante unos segundos. Una vez reiniciado, todos los contenedores creados a partir de ese momento usarán el controlador de archivos local (local) de Docker y heredarán estos límites de max-size y max-file de los logs de Docker.

Además, tenga en cuenta el orden de precedencia de las configuraciones de logging:

1. Las opciones de la CLI (docker run --log-driver) prevalecen sobre todo lo demás.
2. Las sobrescrituras de logging en docker-compose.yml se aplican por servicio en el momento de crear el contenedor.
3. daemon.json actúa como valor global predeterminado para todos los contenedores sin configuración explícita.

Paso 3: Habilitar el logging de Docker mediante journald como controlador de logging de Docker

Como alternativa, puede enviar los logs directamente al demonio journald del sistema. El logging de Docker mediante journald se integra a la perfección con systemctl y con los reenviadores de logs externos.

Abra el archivo de configuración:

sudo nano /etc/docker/daemon.json

Sustituya el contenido por la configuración de journald. Reemplace por completo el contenido del archivo y elimine cualquier entrada anterior de log-opts, ya que journald no admite las opciones max-size ni max-file:

{
  "log-driver": "journald"
}

Guarde y cierre el archivo. La configuración queda actualizada.

Reinicie el servicio. Es necesario recargar docker.service para trasladar la gestión de logs a journald:

sudo systemctl restart docker

Al usar los logs de Docker con journald, el controlador journald elimina el control de rotación del lado de Docker. La rotación de logs sigue existiendo, pero la gestiona por completo el journal de systemd, fuera de Docker. Verá que los logs se envían directamente al journal de systemd. Se indexan mediante campos de metadatos del contenedor, en lugar de estar vinculados a la unidad docker.service.

En la práctica, journald gestiona estos logs con límites concretos configurados en /etc/systemd/journald.conf, en particular SystemMaxUse, RuntimeMaxUse y MaxRetentionSec. Esto conlleva un riesgo de gran radio de impacto (blast radius): el agotamiento de journald puede afectar en producción al registro de ssh, a los logs del kernel, a los logs de auditoría y a todos los demás servicios que comparten el journal. Tenga en cuenta que las opciones max-size y max-file solo se aplican a los controladores json-file y local, no a journald.

Para aplicar los cambios en la configuración de journald:

sudo systemctl restart systemd-journald
# Or to trigger immediate rotation without a full restart:
sudo systemctl kill -s SIGUSR2 systemd-journald

Paso 4: Gestionar la salida de journalctl

Al configurar la rotación de logs de Docker mediante journald, se interactúa con los logs usando journalctl en lugar de docker logs. El servicio journald procesa estos logs de forma centralizada.

Para ver los logs de un contenedor concreto con los logs de Docker en journald, ejecute:

journalctl CONTAINER_NAME=<YOUR_CONTAINER_NAME> -o cat

Salida esperada:

Application started successfully

Paso 5: Verificación

Para verificar la configuración del controlador de logging de Docker en un contenedor en ejecución, inicie un contenedor de prueba:

docker run -d --name log-test nginx:latest

Inspeccione las opciones de log del contenedor:

docker inspect -f '{{.HostConfig.LogConfig.Type}}' log-test

Salida esperada para el controlador local:

local

Si configuró journald, la salida será journald.

Compruebe los parámetros aplicados para el controlador local:

docker inspect -f '{{.HostConfig.LogConfig.Config}}' log-test

Salida esperada:

map[max-file:3 max-size:50m]

Esto confirma que su configuración de logging de Docker en daemon.json aplicó correctamente los parámetros max-size y max-file de los logs de Docker. Tenga en cuenta que journald no muestra aquí las opciones max-size ni max-file, ya que la rotación se delega en el sistema operativo.

Utilice este comando para identificar los contenedores preexistentes que sigan usando el controlador anterior. El controlador de logging se fija al crear el contenedor, por lo que estos contenedores deben recrearse (por ejemplo, con docker compose up -d --force-recreate) para heredar la nueva configuración:

docker ps -aq | xargs -r docker inspect -f '{{.Name}}: {{.HostConfig.LogConfig.Type}}'

Revertir los cambios

Para devolver la configuración global del controlador de logs al formato predeterminado, elimine la configuración de daemon.json.

Elimine el archivo (haga siempre una copia de seguridad de los archivos de configuración antes de modificarlos) y reinicie el servicio de Docker:

sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak.$(date +%F)
sudo rm /etc/docker/daemon.json
sudo systemctl restart docker

Solución de problemas

• journalctl no devuelve resultados para CONTAINER_ID: el controlador journald de Docker escribe en CONTAINER_ID el ID corto de 12 caracteres, mientras que docker inspect devuelve el ID completo de 64 caracteres. Utilice en su lugar CONTAINER_NAME o CONTAINER_ID_FULL.
• Los contenedores existentes siguen usando json-file tras el reinicio: el comando docker update no cambia el controlador de logging. Debe recrear el contenedor (por ejemplo, con docker compose down y luego up) para aplicar el nuevo controlador de logging.
• max-size y max-file no tienen efecto con journald: la rotación de logs de journald se gestiona de forma global mediante /etc/systemd/journald.conf (por ejemplo, SystemMaxUse), no a través de las log-opts de Docker.

Conclusión

Gestionar correctamente la salida de los contenedores es una parte fundamental de una infraestructura fiable. Si elige bien entre los controladores json-file y local de Docker, evitará problemas de almacenamiento. Tanto si configura la rotación de logs de Docker con el ligero controlador de archivos local (local) de Docker como si se integra de forma nativa mediante el logging de Docker con journald, su entorno está ahora preparado para gestionar con seguridad grandes flujos de logs. Aplicar estas prácticas de rotación de logs de Docker garantiza que la configuración de su controlador de logging de Docker se mantenga estable y que los recursos de su host sean predecibles.

Versión del documento: 1.0
Última actualización: mayo de 2026
Responsable: Equipo de Documentación Técnica