Controlador de registro de Amazon CloudWatch Logs

El controlador de registro awslogs envía los registros de los contenedores a Amazon CloudWatch Logs. Los registros se pueden recuperar a través de la Consola de administración de AWS o las SDK y herramientas de línea de comandos de AWS.

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.

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.

El siguiente ejemplo establece el controlador de registro en awslogs y configura la opción awslogs-region.

{
  "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:

$ docker run --log-driver=awslogs ...

Si estás utilizando Docker Compose, configura awslogs empleando el siguiente ejemplo de declaración:

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.

$ 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 para el controlador de registro awslogs. Puedes especificar el grupo de registro con la opción awslogs-group:

$ 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) 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.

$ 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.

$ 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. 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:

[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:

$ 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:

# 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:

Además, se admiten los siguientes códigos que no son de strftime:

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:

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:

$ 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:

# 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) 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:

--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:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}