Referência do agente do CloudWatch Logs

Importante

Esta referência se aplica ao agente do CloudWatch Logs, defasado mais antigo. Se você usar o Instance Metadata Service Version 2 (IMDSv2), deverá usar o novo agente unificado do CloudWatch. Se você não estiver usando o IMDSv2, recomendamos utilizar a versão mais recente do agente unificado do CloudWatch em vez do agente de logs mais antigo. Para obter mais informações sobre o agente unificado mais recente, consulte Coleta de métricas e logs de instâncias do Amazon EC2 e servidores on-premises com o agente do CloudWatch.

Para obter informações sobre como migrar do agente mais antigo do CloudWatch Logs para o agente unificado, consulte Criar o arquivo de configuração do agente do CloudWatch com o assistente.

O agente do CloudWatch Logs oferece uma forma automatizada de enviar dados de log ao CloudWatch Logs de instâncias do Amazon EC2. O agente inclui os seguintes componentes:

• Um plugin para a AWS CLI que envia dados de log para o CloudWatch Logs.

• Um script (daemon) que inicia o processo para enviar dados por push ao CloudWatch Logs.

• Um trabalho cron que garante que o daemon esteja sempre em execução.

Arquivo de configuração do agente

O arquivo de configuração do agente do CloudWatch Logs descreve informações necessárias para o agente do CloudWatch Logs. A seção [general] do arquivo de configuração do agente define configurações comuns que se aplicam a todos os streams de log. A seção [logstream] define as informações necessárias para enviar um arquivo local para um stream de logs remoto. Você pode ter mais de uma seção [logstream], mas cada uma deve ter um nome exclusivo dentro do arquivo de configuração, por exemplo, [logstream1], [logstream2] e assim por diante. O valor [logstream] junto com a primeira linha de dados no arquivo de log definem a identidade do arquivo de log.

[general]
state_file = value
logging_config_file = value
use_gzip_http_content_encoding = [true | false]

[logstream1]
log_group_name = value
log_stream_name = value
datetime_format = value
time_zone = [LOCAL|UTC]
file = value
file_fingerprint_lines = integer | integer-integer
multi_line_start_pattern = regex | {datetime_format}
initial_position = [start_of_file | end_of_file]
encoding = [ascii|utf_8|..]
buffer_duration = integer
batch_count = integer
batch_size = integer

[logstream2]
...

state_file

Especifica onde o arquivo de estado está armazenado.

logging_config_file

(Opcional) Especifica a localização do arquivo de configuração de log do agente. Se você não especifica um arquivo de configuração de log do agente aqui, o arquivo padrão awslogs.conf é usado. A localização do arquivo padrão é /var/awslogs/etc/awslogs.conf se você instalou o agente com um script, e /etc/awslogs/awslogs.conf se você instalou o agente com RPM. O arquivo está no formato de arquivo de configuração Python (https://docs.python.org/2/library/logging.config.html#logging-config-fileformat). Registradores com os seguintes nomes podem ser personalizados.

cwlogs.push
cwlogs.push.reader
cwlogs.push.publisher
cwlogs.push.event
cwlogs.push.batch
cwlogs.push.stream
cwlogs.push.watcher

O exemplo a seguir altera o nível de leitor e editor para AVISO enquanto o valor padrão é INFO.

[loggers]
keys=root,cwlogs,reader,publisher
            
[handlers]
keys=consoleHandler
            
[formatters]
keys=simpleFormatter
           
[logger_root]
level=INFO
handlers=consoleHandler
            
[logger_cwlogs]
level=INFO
handlers=consoleHandler
qualname=cwlogs.push
propagate=0
            
[logger_reader]
level=WARNING
handlers=consoleHandler
qualname=cwlogs.push.reader
propagate=0
            
[logger_publisher]
level=WARNING
handlers=consoleHandler
qualname=cwlogs.push.publisher
propagate=0
            
[handler_consoleHandler]
class=logging.StreamHandler
level=INFO
formatter=simpleFormatter
args=(sys.stderr,)
            
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(process)d - %(threadName)s - %(message)s

use_gzip_http_content_encoding

Quando definido como true (padrão), permite que a codificação de conteúdo gzip http envie cargas úteis compactadas para o CloudWatch Logs. Isso reduz o uso da CPU, reduz o NetworkOut e diminui a latência. Para desativar este recurso, adicione use_gzip_http_content_encoding = false à seção [general]do arquivo de configuração do agente do CloudWatch Logs e reinicie o agente.

nota

Essa configuração só está disponível no awscli-cwlogs versão 1.3.3 e posterior.

log_group_name

Especifica o grupo de logs de destino. Um grupo de logs é criado automaticamente, caso ele ainda não exista. Os nomes de grupos de log podem ter entre 1 e 512 caracteres. Os caracteres permitidos incluem a-z, A-Z, 0-9, "_" (sublinhado), "-" (hífen), "/" (barra) e "." (ponto).

log_stream_name

Especifica o stream de logs de destino. Você pode usar uma cadeia de caracteres literal ou as variáveis predefinidas ({instance_id}, {hostname}, {ip_address}) ou uma combinação de ambas, para definir um nome de stream de log. Um stream de logs é criado automaticamente, caso ele ainda não exista.

datetime_format

Especifica como o carimbo de data e hora é extraído de logs. O timestamp é usado para recuperar eventos de log e gerar métricas. A hora atual será usada para todos os eventos de log se datetime_format não for fornecido. Se o valor datetime_format fornecido for inválido para uma determinada mensagem de log, o carimbo de data e hora do último evento de log com um carimbo de data/hora analisado com êxito será usado. Se não existir nenhum evento de log anterior, a hora atual será usada.

Os códigos datetime_format comuns estão listados a seguir. Você também pode usar qualquer código datetime_format compatíveis com Python, datetime.strptime(). O desvio de fuso horário (%z) também é compatível, embora não seja suportado até o python 3.2, [+ -] HHMM sem dois-pontos (:). Para obter mais informações, consulte strftime() and strptime() Behavior.

%y: ano sem século preenchido como um número decimal preenchido com zeros. 00, 01, ..., 99

%Y: ano com século como número decimal.1970, 1988 2001, 2013

%b: mês como nome abreviado do local. Jan, Fev, ..., Dez (en_US);

%B: mês como nome completo do local. Janeiro, fevereiro,..., dezembro (en_US);

%m: mês como um número decimal preenchido com zeros. 01, 02, ..., 12

%d: dia do mês como um número decimal preenchido com zeros. 01, 02, ..., 31

%H: hora (formato de 24 horas) como um número decimal preenchido com zeros. 00, 01, ..., 23

%I: hora (formato de 12 horas) como um número decimal preenchido com zeros. 01, 02, ..., 12

%p: equivalente de local de AM ou PM.

%M: minuto como um número decimal preenchido com zeros. 00, 01, ..., 59

%S: segundo como um número decimal preenchido com zeros. 00, 01, ..., 59

%f: microssegundo como um número decimal preenchido com zeros à esquerda. 000000, ..., 999999

%z: deslocamento de UTC na forma+HHMM ou -HHMM. +0000, -0400, +1030

Exemplo de formatos:

Syslog: '%b %d %H:%M:%S', e.g. Jan 23 20:59:29

Log4j: '%d %b %Y %H:%M:%S', e.g. 24 Jan 2014 05:00:00

ISO8601: '%Y-%m-%dT%H:%M:%S%z', e.g. 2014-02-20T05:20:20+0000

time_zone

Especifica o fuso horário do carimbo de data e hora do evento de log. Os dois valores suportados são UTC e LOCAL. O padrão é LOCAL, que será usado se o fuso horário não puder ser considerado com base em datetime_format.

file

Especifica os arquivos de log que você deseja enviar para o CloudWatch Logs. O arquivo pode apontar para um arquivo específico ou vários arquivos (usando curingas como /var/log/system.log*). Somente o arquivo mais recente é enviado ao CloudWatch Logs com base no tempo de modificação do arquivo. Recomendamos usar caracteres curinga para especificar uma série de arquivos do mesmo tipo, como access_log.2014-06-01-01, access_log.2014-06-01-02, etc., mas não vários tipos de arquivos, como access_log_80 e access_log_443. Para especificar vários tipos de arquivos, adicione outra entrada de stream de log ao arquivo de configuração para que cada tipo de arquivo de log vá para um stream de log diferente. Arquivos compactados não têm suporte.

file_fingerprint_lines

Especifica o intervalo de linhas para identificar um arquivo. Os valores válidos são um ou dois números delimitados por traço, como "1", "2-5". O valor padrão é "1" para que a primeira linha seja usada para calcular a impressão digital. As linhas de impressão digital não são enviadas ao CloudWatch Logs a menos que todas as linhas especificadas estejam disponíveis.

multi_line_start_pattern

Especifica o padrão para identificar o início de uma mensagem de log. Uma mensagem de log é feita de uma linha em conformidade com o padrão e as seguintes linhas que não correspondem ao padrão. Os valores válidos são expressão regular ou {datetime_format}. Ao usar {datetime_format}, a opção datetime_format deve ser especificada. O valor padrão é "^ [^\s]" para que qualquer linha que comece com um caractere diferente de espaço feche a mensagem de log anterior e inicie uma nova mensagem de log.

initial_position

Especifica onde começar a ler dados (start_of_file ou end_of_file). O padrão é start_of_file. É usado somente se não há estado persistente para esse stream de logs.

encoding

Especifica a codificação do arquivo de log para que o arquivo possa ser lido corretamente. O padrão é utf_8. As codificações suportadas pelo codecs.decode () Python podem ser usadas aqui.

Atenção

A especificação incorreta da codificação pode causar a perda de dados porque os caracteres que não podem ser decodificados são substituídos por algum outro caractere.

Veja a seguir algumas codificações comuns:

ascii, big5, big5hkscs, cp037, cp424, cp437, cp500, cp720, cp737, cp775, cp850, cp852, cp855, cp856, cp857, cp858, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, cp874, cp875, cp932, cp949, cp950, cp1006, cp1026, cp1140, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, cp1257, cp1258, euc_jp, euc_jis_2004, euc_jisx0213, euc_kr, gb2312, gbk, gb18030, hz, iso2022_jp, iso2022_jp_1, iso2022_jp_2, iso2022_jp_2004, iso2022_jp_3, iso2022_jp_ext, iso2022_kr, latin_1, iso8859_2, iso8859_3, iso8859_4, iso8859_5, iso8859_6, iso8859_7, iso8859_8, iso8859_9, iso8859_10, iso8859_13, iso8859_14, iso8859_15, iso8859_16, johab, koi8_r, koi8_u, mac_cyrillic, mac_greek, mac_iceland, mac_latin2, mac_roman, mac_turkish, ptcp154, shift_jis, shift_jis_2004, shift_jisx0213, utf_32, utf_32_be, utf_32_le, utf_16, utf_16_be, utf_16_le, utf_7, utf_8, utf_8_sig

buffer_duration

Especifica o intervalo de tempo para o processamento em lote de eventos de log. O valor mínimo é 5000 ms e valor padrão é 5000 ms.

batch_count

Especifica o número máximo de eventos de log em um lote, até 10.000. O valor padrão é 10000.

batch_size

Especifica o tamanho máximo de eventos de log em um lote, em bytes, até 1.048.576 bytes. O valor de padrão é de 1048576 bytes. Esse tamanho é calculado como a soma de todas as mensagens de evento em UTF-8, mais 26 bytes para cada evento de log.

Como usar o agente do CloudWatch Logs com proxies HTTP

Você pode usar o agente do CloudWatch Logs com proxies HTTP.

nota

Os proxies HTTP são suportados no awslogs-agent-setup.py versão 1.3.8 ou posterior.

Para usar o agente do CloudWatch Logs com proxies HTTP

1. Faça um dos seguintes procedimentos:

   1. Para uma nova instalação do agente do CloudWatch Logs, execute os seguintes comandos:

      curl https://s3.amazonaws.com/aws-cloudwatch/downloads/latest/awslogs-agent-setup.py -O

      sudo python awslogs-agent-setup.py --region us-east-1 --http-proxy http://your/proxy --https-proxy http://your/proxy --no-proxy 169.254.169.254

      Para manter o acesso ao serviço de metadados do Amazon EC2 em instâncias do EC2, use --no-proxy 169.254.169.254 (recomendado). Para obter mais informações, consulte Metadados de instância e dados do usuário no Guia do usuário do Amazon EC2 para instâncias do Linux.

      Nos valores de http-proxy e https-proxy, você especifica a URL completa.

   2. Para uma instalação existente do agente do CloudWatch Logs, edite /var/awslogs/etc/proxy.conf e adicione seus proxies:

      HTTP_PROXY=
      HTTPS_PROXY=
      NO_PROXY=

2. Reinicie o agente para que as alterações sejam aplicadas:

   sudo service awslogs restart

   Se você está usando o Amazon Linux 2, use o seguinte comando para reiniciar o agente:

   sudo service awslogsd restart

Compartimentalização de arquivos de configuração do agente do CloudWatch Logs

Se você estiver usando o awslogs-agent-setup.py versão 1.3.8 ou posterior com o awscli-cwlogs 1.3.3 ou posterior, poderá importar diferentes configurações de fluxo para vários componentes de forma independente entre si por meio da criação de arquivos de configuração adicionais no diretório /var/awslogs/etc/config/. Quando o agente do CloudWatch Logs é iniciado, ele inclui todas as configurações de fluxo nesses arquivos de configuração adicionais. As propriedades de configuração na seção [general] devem ser definidas no arquivo de configuração principal (/var/awslogs/etc/awslogs.conf) e são ignoradas em todos os arquivos de configuração adicionais encontrados em /var/awslogs/etc/config/.

Se você não tem um diretório /var/awslogs/etc/config/, pois o agente foi instalado com RPM, use o /etc/awslogs/config/ no lugar dele.

Reinicie o agente para que as alterações sejam aplicadas:

sudo service awslogs restart

Se você está usando o Amazon Linux 2, use o seguinte comando para reiniciar o agente:

sudo service awslogsd restart

Perguntas frequentes do agente do CloudWatch Logs

Quais tipos de rotações de arquivos são compatíveis?

Os mecanismos de rotação de arquivos a seguir são suportados:

• Renomear arquivos de log existentes com um sufixo numérico e, em seguida, recriar o arquivo de log original em branco. Por exemplo, /var/log/syslog.log é renomeado como /var/log/syslog.log.1. Se /var/log/syslog.log.1 já existir de uma rotação anterior, ele será renomeado como /var/log/syslog.log.2.

• Truncando o arquivo de log original após a criação de uma cópia. Por exemplo, /var/log/syslog.log é copiado em /var/log/syslog.log.1 e /var/log/syslog.log é truncado. Pode haver perda de dados nesse caso, então, tome cuidado ao usar esse mecanismo de rotação de arquivos.

• Criando um novo arquivo com um padrão comum como o antigo. Por exemplo, /var/log/syslog.log.2014-01-01 permanece e /var/log/syslog.log.2014-01-02 é criado.

A impressão digital (ID de origem) do arquivo é calculada aplicando hash à chave de stream de logs e à primeira linha do conteúdo do arquivo. Para substituir esse comportamento, a opção file_fingerprint_lines pode ser usada. Quando a rotação de arquivos acontece, o novo arquivo deve ter um novo conteúdo e o arquivo antigo não deve ter conteúdo anexado; o agente envia o novo arquivo depois de ler o arquivo antigo.

Como posso determinar qual versão do agente estou usando?

Caso tenha usado um script de configuração para instalar o agente do CloudWatch Logs, você poderá usar o /var/awslogs/bin/awslogs-version.sh para verificar que versão do agente que está usando. Ele imprime a versão do agente e suas principais dependências. Se você tiver usado o yum para instalar o agente do CloudWatch Logs, poderá usar “yum info awslogs” e “yum info aws-cli-plugin-cloudwatch-logs” para verificar a versão do agente do CloudWatch Logs e o plugin.

Como ficam as entradas de log convertidas em eventos de log?

Os eventos de log contêm duas propriedades: o carimbo de data e hora de quando o evento ocorreu, e a mensagem de log bruta. Por padrão, qualquer linha que comece com um caractere diferente de espaço fecha a mensagem de log anterior, se houver, e inicia uma nova mensagem de log. Para substituir este comportamento, o multi_line_start_pattern pode ser usado, e qualquer linha que esteja em conformidade com o padrão inicia uma nova mensagem de log. O padrão pode ser qualquer regex ou "{datetime_format}". Por exemplo, se a primeira linha de cada mensagem de log contiver um carimbo de data/hora, como '2014-01-02T13:13:01Z', o multi_line_start_pattern poderá ser definido como '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z'. Para simplificar a configuração, a variável ‘{datetime_format}' poderá ser usada se a variável datetime_format option for especificada. Para o mesmo exemplo, se datetime_format estiver definido como '%Y-%m-%dT%H:%M:%S%z', então multi_line_start_pattern poderá ser simplesmente '{datetime_format}'.

A hora atual será usada para todos os eventos de log se datetime_format não for fornecido. Se datetime_format fornecido for inválido para uma determinada mensagem de log, será usado o carimbo de data e hora do último evento de log com um carimbo de data/hora analisado com êxito. Se não existir nenhum evento de log anterior, a hora atual será usada. Uma mensagem de aviso é registrada quando um evento de log retorna para a hora atual ou a hora do evento de log anterior.

Os carimbos de data e hora são usados para recuperar eventos de log e gerar métricas, portanto, se você especificar o formato incorreto, os eventos de log poderão se tornar não recuperáveis e gerar métricas incorretas.

Como os eventos de log são armazenadas em lote?

Um lote fica cheio e é publicado quando qualquer uma das seguintes condições é atendida:

1. O tempo de buffer_duration terminou desde que o primeiro evento de log foi adicionado.

2. Menos do que batch_size de eventos de log foram acumulados, mas adicionar o novo evento de log excede o batch_size.

3. O número de eventos de log atingiu batch_count.

4. Os eventos de log do lote não abrangem mais do que 24 horas, mas adicionar o novo evento de log excede a restrição de 24 horas.

O que faz com que entradas de log, eventos de log ou lotes sejam ignorados ou truncados?

Para acompanhar a restrição da operação PutLogEvents, os seguintes problemas podem fazer com que um evento de log ou lote seja ignorado.

nota

O agente do CloudWatch Logs grava um aviso em seu log quando os dados são ignorados.

1. Se o tamanho de um evento de log exceder 256 KB, ele será ignorado completamente.

2. Se o carimbo de data e hora do evento de log for de mais do que 2 horas no futuro, o evento de log será ignorado.

3. Se o carimbo de data e hora do evento de log for de mais do que 14 dias no passado, o evento de log será ignorado.

4. Se qualquer evento de log for mais antigo do que o período de retenção do grupo de logs, o lote inteiro será ignorado.

5. Se o lote de eventos de log em uma única solicitação PutLogEvents abranger mais de 24 horas, ocorrerá falha na operação PutLogEvents.

A interrupção do agente causa perda/duplicações de dados?

Não, desde que o arquivo de estado esteja disponível e nenhuma rotação de arquivos tenha ocorrido desde a última execução. O agente do CloudWatch Logs pode começar de onde parou e continuar a enviar os dados de log.

Posso apontar arquivos de log diferentes do mesmo host ou de hosts diferentes para o mesmo stream de logs?

A configuração de várias fontes de log para enviar dados a um único stream de logs não é suportada.

Quais chamadas de API o agente pode fazer (ou quais ações devo adicionar à minha política do IAM)?

O agente do CloudWatch Logs necessita das operações CreateLogGroup, CreateLogStream, DescribeLogStreams e PutLogEvents. Se você estiver usando o agente mais recente, o DescribeLogStreams não será necessário. Consulte o exemplo de política do IAM a seguir.

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

Não quero que o agente do CloudWatch Logs crie grupos de logs nem fluxos de logs automaticamente. Como posso impedir que o agente recrie grupos e fluxos de log?

Em sua política do IAM, é possível restringir o agente apenas às seguintes operações: DescribeLogStreams, PutLogEvents.

Antes de revogar as permissões CreateLogGroup e CreateLogStream do agente, certifique-se de criar os grupos de log e fluxos de log que você deseja que o agente use. O agente de logs não pode criar fluxos de log em um grupo de log que você criou, a menos que ele tenha as permissões CreateLogGroup e CreateLogStream.

Quais logs devo procurar ao solucionar problemas?

O log de instalação do agente está em /var/log/awslogs-agent-setup.log e o log do agente está em /var/log/awslogs.log.