Usar o driver de log awslogs - Amazon Elastic Container Service

Usar o driver de log awslogs

Você pode configurar os contêineres das tarefas para enviar informações de log ao CloudWatch Logs. Se você estiver usando o tipo de inicialização do Fargate para suas tarefas, isso permite que você visualize os logs 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 ajuda nos conceitos básicos de como usar o driver de log awslogs nas 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.

Habilitar o driver de log awslogs para contêineres

Se você estiver usando o tipo de inicialização do Fargateawslogs para suas tarefas, para habilitar o driver de log você só precisa adicionar os parâmetros logConfiguration necessários à definição de tarefa. Para obter 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 obter 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. 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 deverão ter 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 pode 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 criará 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.

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ê tem a opção de permitir que o Amazon ECS configure automaticamente os logs do CloudWatch. Essa opção cria um grupo de logs 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 doAmazon 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 obter 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

Exigido: Não

Especifique se você deseja que o grupo de logs seja criado automaticamente. Se esta 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 para a qual o driver de log awslogs deve enviar os logs do Docker. Você pode optar por enviar todos os logs a partir de clusters em regiões diferentes para uma única região no CloudWatch Logs, para que eles permaneçam todos visíveis em um local ou pode separá-los por região para mais detalhes. Certifique-se de que o grupo de logs especificado exista na região especificada com essa opção.

awslogs-group

Obrigatório: sim

Você deve especificar um grupo de logs para o qual o driver de log awslogs enviará os fluxos de log. Para obter 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.

A opção awslogs-stream-prefix permite 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, você pode usar o nome do serviço como o prefixo, o que permite que você rastreie fluxos de log 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

Exigido: 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. Assim, 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, o que pode ter um impacto negativo no desempenho do registro em log.

awslogs-multiline-pattern

Exigido: Não

Essa opção define um padrão inicial de várias linhas usando 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. Assim, 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 no desempenho do registro em log.

mode

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

Exigido: 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 obter mais informações, consulte . Criar uma definição de tarefa.

O JSON de definição da tarefa mostrado abaixo tem um objeto logConfiguration especificado para cada contêiner; um para o contêiner do WordPress que envia logs para um grupo de logs chamado awslogs-wordpress e um para um contêiner do MySQL que envia logs para um grupo de logs chamado 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-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-group": "awslogs-mysql", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "awslogs-example" } } } ], "family": "awslogs-example" }

No console do Amazon ECS, a configuração de log do contêiner wordpress é especificada conforme mostrado na imagem abaixo.


					Configuração do log do console

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