Usar o driver de log awslogs - Serviço Amazon Elastic Container

Usar o driver de log awslogs

Você pode configurar os contêineres das tarefas para enviar informações de log ao CloudWatch Logs. Se estiver usando o tipo de inicialização do Fargate para suas tarefas, você poderá visualizar os logs a partir dos seus contêineres. Se você estiver usando o tipo de inicialização do EC2, poderá visualizar logs diferentes dos contêineres em um local conveniente e evitar que os logs de contêiner ocupem espaço em disco nas instâncias do seu contêiner.Este tópico discute os conceitos básicos de como usar o driver de log awslogs em definições de tarefa.

nota

O tipo de informações registradas em log pelos contêineres em sua tarefa depende principalmente do comando ENTRYPOINT. Por padrão, os logs capturados mostram a saída do comando que você normalmente veria em um terminal interativo, se executasse o contêiner localmente, que são os fluxos de E/S STDOUT e STDERR. O driver de log awslogs simplesmente envia esses logs do Docker para o CloudWatch Logs. Para obter mais informações sobre como os logs do Docker são processados, incluindo maneiras alternativas de capturar fluxos ou dados de arquivos diferentes, consulte Visualizar logs de um contêiner ou serviço na documentação do Docker.

Para enviar logs de sistema a partir das instâncias de contêiner do Amazon ECS para o CloudWatch Logs, consulte Monitorar as instâncias de contêiner. Para obter mais informações sobre o CloudWatch Logs, consulte Monitorar arquivos de log e Cotas do CloudWatch Logs no Guia do usuário do Amazon CloudWatch Logs.

Ativação do driver de log awslogs para seus contêineres

Se você estiver usando o tipo de inicialização do Fargate para suas tarefas, precisará adicionar os parâmetros awslogs necessários à sua definição de tarefa para ativar o driver de log logConfiguration. Para mais informações, consulte Especificar uma configuração de log na definição de tarefa.

Se você estiver usando o tipo de inicialização do EC2 para suas tarefas e quer ativar o driver de log awslogs, suas instâncias de contêiner do Amazon ECS precisarão pelo menos da versão 1.9.0 do agente de contêiner. Para obter informações sobre como verificar a versão do agente e atualizar para a versão mais recente, consulte Atualizar o agente de contêiner do Amazon ECS.

nota

Caso não esteja usando a AMI otimizada para Amazon ECS (com pelo menos a versão 1.9.0-1 do pacote ecs-init) para as instâncias de contêiner, você também precisará especificar que o driver de registro awslogs está disponível na instância de contêiner quando iniciar o agente usando a variável de ambiente a seguir na declaração docker run ou no arquivo da variável de ambiente. Para mais informações, consulte Instalar o agente de contêiner do Amazon ECS.

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

As instâncias de contêiner do Amazon ECS também exigem permissão de logs:CreateLogStream e logs:PutLogEvents na função do IAM com a qual você inicia as instâncias de contêiner. Caso você tenha criado a função de instância de contêiner do Amazon ECS antes que o suporte ao driver de log awslogs tenha sido habilitado no Amazon ECS, talvez seja necessário adicionar essa permissão. A ecsTaskExecutionRole é usada quando é atribuída à tarefa e provavelmente contém as permissões corretas. Para obter informações sobre a verificação da sua função de execução de tarefas, consulte Para verificar a ecsTaskExecutionRole no console do IAM;. Se as instâncias de contêiner usarem a política do IAM gerenciada para instâncias de contêiner, as instâncias de contêiner terão provavelmente as permissões corretas. Para obter informações sobre como verificar a função de instância de contêiner do Amazon ECS e anexar a política gerenciada do IAM para instâncias de contêiner, consulte Para verificar a ecsInstanceRole no console do IAM;.

Criar um grupo de logs

O driver de log awslogs pode enviar fluxos de log para um grupo de logs existente no CloudWatch Logs ou criar um novo grupo de logs em seu nome. O AWS Management Console fornece uma opção de configuração automática que cria um grupo de logs em seu nome usando o nome da família de definição da tarefa com ecs como prefixo. Como alternativa, é possível especificar manualmente as opções de configuração de log e especificar a opção awslogs-create-group com um valor de true que cria os grupos de logs em seu nome.

nota

Para usar a opção awslogs-create-group para criar seu grupo de logs, sua política do IAM deve incluir a permissão logs:CreateLogGroup.

O código a seguir mostra como definir a opção 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" } } }

Usar o recurso de configuração automática para criar um grupo de logs

Ao registrar uma definição de tarefa no console do Amazon ECS, você pode permitir que o Amazon ECS configure automaticamente os logs do CloudWatch. Isso faz com que um grupo de logs seja criado em seu nome usando o nome da família de definição da tarefa com ecs como prefixo.

Para usar a opção de configuração automática do grupo de logs no console do Amazon ECS

  1. Abra o console do Amazon ECS em https://console.aws.amazon.com/ecs/.

  2. No painel de navegação à esquerda, escolha Task Definitions, Create new Task Definition.

  3. Escolha suas opções de compatibilidade e selecione Next Step (Próxima etapa).

  4. Escolha Add container.

  5. Na seção Storage and Logging (Armazenamento e registro em log), em Log configuration (Configuração de log), selecione Auto-configure CloudWatch Logs (Configurar o CloudWatch Logs automaticamente).

  6. Insira as opções do driver de logs awslogs. Para mais informações, consulte Especificar uma configuração de log na definição de tarefa.

  7. Preencha o restante do assistente de definição de tarefas.

Opções disponíveis do driver de log awslogs

O driver de log awslogs oferece suporte às seguintes opções em definições de tarefa do Amazon ECS. Para obter mais informações, consulte Driver de registro do CloudWatch Logs.

awslogs-create-group

Obrigatório: não

Especifique se você deseja que o grupo de logs seja criado automaticamente. Se essa opção não for especificada, o padrão será false.

nota

Sua política do IAM deve incluir a permissão logs:CreateLogGroup antes que você tente usar awslogs-create-group.

awslogs-region

Obrigatório: sim

Especifique a Região da AWS para a qual o driver de log do awslogs deve enviar seus logs do Docker. É possível optar por enviar todos os logs de clusters em regiões distintas para uma única região no CloudWatch Logs. Isso tem o objetivo de fazer com que todos fiquem visíveis em um único local. Caso contrário, você pode separá-los por região para mais granularidade. Certifique-se de que o grupo de logs especificado exista na região especificada com essa opção.

awslogs-group

Obrigatório: sim

Certifique-se de especificar um grupo de logs para o qual o driver de log do awslogs envia seus fluxos de logs. Para mais informações, consulte Criar um grupo de logs.

awslogs-stream-prefix

Obrigatório: Opcional para o tipo de inicialização do EC2, obrigatório para o tipo de inicialização do Fargate.

Use a opção awslogs-stream-prefix para associar um fluxo de log ao prefixo especificado, ao nome do contêiner e ao ID da tarefa do Amazon ECS à qual o contêiner pertence. Caso você especifique um prefixo com essa opção, o fluxo de log utiliza o seguinte formato.

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

Se você não especificar um prefixo com essa opção, o fluxo de log será nomeado depois que o ID do contêiner for atribuído pelo daemon do Docker na instância de contêiner. Como é difícil rastrear logs até o contêiner que os enviou apenas com o ID do contêiner do Docker (disponível apenas na instância de contêiner), recomendamos especificar um prefixo com essa opção.

Para serviços do Amazon ECS, é possível utilizar o nome do serviço como prefixo. Ao fazer isso, é possível rastrear fluxos de logs até o serviço ao qual o contêiner pertence, o nome do contêiner que os enviou e o ID da tarefa à qual o contêiner pertence.

Você deve especificar um stream-prefix para seus logs para fazer com que eles apareçam no painel Logs quando o console do Amazon ECS for usado.

awslogs-datetime-format

Obrigatório: não

Essa opção define um padrão de início de várias linhas no formato strftime em Python. Uma mensagem de log é formada por uma linha em conformidade com o padrão e as linhas seguintes que não correspondem ao padrão. A linha em conformidade é o delimitador entre as mensagens de log.

Um exemplo de um caso de uso para esse formato é a análise da saída, como um despejo de pilha, que poderia ser registrado em várias entradas. O padrão correto permite que ele seja capturado em uma única entrada.

Para obter mais informações, consulte awslogs-datetime-format.

Essa opção sempre terá precedência se os awslogs-datetime-format e awslogs-multiline-pattern estiverem configurados.

nota

O registro em várias linhas executa a análise da expressão regular e a correspondência de todas as mensagens de log. Isso pode ter um impacto negativo na performance do registro em log.

awslogs-multiline-pattern

Obrigatório: não

Essa opção define um padrão inicial de várias linhas que usa uma expressão regular. Uma mensagem de log é formada por uma linha em conformidade com o padrão e as linhas seguintes que não correspondem ao padrão. A linha em conformidade é o delimitador entre as mensagens de log.

Para obter mais informações, consulte awslogs-multiline-pattern.

Essa opção será ignorada se awslogs-datetime-format também estiver configurado.

nota

O registro em várias linhas executa a análise da expressão regular e a correspondência de todas as mensagens de log. Isso pode ter um impacto negativo na performance do registro em log.

mode

Obrigatório: não

Valores válidos: non-blocking | blocking

Valor padrão: blocking

O modo de entrega de mensagens de log do contêiner para o awslogs. Para obter mais informações, consulte Configurar drivers de registro.

max-buffer-size

Obrigatório: não

Valor padrão: 1m

Quando é usado o modo non-blocking, a opção de log max-buffer-size controla o tamanho do buffer de anel usado para armazenamento de mensagens intermediárias.

Especificar uma configuração de log na definição de tarefa

Para os contêineres enviarem logs ao CloudWatch, você deve especificar o driver de log awslogs para contêineres na definição de tarefa. Esta seção descreve a configuração de log para um contêiner usar o driver de log awslogs. Para mais informações, consulte Criação de uma definição de tarefa usando o novo console.

A definição de tarefa JSON a seguir tem um objeto logConfiguration especificado para cada contêiner. Um deles é para o contêiner do WordPress que envia logs a um grupo de logs denominado awslogs-wordpress. O outro é para um contêiner MySQL que envia logs a um grupo de logs denominado awslogs-mysql. Ambos os contêineres usam o prefixo de fluxo de log 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" }

Depois que tiver registrado uma definição de tarefa com o driver de log awslogs em uma configuração de log de definição de contêiner, você poderá executar uma tarefa ou criar um serviço com essa definição de tarefa para começar a enviar logs ao CloudWatch Logs. Para obter mais informações, consulte Executar uma tarefa autônoma e Criar um serviço do Amazon ECS.

Visualizarlogs de contêiner awslogs no CloudWatch Logs

Para tarefas que usam o tipo de inicialização do EC2, depois que a função da instância de contêiner tiver as permissões apropriadas para enviar logs ao CloudWatch Logs, os agentes de contêiner serão atualizados pelo menos para a versão 1.9.0 e você terá configurado e iniciado uma tarefa com contêineres que usam o driver de log awslogs e os contêineres configurados deverão enviar os dados de log ao CloudWatch Logs. Você pode visualizar e pesquisar esses logs no console.

Para visualizar os dados do CloudWatch Logs para um contêiner no console do Amazon ECS

  1. Abra o console do Amazon ECS em https://console.aws.amazon.com/ecs/.

  2. Na página Clusters, selecione o cluster que contém a tarefa a ser exibida.

  3. Na página Cluster: cluster_name,, escolha Tasks e selecione a tarefa a ser exibida.

  4. Na página Task: task_id, expanda a visualização de contêiner, escolhendo a seta para a esquerda do nome do contêiner.

  5. Na seção Configuração de log, escolha View logs in CloudWatch (Ver logs no CW), que abre o fluxo de logs associado no console do CloudWatch.

    
							Visualização de definição de tarefas da configuração de log

Para visualizar os dados do CloudWatch Logs no console do CloudWatch

  1. Abra o console do CloudWatch em https://console.aws.amazon.com/cloudwatch/.

  2. No painel de navegação esquerdo, selecione Logs.

  3. Selecione um grupo de logs para exibir. Você deve ver os grupos de logs criados em Criar um grupo de logs.

    
							Exibição de métricas do console do awslogs
  4. Escolha um stream de logs para visualizar.

    
							Exibição de métricas do console do awslogs