Configurar los controladores de registro

Docker incluye múltiples mecanismos de registro para ayudarte a obtener información de los contenedores y servicios en ejecución. Estos mecanismos se denominan controladores de registro (logging drivers). Cada demonio de Docker tiene un controlador de registro predeterminado, el cual utiliza cada contenedor a menos que lo configures para utilizar un controlador de registro diferente.

De forma predeterminada, Docker utiliza el controlador de registro json-file, el cual almacena los registros de los contenedores como JSON internamente. Además de utilizar los controladores de registro incluidos con Docker, también puedes implementar y utilizar complementos de controladores de registro (plugins).

Tip

Utiliza el controlador de registro local para evitar el agotamiento del espacio en disco. Por defecto, no se realiza rotación de registros en json-file. Como resultado, los archivos de registro almacenados por el controlador predeterminado json-file pueden consumir una cantidad significativa de espacio en disco en contenedores que generan mucha salida, lo que puede provocar el agotamiento del espacio en disco.

Docker mantiene el controlador json-file (sin rotación de registros) por defecto para conservar la compatibilidad con versiones anteriores de Docker y para situaciones en las que Docker se utiliza como entorno de ejecución para Kubernetes.

Para otras situaciones, se recomienda el controlador de registro local, ya que realiza rotación de registros de forma predeterminada y utiliza un formato de archivo más eficiente. Consulta la sección Configurar el controlador de registro predeterminado a continuación para aprender cómo configurar el controlador de registro local por defecto, y la página del controlador de registro local para más detalles.

Configurar el controlador de registro predeterminado

Para configurar el demonio de Docker para que utilice por defecto un controlador de registro específico, establece el valor de log-driver con el nombre del controlador de registro en el archivo de configuración daemon.json. Consulta la sección "archivo de configuración del demonio" en el manual de referencia de dockerd para más detalles.

El controlador de registro predeterminado es json-file. El siguiente ejemplo establece el controlador de registro predeterminado en el controlador local:

{
  "log-driver": "local"
}

Si el controlador de registro tiene opciones configurables, puedes establecerlas en el archivo daemon.json como un objeto JSON bajo la clave log-opts. El siguiente ejemplo establece cuatro opciones configurables en el controlador de registro json-file:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "labels": "production_status",
    "env": "os,customer"
  }
}

Reinicia Docker para que los cambios surtan efecto en los contenedores nuevos. Los contenedores existentes no utilizarán la nueva configuración de registro automáticamente.

Note

Las opciones de configuración de log-opts en el archivo de configuración daemon.json deben proporcionarse como cadenas. Los valores booleanos y numéricos (como el valor para max-file en el ejemplo anterior) deben, por lo tanto, estar entre comillas (").

Si no especificas un controlador de registro, el predeterminado es json-file. Para conocer el controlador de registro predeterminado actual para el demonio de Docker, ejecuta docker info y busca Logging Driver. Puedes utilizar el siguiente comando en Linux, macOS o PowerShell en Windows:

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

json-file

Note

Cambiar el controlador de registro predeterminado o las opciones del controlador en la configuración del demonio solo afecta a los contenedores que se crean después de realizar el cambio de configuración. Los contenedores existentes conservan las opciones del controlador de registro que se utilizaron cuando se crearon. Para actualizar el controlador de registro de un contenedor, este debe volver a crearse con las opciones deseadas. Consulta la sección Configurar el controlador de registro para un contenedor a continuación para aprender a conocer la configuración del controlador de registro de un contenedor.

Configurar el controlador de registro para un contenedor

Cuando inicias un contenedor, puedes configurarlo para utilizar un controlador de registro diferente al predeterminado del demonio de Docker mediante la opción --log-driver. Si el controlador de registro tiene opciones configurables, puedes establecerlas utilizando una o más instancias de la opción --log-opt <NOMBRE>=<VALOR>. Incluso si el contenedor utiliza el controlador de registro predeterminado, este puede usar opciones configurables diferentes.

El siguiente ejemplo inicia un contenedor Alpine con el controlador de registro none.

$ docker run -it --log-driver none alpine ash

Para conocer el controlador de registro actual de un contenedor en ejecución, si el demonio está utilizando el controlador json-file, ejecuta el siguiente comando docker inspect, sustituyendo <CONTAINER> por el nombre o ID del contenedor:

$ docker inspect -f '{{.HostConfig.LogConfig.Type}}' <CONTAINER>

json-file

Configurar el modo de entrega de los mensajes de registro desde el contenedor al controlador

Docker proporciona dos modos para entregar mensajes desde el contenedor al controlador de registro:

• (Predeterminado) entrega directa y bloqueante (blocking) desde el contenedor al controlador.
• entrega no bloqueante (non-blocking) que almacena los mensajes de registro en un búfer intermedio por contenedor para su consumo por parte del controlador.

El modo de entrega de mensajes non-blocking evita que las aplicaciones se bloqueen debido a la contrapresión (back pressure) del sistema de registro. Es probable que las aplicaciones fallen de formas inesperadas cuando los flujos STDERR o STDOUT se bloquean.

Warning

Cuando el búfer está lleno, no se encolarán nuevos mensajes. La pérdida de mensajes suele ser preferible antes que bloquear el proceso de escritura de registros de una aplicación.

La opción de registro mode controla si se utiliza la entrega de mensajes blocking (predeterminada) o non-blocking.

La opción max-buffer-size controla el tamaño del búfer utilizado para el almacenamiento intermedio de mensajes cuando mode está configurado en non-blocking. El valor predeterminado es 1m, es decir, 1 MB (1 millón de bytes). Consulta la función FromHumanSize() en el paquete go-units para ver los formatos de cadena permitidos; algunos ejemplos son 1KiB para 1024 bytes y 2g para 2 mil millones de bytes.

El siguiente ejemplo inicia un contenedor Alpine con la salida de registros en modo no bloqueante y un búfer de 4 megabytes:

$ docker run -it --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine ping 127.0.0.1

Utilizar variables de entorno o etiquetas con los controladores de registro

Algunos controladores de registro añaden el valor de las opciones --env|-e o --label de un contenedor a los registros del mismo. Este ejemplo inicia un contenedor utilizando el controlador de registro predeterminado del demonio de Docker (en el siguiente ejemplo, json-file) pero establece la variable de entorno os=ubuntu.

$ docker run -dit --label production_status=testing -e os=ubuntu alpine sh

Si el controlador de registro lo admite, esto añade campos adicionales a la salida del registro. La siguiente salida es generada por el controlador de registro json-file:

"attrs":{"production_status":"testing","os":"ubuntu"}

Controladores de registro compatibles

Se admiten los siguientes controladores de registro. Consulta el enlace a la documentación de cada controlador para conocer sus opciones configurables, si corresponde. Si estás utilizando complementos de controladores de registro (plugins), es posible que veas más opciones.

Limitaciones de los controladores de registro

• La lectura de la información de registro requiere descomprimir los archivos de registro rotados, lo que provoca un aumento temporal en el uso de disco (hasta que se lean las entradas de registro de los archivos rotados) y un mayor uso de CPU durante la descompresión.
• La capacidad del almacenamiento del host donde reside el directorio de datos de Docker determina el tamaño máximo de la información de los archivos de registro.