# Controlador de registro de Amazon CloudWatch Logs El controlador de registro `awslogs` envía los registros de los contenedores a [Amazon CloudWatch Logs](https://aws.amazon.com/cloudwatch/details/#log-monitoring). Los registros se pueden recuperar a través de la [Consola de administración de AWS](https://console.aws.amazon.com/cloudwatch/home#logs:) o las [SDK y herramientas de línea de comandos de AWS](https://docs.aws.amazon.com/cli/latest/reference/logs/index.html). ## Uso Para usar el controlador `awslogs` como el controlador de registro predeterminado, establece las claves `log-driver` y `log-opt` con los valores adecuados en el archivo `daemon.json`. Para obtener más información sobre cómo configurar Docker mediante `daemon.json`, consulta [daemon.json](/reference/cli/dockerd/#daemon-configuration-file). > [!NOTE] > > Si usas Docker Desktop, edita la configuración del demonio a través del > panel de Docker Desktop. Abre **Settings** y selecciona **Docker Engine**. > Para más detalles, consulta > [Configuración de Docker Engine](/desktop/settings-and-maintenance/settings/#docker-engine). El siguiente ejemplo establece el controlador de registro en `awslogs` y configura la opción `awslogs-region`. ```json { "log-driver": "awslogs", "log-opts": { "awslogs-region": "us-east-1" } } ``` Reinicia Docker para que los cambios surtan efecto. Puedes establecer el controlador de registro para un contenedor específico utilizando la opción `--log-driver` en `docker run`: ```console $ docker run --log-driver=awslogs ... ``` Si estás utilizando Docker Compose, configura `awslogs` empleando el siguiente ejemplo de declaración: ```yaml myservice: logging: driver: awslogs options: awslogs-region: us-east-1 ``` ## Opciones de Amazon CloudWatch Logs Puedes agregar opciones de registro a `daemon.json` para establecer valores predeterminados para todo Docker, o utilizar la opción `--log-opt NOMBRE=VALOR` para especificar las opciones del controlador de registro de Amazon CloudWatch Logs al iniciar un contenedor. ### awslogs-region El controlador de registro `awslogs` envía tus registros de Docker a una región específica. Utiliza la opción de registro `awslogs-region` o la variable de entorno `AWS_REGION` para configurar la región. Por defecto, si tu demonio de Docker se está ejecutando en una instancia de EC2 y no se ha configurado ninguna región, el controlador utiliza la región de la instancia. ```console $ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 ... ``` ### awslogs-endpoint Por defecto, Docker utiliza la opción de registro `awslogs-region` o la región detectada para construir el punto final (endpoint) de la API de CloudWatch Logs remota. Utiliza la opción de registro `awslogs-endpoint` para invalidar el punto final predeterminado con el punto final proporcionado. > [!NOTE] > > La opción de registro `awslogs-region` o la región detectada controlan la región utilizada para la firma. Es posible que experimentes errores de firma si el punto final que has especificado con `awslogs-endpoint` utiliza una región diferente. ### awslogs-group Debes especificar un [grupo de registro](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) para el controlador de registro `awslogs`. Puedes especificar el grupo de registro con la opción `awslogs-group`: ```console $ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 --log-opt awslogs-group=myLogGroup ... ``` ### awslogs-stream Para configurar qué [flujo de registro (log stream)](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) se debe utilizar, puedes especificar la opción de registro `awslogs-stream`. Si no se especifica, se utiliza el ID del contenedor como flujo de registro. > [!NOTE] > > Los flujos de registro dentro de un grupo de registro determinado solo deben ser utilizados por un contenedor a la vez. El uso del mismo flujo de registro para múltiples contenedores de forma simultánea puede reducir el rendimiento del registro. ### awslogs-create-group El controlador de registro devuelve un error de forma predeterminada si el grupo de registro no existe. Sin embargo, puedes establecer `awslogs-create-group` en `true` para crear automáticamente el grupo de registro según sea necesario. La opción `awslogs-create-group` tiene como valor predeterminado `false`. ```console $ docker run \ --log-driver=awslogs \ --log-opt awslogs-region=us-east-1 \ --log-opt awslogs-group=myLogGroup \ --log-opt awslogs-create-group=true \ ... ``` > [!NOTE] > > Tu política de AWS IAM debe incluir el permiso `logs:CreateLogGroup` antes de intentar utilizar `awslogs-create-group`. ### awslogs-create-stream Por defecto, el controlador de registro crea el flujo de AWS CloudWatch Logs utilizado para la persistencia de los registros del contenedor. Establece `awslogs-create-stream` en `false` para deshabilitar la creación de flujos de registro. Cuando está deshabilitado, el demonio de Docker asume que el flujo de registro ya existe. Un caso de uso donde esto resulta beneficioso es cuando la creación del flujo de registro es manejada por otro proceso, evitando llamadas redundantes a la API de AWS CloudWatch Logs. Si `awslogs-create-stream` se establece en `false` y el flujo de registro no existe, la persistencia del registro en CloudWatch fallará durante el tiempo de ejecución del contenedor, lo que provocará mensajes de error `Failed to put log events` en los registros del demonio. ```console $ docker run \ --log-driver=awslogs \ --log-opt awslogs-region=us-east-1 \ --log-opt awslogs-group=myLogGroup \ --log-opt awslogs-stream=myLogStream \ --log-opt awslogs-create-stream=false \ ... ``` ### awslogs-datetime-format La opción `awslogs-datetime-format` define un patrón de inicio de varias líneas en el [formato `strftime` de Python](https://strftime.org). Un mensaje de registro consta de una línea que coincide con el patrón y de cualquier línea siguiente que no coincida con el patrón. De este modo, la línea coincidente es el delimitador entre los mensajes de registro. Un ejemplo de caso de uso para utilizar este formato es para analizar salidas como un volcado de pila (stack dump), que de otro modo podría registrarse en múltiples entradas. El patrón correcto permite capturarlo en una sola entrada. Esta opción siempre tiene prioridad si se configuran tanto `awslogs-datetime-format` como `awslogs-multiline-pattern`. > [!NOTE] > > El registro de varias líneas realiza el análisis sintáctico y la coincidencia de expresiones regulares de todos los mensajes de registro, lo que puede tener un impacto negativo en el rendimiento del registro. Considera el siguiente flujo de registro, donde los nuevos mensajes de registro comienzan con una marca de tiempo: ```console [May 01, 2017 19:00:01] A message was logged [May 01, 2017 19:00:04] Another multi-line message was logged Some random message with some random words [May 01, 2017 19:01:32] Another message was logged ``` El formato se puede expresar como una expresión `strftime` de `[%b %d, %Y %H:%M:%S]`, y el valor de `awslogs-datetime-format` se puede establecer con esa expresión: ```console $ docker run \ --log-driver=awslogs \ --log-opt awslogs-region=us-east-1 \ --log-opt awslogs-group=myLogGroup \ --log-opt awslogs-datetime-format='\[%b %d, %Y %H:%M:%S\]' \ ... ``` Esto analiza los registros en los siguientes eventos de CloudWatch: ```console # Primer evento [May 01, 2017 19:00:01] A message was logged # Segundo evento [May 01, 2017 19:00:04] Another multi-line message was logged Some random message with some random words # Tercer evento [May 01, 2017 19:01:32] Another message was logged ``` Se admiten los siguientes códigos de `strftime`: | Código | Significado | Ejemplo | | :----- | :------------------------------------------------------------------------------- | :------- | | `%a` | Nombre abreviado del día de la semana. | Mon | | `%A` | Nombre completo del día de la semana. | Monday | | `%w` | Día de la semana como número decimal donde 0 es domingo y 6 es sábado. | 0 | | `%d` | Día del mes como un número decimal rellenado con ceros. | 08 | | `%b` | Nombre abreviado del mes. | Feb | | `%B` | Nombre completo del mes. | February | | `%m` | Mes como un número decimal rellenado con ceros. | 02 | | `%Y` | Año con siglo como un número decimal. | 2008 | | `%y` | Año sin siglo como un número decimal rellenado con ceros. | 08 | | `%H` | Hora (reloj de 24 horas) como un número decimal rellenado con ceros. | 19 | | `%I` | Hora (reloj de 12 horas) como un número decimal rellenado con ceros. | 07 | | `%p` | AM o PM. | AM | | `%M` | Minuto como un número decimal rellenado con ceros. | 57 | | `%S` | Segundo como un número decimal rellenado con ceros. | 04 | | `%f` | Microsegundos como un número decimal rellenado con ceros. | 000345 | | `%z` | Desplazamiento UTC en la forma +HHMM o -HHMM. | +1300 | | `%Z` | Nombre de la zona horaria. | PST | | `%j` | Día del año como un número decimal rellenado con ceros. | 363 | Además, se admiten los siguientes códigos que no son de `strftime`: | Código | Significado | Ejemplo | | :----- | :-------------------------------------------------------------------------------------- | :------- | | `%L` | Milisegundos como un número decimal rellenado con ceros y precedido por un punto. | .123 | ### awslogs-multiline-pattern La opción `awslogs-multiline-pattern` define un patrón de inicio de varias líneas utilizando una expresión regular. Un mensaje de registro consta de una línea que coincide con el patrón y de cualquier línea siguiente que no coincida con el patrón. De este modo, la línea coincidente es el delimitador entre los mensajes de registro. Esta opción se ignora si también está configurada `awslogs-datetime-format`. > [!NOTE] > > El registro de varias líneas realiza el análisis sintáctico y la coincidencia de expresiones regulares de todos los mensajes de registro. Esto puede tener un impacto negativo en el rendimiento del registro. Considera el siguiente flujo de registro, donde cada mensaje de registro debe comenzar con el patrón `INFO`: ```console INFO A message was logged INFO Another multi-line message was logged Some random message INFO Another message was logged ``` Puedes utilizar la expresión regular `^INFO`: ```console $ docker run \ --log-driver=awslogs \ --log-opt awslogs-region=us-east-1 \ --log-opt awslogs-group=myLogGroup \ --log-opt awslogs-multiline-pattern='^INFO' \ ... ``` Esto analiza los registros en los siguientes eventos de CloudWatch: ```console # Primer evento INFO A message was logged # Segundo evento INFO Another multi-line message was logged Some random message # Tercer evento INFO Another message was logged ``` ### tag Especifica `tag` como alternativa a la opción `awslogs-stream`. `tag` interpreta las marcas de plantilla de Go, como `{{.ID}}`, `{{.FullID}}` o `{{.Name}}`. Consulta la [documentación de la opción de etiqueta (tag)](/engine/logging/drivers/awslogs/log_tags/) para más detalles sobre las sustituciones de plantillas admitidas. Cuando se especifican tanto `awslogs-stream` como `tag`, el valor proporcionado para `awslogs-stream` invalida la plantilla especificada con `tag`. Si no se especifica, se utiliza el ID del contenedor como flujo de registro. > [!NOTE] > > La API de registro de CloudWatch no admite el carácter `:` en el nombre del registro. Esto puede causar problemas al utilizar `{{ .ImageName }}` como etiqueta, ya que una imagen de Docker tiene el formato `IMAGE:TAG`, por ejemplo `alpine:latest`. Se pueden utilizar marcas de plantilla para obtener el formato adecuado. Para obtener el nombre de la imagen y los primeros 12 caracteres del ID del contenedor, puedes utilizar: > > ```bash > --log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}' > ``` > > el resultado es algo como: `alpine_latest-bf0072049c76` ### awslogs-force-flush-interval-seconds El controlador `awslogs` descarga periódicamente los registros en CloudWatch. La opción `awslogs-force-flush-interval-seconds` cambia los segundos del intervalo de descarga. El valor predeterminado es 5 segundos. ### awslogs-max-buffered-events El controlador `awslogs` almacena en búfer los registros. La opción `awslogs-max-buffered-events` cambia el tamaño del búfer de registros. El valor predeterminado es 4K. ## Credenciales Debes proporcionar credenciales de AWS al demonio de Docker para utilizar el controlador de registro `awslogs`. Puedes proporcionar estas credenciales mediante las variables de entorno `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` y `AWS_SESSION_TOKEN`, el archivo de credenciales compartidas predeterminado de AWS (`~/.aws/credentials` del usuario root) o, si estás ejecutando el demonio de Docker en una instancia de Amazon EC2, el perfil de la instancia de Amazon EC2. Las credenciales deben tener aplicada una política que permita las acciones `logs:CreateLogStream` y `logs:PutLogEvents`, tal como se muestra en el siguiente ejemplo: ```json { "Version": "2012-10-17", "Statement": [ { "Action": ["logs:CreateLogStream", "logs:PutLogEvents"], "Effect": "Allow", "Resource": "*" } ] } ```