Solucionar problemas do atendente do CloudWatch

Use as seguintes informações para ajudar a solucionar problemas com o atendente do CloudWatch.

Parâmetros de linha de comando do atendente do CloudWatch

Para ver a lista completa de parâmetros compatíveis com o atendente do CloudWatch, insira o seguinte na linha de comando em um computador onde ele estiver instalado:

amazon-cloudwatch-agent-ctl -help

Falha ao instalar o atendente do CloudWatch usando o Run Command

Para instalar o atendente do CloudWatch usando o Systems Manager Run Command, o SSM Agent no servidor de destino deve ter a versão 2.2.93.0 ou posterior. Caso seu SSM Agent não esteja na versão correta, você poderá encontrar erros que incluem as seguintes mensagens:

no latest version found for package AmazonCloudWatchAgent on platform linux

failed to download installation package reliably

Para obter informações sobre como instalar ou atualizar a versão do SSM Agent, consulte Instalar e configurar o SSM Agent no Manual do usuário do AWS Systems Manager.

O atendente do CloudWatch não inicia

Se o atendente do CloudWatch falhar ao iniciar, pode haver um problema em sua configuração. As informações de configuração são registradas no arquivo configuration-validation.log. O arquivo está localizado em /opt/aws/amazon-cloudwatch-agent/logs/configuration-validation.log nos servidores Linux e em $Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\configuration-validation.log nos servidores que executam o Windows Server.

Verificar se o atendente do CloudWatch está em execução

Você pode consultar o atendente do CloudWatch para saber ele se está em execução ou se foi interrompido. Você pode usar o AWS Systems Manager para fazer isso remotamente. Também pode usar linha de comando, mas apenas para verificar um servidor local.

Para consultar o status do atendente do CloudWatch usando o Run Command

1. Abra o console do Systems Manager em https://console.aws.amazon.com/systems-manager/.

2. No painel de navegação, selecione Executar comando.

   - ou -

   Se a página inicial do AWS Systems Manager for exibida, role para baixo e escolha Explore Run Command.

3. Selecione Run command.

4. Na lista Documento de comando, selecione o botão ao lado de AmazonCloudWatch-ManageAgent.

5. Na lista Ação, escolha status.

6. Em Origem de configuração opcional escolha padrão e mantenha Local de configuração opcional em branco.

7. Na área Destino, selecione a instância a ser verificada.

8. Escolha Executar.

Se o atendente estiver em execução, a saída poderá ser semelhante ao seguinte.

{
       "status": "running",
       "starttime": "2017-12-12T18:41:18",
       "version": "1.73.4"
}

Se o atendente for interrompido, o campo "status" exibirá "stopped".

Para consultar o status do atendente do CloudWatch localmente usando a linha de comando

• Em um servidor Linux, digite o seguinte:

  sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -m ec2 -a status

  Em um servidor que executa o Windows Server, digite o seguinte em PowerShell como administrador:

  & $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a status

O atendente do CloudWatch não é iniciado e o erro menciona uma região do Amazon EC2

Se o atendente não for iniciado e a mensagem de erro mencionar um endpoint da região do Amazon EC2, talvez você tenha configurado o atendente de maneira que ele precise acessar o endpoint do Amazon EC2 sem conceder esse acesso.

Por exemplo, se você especificar um valor para o parâmetro append_dimensions no arquivo de configuração do atendente que depende dos metadados do Amazon EC2 e usar proxies, será necessário verificar se o servidor pode acessar o endpoint do Amazon EC2. Para obter mais informações sobre esses endpoints, consulte Amazon Elastic Compute Cloud (Amazon EC2) no Referência geral da Amazon Web Services.

O atendente do CloudWatch não inicia no Windows Server

No Windows Server, você poderá ver o seguinte erro:

Start-Service : Service 'Amazon CloudWatch Agent (AmazonCloudWatchAgent)' cannot be started due to the following
error: Cannot start service AmazonCloudWatchAgent on computer '.'.
At C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1:113 char:12
+     $svc | Start-Service
+            ~~~~~~~~~~~~~
    + CategoryInfo          : OpenError: (System.ServiceProcess.ServiceController:ServiceController) [Start-Service],
   ServiceCommandException
    + FullyQualifiedErrorId : CouldNotStartService,Microsoft.PowerShell.Commands.StartServiceCommand

Para corrigi-lo, primeiro verifique se o serviço do servidor está em execução. Esse erro pode ser visto se o atendente tentar iniciar quando o serviço do servidor não está em execução.

Se o serviço do servidor já estiver em execução, talvez o probema seja o descrito a seguir. Em algumas instalações do Windows Server, o atendente do CloudWatch leva mais de 30 segundos para iniciar. Como o Windows Server, por padrão, permite apenas 30 segundos para iniciar serviços, isso faz com que o atendente falhe com um erro semelhante ao seguinte:

Para corrigir esse problea, aumente o valor de tempo limite do serviço. Para obter mais informações, consulte Um serviço não começa, e os eventos 7000 e 7011 estão registrados no log de eventos do Windows.

Onde estão as métricas?

Se o atendente do CloudWatch estiver em execução, mas não for possível encontrar métricas coletadas por ele no AWS Management Console ou na AWS CLI, confirme se você está usando o namespace correto. Por padrão, o namespace para métricas coletado pelo atendente é CWAgent. Você pode personalizar o namespace usando o campo namespace na seção metrics do arquivo de configuração do atendente. Se você não vir as métricas esperadas, verifique o arquivo de configuração para confirmar o namespace que está sendo usado.

Quando você baixa o pacote do atendente do CloudWatch pela primeira vez, o arquivo de configuração do atendente é amazon-cloudwatch-agent.json. Esse arquivo está no diretório em que você executou o assistente de configuração ou pode ter sido transferido para um diretório diferente. Se você usar o assistente de configuração, a saída do arquivo de configuração do atendente será chamada de config.json. Para obter mais informações sobre o arquivo de configuração, incluindo o campo namespace, consulte Arquivo de configuração do atendente do CloudWatch: seção de métricas.

O atendente do CloudWatch leva muito tempo para ser executado em um contêiner ou registra um erro de limite de salto

Se você executar o atendente do CloudWatch como um serviço de contêiner e quiser adicionar dimensões métricas do Amazon EC2 a todas as métricas coletadas pelo atendente, poderá ver os seguintes erros na versão v1.247354.0 do atendente:

2022-06-07T03:36:11Z E! [processors.ec2tagger] ec2tagger: Unable to retrieve Instance Metadata Tags. This plugin must only be used on an EC2 instance.
2022-06-07T03:36:11Z E! [processors.ec2tagger] ec2tagger: Please increase hop limit to 2 by following this document https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-options.html#configuring-IMDS-existing-instances.
2022-06-07T03:36:11Z E! [telegraf] Error running agent: could not initialize processor ec2tagger: EC2MetadataRequestError: failed to get EC2 instance identity document
caused by: EC2MetadataError: failed to make EC2Metadata request
        status code: 401, request id: 
caused by:

Você poderá ver esse erro se o atendente tentar obter metadados de IMDSv2 dentro de um contêiner sem um limite de salto apropriado. Nas versões do atendente anteriores à v1.247354.0, você pode ter esse problema sem ver a mensagem de log.

Para resolver isso, aumente o limite de salto para 2 seguindo as instruções em Configurar as opções de metadados da instância.

Atualizei a configuração de meu atendente, mas não vejo as novas métricas ou logs no console do CloudWatch

Se você atualizar o arquivo de configuração do atendente do CloudWatch, na próxima vez que iniciar o atendente, deverá usar a opção fetch-config. Por exemplo, se você armazenou o arquivo atualizado no computador local, insira o seguinte comando:

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -s -m ec2 -c file:configuration-file-path

Arquivos e locais do atendente do CloudWatch

A tabela a seguir lista os arquivos instalados e usados pelo atendente do CloudWatch, bem como seus locais nos servidores que executam o Linux ou o Windows Server.

Arquivo	Local do Linux	Local do Windows Server
O script de controle que controla o início, a interrupção e a reinicialização do atendente.	/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl ou /usr/bin/amazon-cloudwatch-agent-ctl	$Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1
O arquivo de log no qual o atendente grava. Talvez você precise anexá-lo ao entrar em contato com AWS Support.	/opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log ou /var/log/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.log	$Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\amazon-cloudwatch-agent.log
Arquivo de validação de configuração do atendente.	/opt/aws/amazon-cloudwatch-agent/logs/configuration-validation.log ou /var/log/amazon/amazon-cloudwatch-agent/configuration-validation.log	$Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\configuration-validation.log
O arquivo JSON usado para configurar o atendente, imediatamente após o assistente criá-lo. Para obter mais informações, consulte Criar o arquivo de configuração do atendente do CloudWatch.	/opt/aws/amazon-cloudwatch-agent/bin/config.json	$Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\config.json
O arquivo JSON usado para configurar o atendente, se esse arquivo de configuração tiver sido baixado do Parameter Store.	/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json ou /etc/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.json	$Env:ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.json
O arquivo TOML usado para especificar informações de região e credenciais a serem usadas pelo agente, substituindo os padrões do sistema.	/opt/aws/amazon-cloudwatch-agent/etc/common-config.toml ou /etc/amazon/amazon-cloudwatch-agent/common-config.toml	$Env:ProgramData\Amazon\AmazonCloudWatchAgent\common-config.toml
O arquivo TOML que contém o conteúdo convertido do arquivo de configuração JSON. O script amazon-cloudwatch-agent-ctl gera esse arquivo. Os usuários não devem modificar diretamente esse arquivo. Isso pode ser útil para verificar se a tradução de JSON para TOML foi bem-sucedida.	/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.toml ou /etc/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.toml	$Env:ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.toml
O arquivo YAML que contém o conteúdo convertido do arquivo de configuração JSON. O script amazon-cloudwatch-agent-ctl gera esse arquivo. Você não deve modificar diretamente este arquivo. Este arquivo pode ser útil para verificar se a tradução de JSON para TOML foi bem-sucedida.	/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.yaml or /etc/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.yaml	$Env:ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.yaml

Encontrar informações sobre versões do atendente do CloudWatch

Para localizar o número de versão do atendente do CloudWatch em um servidor Linux, insira o seguinte comando:

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a status

Para localizar o número de versão do atendente do CloudWatch no Windows Server, insira o seguinte comando:

& $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a status

nota

Usar esse comando é a maneira correta de localizar a versão do atendente do CloudWatch. Se você usar Programs and Features (Programas e recursos) no painel de controle, verá um número de versão incorreto.

Também é possível baixar um arquivo README sobre as alterações mais recentes no atendente e um arquivo que indica o número da versão que está disponível atualmente para baixar. Esses arquivos estão nestes locais:

• https://amazoncloudwatch-agent.s3.amazonaws.com/info/latest/RELEASE_NOTES ou https://amazoncloudwatch-agent-region.s3.region.amazonaws.com/info/latest/RELEASE_NOTES

• https://amazoncloudwatch-agent.s3.amazonaws.com/info/latest/CWAGENT_VERSION ou https://amazoncloudwatch-agent-region.s3.region.amazonaws.com/amazoncloudwatch-agent-region/info/latest/CWAGENT_VERSION

Logs gerados pelo atendente do CloudWatch

O atendente gera um log enquanto é executado. Esse log inclui informações de solução de problemas. Esse log é o arquivo amazon-cloudwatch-agent.log. O arquivo está localizado em /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log nos servidores Linux e em $Env:ProgramData\Amazon\AmazonCloudWatchAgent\Logs\amazon-cloudwatch-agent.log nos servidores que executam o Windows Server.

Você pode configurar o atendente para registrar detalhes adicionais no arquivo amazon-cloudwatch-agent.log. No arquivo de configuração do atendente, na seção agent, defina o campo debug como true. Depois, reconfigure e reinicie o atendente do CloudWatch. Para desativar o registro dessas informações adicionais no log, defina o campo debug como false. Em seguida, reconfigure e reinicie o atendente. Para obter mais informações, consulte Criar ou editar manualmente o arquivo de configuração do atendente do CloudWatch.

Nas versões 1.247350.0 e posteriores do atendente do CloudWatch, você pode definir opcionalmente o campo aws_sdk_log_level na seção agent do arquivo de configuração do atendente com uma ou mais das opções a seguir. Separe várias opções com o caractere |.

• LogDebug

• LogDebugWithSigning

• LogDebugWithHTTPBody

• LogDebugRequestRetries

• LogDebugWithEventStreamBody

Para mais informações sobre essas opções, consulte LogLevelType.

Interromper e reiniciar o atendente do CloudWatch

Você pode interromper o atendente do CloudWatch manualmente usando o AWS Systems Manager ou a linha de comando.

Para interromper o atendente do CloudWatch usando o Run Command

1. Abra o console do Systems Manager em https://console.aws.amazon.com/systems-manager/.

2. No painel de navegação, selecione Executar comando.

   - ou -

   Se a página inicial do AWS Systems Manager for exibida, role para baixo e escolha Explore Run Command.

3. Selecione Run command.

4. Na lista Documento do comando, escolha AmazonCloudWatch-ManageAgent.

5. Na área Targets (Destinos), escolha a instância onde você instalou o atendente do CloudWatch.

6. Na lista Ação, escolha interromper.

7. Mantenha Optional Configuration Source (Origem de configuração opcional) e Optional Configuration Location (Local de configuração opcional) em branco.

8. Escolha Executar.

Para interromper o atendente do CloudWatch localmente usando a linha de comando

• Em um servidor Linux, digite o seguinte:

  sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -m ec2 -a stop

  Em um servidor que executa o Windows Server, digite o seguinte em PowerShell como administrador:

  & $Env:ProgramFiles\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a stop

Para reiniciar o atendente, siga as instruções em Iniciar o atendente do CloudWatch.