Uso del controlador de registros awslogs

Puede configurar los contenedores de las tareas para que envíen información de registro aCloudWatch Logs. Si utiliza el tipo de lanzamiento de Fargate para las tareas, puede ver los registros de los contenedores. Si utiliza el tipo de lanzamiento de EC2, esto le permite ver distintos registros desde los contenedores en una ubicación cómoda y evita que los registros de contenedor ocupen espacio en disco en sus instancias de contenedor. En este tema se analiza cómo comenzar a utilizar el controlador de registros awslogs en las definiciones de tareas.

nota

El tipo de información que registran los contenedores de la tarea depende en gran medida del comando ENTRYPOINT. De forma predeterminada, los registros que se capturan muestran la salida del comando que aparecería normalmente en un terminal interactivo si el contenedor se ejecutara localmente, que son los flujos de E/S STDOUT y STDERR. El controlador deawslogs registro simplemente transfiere estos registros de Docker aCloudWatch Logs. Para obtener más información acerca de cómo se procesan los registros de Docker, incluidas formas alternativas de capturar diferentes datos de archivo o flujos, consulte la página sobre cómo ver los registros de un contenedor o servicio en la documentación de Docker.

Para enviar registros del sistema desde las instancias de contenedor de Amazon ECS aCloudWatch Logs, consulteMonitoreo de instancias de contenedor. Para obtener más información sobreCloudWatch los registros, consulte Supervisión de los archivos de registro y las cuotas deCloudWatch registros en la Guía del usuario de AmazonCloudWatch Logs.

Activación del controlador de registros awslogs para los contenedores

Si utiliza el tipo de lanzamiento de Fargate para las tareas, debe agregar los parámetros logConfiguration necesarios a la definición de tareas para activar el controlador de registros awslogs. Para obtener más información, consulte Especificación de una configuración de registro en la definición de tarea.

Si utiliza el tipo de lanzamiento de EC2 para las tareas y desea activar el controlador de registros awslogs, las instancias de contenedor de Amazon ECS requieren al menos la versión 1.9.0 del agente de contenedor. Para obtener información acerca de cómo comprobar la versión del agente y actualizar a la versión más reciente, consulte Actualización del agente de contenedor de Amazon ECS.

nota

Si no está utilizando la AMI optimizada para Amazon ECS (con al menos la versión 1.9.0-1 del paquete ecs-init) para las instancias de contenedor, también tiene que especificar que el controlador de registros awslogs esté disponible en la instancia de contenedor al iniciar el agente utilizando la siguiente variable de entorno en la instrucción docker run o el archivo de variables de entorno. Para obtener más información, consulte Instalación del agente de contenedor de Amazon ECS.

ECS_AVAILABLE_LOGGING_DRIVERS='["json-file","awslogs"]'

Las instancias de contenedor de Amazon ECS también requieren el permiso logs:CreateLogStream y logs:PutLogEvents en el rol de IAM con el que se pueden lanzar las instancias de contenedor. Si creó el rol de instancia de contenedor de Amazon ECS antes de que se habilitara la compatibilidad con el controlador de registros awslogs en Amazon ECS, es posible que tenga que agregar este permiso. El ecsTaskExecutionRole se utiliza cuando se asigna a la tarea y probablemente contenga los permisos correctos. Para obtener información sobre verificar el rol de ejecución de tareas, consulte Comprobación del rol de ejecución de tareas (ecsTaskExecutionRole) en la consola de IAM. Si las instancias de contenedor utilizan la política de IAM administrada para instancias de contenedor, probablemente tengan los permisos correctos. Para obtener información acerca de cómo verificar el rol de instancia de contenedor de Amazon ECS y adjuntar la política de IAM administrada para instancias de contenedor, consulte Comprobación de la instancia de contenedor (ecsInstanceRole) en la consola de IAM.

Creación de un grupo de registros

El controlador deawslogs registros puede enviar flujos de registros a un grupo deCloudWatch registros existente en Logs o puede crear un nuevo grupo de registro en su nombre. La AWS Management Console proporciona una opción de configuración automática que crea un grupo de registro en su nombre mediante el nombre de familia de definición de tareas con ecs como prefijo. De forma alternativa, puede especificar manualmente las opciones de configuración de registros y especificar la opción awslogs-create-group con un valor de true que crea los grupos de registros en su nombre.

nota

Para utilizar laawslogs-create-group opción de crear el grupo de registros, la política de rol de IAM de ejecución de tareas o la política de rol de instancia de EC2 deben incluir ellogs:CreateLogGroup permiso.

En el código siguiente se muestra cómo establecer la opción awslogs-create-group.

{
    "containerDefinitions": [
        {
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "firelens-container",
                    "awslogs-region": "us-west-2",
                    "awslogs-create-group": "true",
                    "awslogs-stream-prefix": "firelens"
                }
            }
}

Uso de la característica de configuración automática para crear un grupo de registros

Al registrar una definición de tarea, en la consola de Amazon ECS, puede permitir que Amazon ECS configure automáticamenteCloudWatch los registros. Esto hace que se cree un grupo de registro en su nombre mediante el nombre de familia de definición de tareas con ecs como prefijo. Para obtener más información, consulte Creación de una definición de tareas con la consola.

Opciones disponibles del controlador de registros awslogs

El controlador de registros awslogs admite las siguientes opciones en las definiciones de tareas de Amazon ECS: Para obtener más información, consulte Controlador deCloudWatch registros.

awslogs-create-group

Obligatorio: no

Especifique si desea que el grupo de registro se cree automáticamente. Si no se especifica esta opción, el valor predeterminado es false.

nota

Su política de IAM debe incluir el permiso logs:CreateLogGroup antes de intentar utilizar awslogs-create-group.

awslogs-region

Obligatorio: sí

Especifique la Región de AWS a la que el controlador de registro awslogs enviará los registros de Docker. Puede elegir enviar todos los registros desde clústeres de diferentes regiones a una única región deCloudWatch Registros. Esto es para que todos sean visibles en una sola ubicación. De lo contrario, puede separarlos por región para obtener un mayor grado de detalle. Asegúrese de que el grupo de registro especificado exista en la región que especifique con esta opción.

awslogs-group

Obligatorio: sí

Asegúrese de especificar un grupo de registro al que el controlador de registros awslogs envíe sus flujos de registros. Para obtener más información, consulte Creación de un grupo de registros.

awslogs-stream-prefix

Obligatorio: Opcional cuando se utiliza el tipo de lanzamiento de EC2, obligatorio para el tipo de lanzamiento de Fargate.

Utilice esta opción awslogs-stream-prefix para asociar un flujo de registro con el prefijo especificado, el nombre del contenedor y el ID de la tarea de Amazon ECS a la que pertenece el contenedor. Si especifica un prefijo con esta opción, el flujo de registro adopta el siguiente formato.

prefix-name/container-name/ecs-task-id

Si no especifica un prefijo con esta opción, el flujo de registro se nombra según el ID del contenedor que asigna el daemon de Docker en la instancia de contenedor. Dado que es difícil realizar un seguimiento de los registros hasta el contenedor que los envió solo con el ID de contenedor de Docker (que solo está disponible en la instancia de contenedor), le recomendamos que especifique un prefijo con esta opción.

En el caso de los servicios de Amazon ECS, puede utilizar el nombre del servicio como prefijo. De este modo, puede realizar un seguimiento de flujos de registros hasta el servicio al que pertenece el contenedor, el nombre del contenedor que los envió y el ID de la tarea a la que pertenece el contenedor.

Debe especificar un prefijo de flujo para los registros para que aparezcan en el panel de registros al utilizar la consola de Amazon ECS.

awslogs-datetime-format

Obligatorio: no

Esta opción define un patrón de inicio de varias líneas en formato strftime de Python. Un mensaje de registro consta de una línea que coincide con el patrón y de líneas siguientes que no coinciden con el patrón. La línea coincidente es el delimitador entre los mensajes de registro.

Un ejemplo de caso de uso de este formato es para analizar la salida como un volcado de pila, que de lo contrario podría registrarse en varias entradas. El patrón correcto permite capturarla en una sola entrada.

Para obtener más información, consulte awslogs-datetime-format.

No puede configurar las opciones awslogs-datetime-format y awslogs-multiline-pattern a la vez.

nota

El registro de varias líneas realiza análisis de las expresiones regulares y correspondencia de todos los mensajes de registro. Esto puede tener un impacto negativo sobre el rendimiento de registro.

awslogs-multiline-pattern

Obligatorio: no

Esta opción define un patrón de inicio de varias líneas que utiliza una expresión regular. Un mensaje de registro consta de una línea que coincide con el patrón y de líneas siguientes que no coinciden con el patrón. La línea coincidente es el delimitador entre los mensajes de registro.

Para obtener más información, consulte awslogs-multiline-pattern.

Esta opción se pasa por alto si también se ha configurado awslogs-datetime-format.

No puede configurar las opciones awslogs-datetime-format y awslogs-multiline-pattern a la vez.

nota

El registro de varias líneas realiza análisis de las expresiones regulares y correspondencia de todos los mensajes de registro. Esto puede tener un impacto negativo sobre el rendimiento de registro.

mode

Obligatorio: no

Valores válidos: non-blocking | blocking

Valor predeterminado: blocking

El modo de entrega de los mensajes de registro desde el contenedor a awslogs. Para obtener más información, consulte Configuración de los controladores de registros.

max-buffer-size

Obligatorio: no

Valor predeterminado: 1m

Cuando se utiliza el modo non-blocking, la opción de registro max-buffer-size controla el tamaño del búfer de anillo que se utiliza para el almacenamiento intermedio de mensajes.

Especificación de una configuración de registro en la definición de tarea

Antes de que los contenedores puedan enviar registros a CloudWatch, debe especificar el controlador de registros awslogs para los contenedores en la definición de tarea. Esta sección describe la configuración de registros para un contenedor para utilizar el controlador de registro awslogs. Para obtener más información, consulte Creación de una definición de tareas con la consola.

El JSON de definición de tareas a continuación tiene un objeto logConfiguration especificado para cada contenedor. Uno es para elWordPress contenedor que envía registros a un grupo de registro denominadoawslogs-wordpress. El otro es para un contenedor MySQL que envía registros a un grupo de registro denominado awslogs-mysql. Ambos contenedores utilizan el prefijo de flujo de registros awslogs-example.

{
    "containerDefinitions": [
        {
            "name": "wordpress",
            "links": [
                "mysql"
            ],
            "image": "wordpress",
            "essential": true,
            "portMappings": [
                {
                    "containerPort": 80,
                    "hostPort": 80
                }
            ],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-create-group": "true",
                    "awslogs-group": "awslogs-wordpress",
                    "awslogs-region": "us-west-2",
                    "awslogs-stream-prefix": "awslogs-example"
                }
            },
            "memory": 500,
            "cpu": 10
        },
        {
            "environment": [
                {
                    "name": "MYSQL_ROOT_PASSWORD",
                    "value": "password"
                }
            ],
            "name": "mysql",
            "image": "mysql",
            "cpu": 10,
            "memory": 500,
            "essential": true,
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-create-group": "true",
                    "awslogs-group": "awslogs-mysql",
                    "awslogs-region": "us-west-2",
                    "awslogs-stream-prefix": "awslogs-example"
                }
            }
        }
    ],
    "family": "awslogs-example"
}

Después de haber registrado una definición de tareas con el controlador deawslogs registros en una configuración de registros de definición de contenedor, puede ejecutar una tarea o crear un servicio con dicha definición de tarea para empezar a enviarCloudWatch registros a Logs. Para obtener más información, consulte Ejecución de una tarea independiente en la consola clásica de Amazon ECS y Creación de un servicio de Amazon ECS en la consola clásica.

Visualización de registros de contenedor de awslogs enCloudWatch Logs

En el caso de tareas que utilizan el tipo de lanzamiento de EC2, una vez que el rol de instancia de contenedor tenga los permisos adecuados para enviarCloudWatch registros a Logs, los agentes de contenedor se actualicen al menos a la versión 1.9.0 y se haya configurado e iniciado una tarea con contenedores que utilicen elawslogs controlador deCloudWatch registros, los contenedores configurados deberían enviar sus datos de registro a Logs. Puede consultar y buscar estos registros en la consola.

Para verCloudWatch los datos de los registros de un contenedor desde la consola de Amazon ECS

1. Abra la consola en https://console.aws.amazon.com/ecs/v2.

2. En la página Clusters, seleccione el clúster que contiene la tarea que desea ver.

3. En la página Cluster: cluster_name, elija Tareas y, a continuación, seleccione la tarea que desee ver.

4. En la página Tarea: task_id, en Detalles del contenedor, elija Configuración de registro para ver los registros.

5. En la sección Log Configuration , seleccione View logs in CloudWatch, que abre la secuencia de registro asociada en la consola de CloudWatch.

Para verCloudWatch los datos de tus registros en laCloudWatch consola

1. Abra la consola de CloudWatch en https://console.aws.amazon.com/cloudwatch/.

2. En el panel de navegación izquierdo, elija Logs (Registros).

3. Seleccione un grupo de registros que desea ver. Debería ver los grupos de registros que haya creado en Creación de un grupo de registros.

4. Elija el flujo de registros que desea ver.