A sua instância EC2 deixou de responder, mas o CloudWatch mostra que está tudo bem? Clássico. A AWS fornece métricas de CPU, rede e I/O de disco por defeito, mas não mostra a utilização de memória nem o espaço livre em disco. Esses números estão escondidos dentro da máquina virtual e, até os extrair, está a voar às cegas.

Quando a memória se esgota, a instância não avisa; simplesmente bloqueia. O OOM Killer termina processos por ordem aleatória e fica a tentar adivinhar: um plugin falhou? A base de dados foi abaixo? A causa real é que ficou sem os gigabytes de RAM que não estava a monitorizar. O disco conta a mesma história: logs, backups e ficheiros temporários enchem o armazenamento silenciosamente e, numa bela manhã, depara-se com No space left on device.

A solução é o CloudWatch Agent, o agente padrão da AWS que recolhe métricas de memória, disco, swap e cerca de duas dezenas de outras métricas de sistema e as envia para o CloudWatch. A configuração demora 20 minutos e cabe no nível gratuito (10 métricas personalizadas por mês). Abaixo encontra um guia passo a passo, do IAM ao dashboard final.

💡 Visão geral rápida:

• Criar uma política IAM com cloudwatch:PutMetricData e anexá-la a um utilizador
• Transferir e instalar o CloudWatch Agent numa instância Ubuntu
• Configurar o ficheiro JSON: memória, disco, swap
• Iniciar o agente e verificar se as métricas estão a fluir para o CloudWatch
• Construir um dashboard personalizado com gráficos de utilização de memória e disco

Gestão de identidade e acesso na AWS

O agente precisa de permissões para enviar métricas para o CloudWatch. Vamos criar uma política IAM e anexá-la a um utilizador com acesso programático.

Política IAM

Abra a consola IAM, vá a Políticas → Criar política e mude para o separador JSON. Cole este documento:

1
{
2
    "Version": "2012-10-17",
3
    "Statement": [
4
        {
5
            "Sid": "CloudWatchAgentMetrics",
6
            "Effect": "Allow",
7
            "Action": [
8
                "cloudwatch:PutMetricData",
9
                "ec2:DescribeTags",
10
                "cloudwatch:GetMetricStatistics",
11
                "cloudwatch:ListMetrics"
12
            ],
13
            "Resource": "*"
14
        }
15
    ]
16
}

Clique em Rever política, introduza um nome (por exemplo, CloudWatchAgentPolicy) e clique em Criar política.

Utilizador IAM

Vá a Utilizadores → Adicionar utilizador. Introduza um nome e certifique-se de que marca a caixa "Acesso programático"; isto fornece o ID da chave de acesso e a chave de acesso secreta que o agente usará para autenticação.

No ecrã de permissões, selecione Anexar políticas existentes diretamente. No filtro de tipo de política, escolha Gerida pelo cliente para encontrar rapidamente a CloudWatchAgentPolicy que acabou de criar.

Marque a política e clique em Seguinte → Criar utilizador. A AWS mostrará as chaves de acesso. Guarde o ID da chave de acesso e a chave de acesso secreta imediatamente. Se fechar a página, as chaves desaparecem para sempre e terá de as recriar.

Instalar o CloudWatch Agent

Os antigos scripts de monitorização em Perl (CloudWatchMonitoringScripts-1.2.2.zip) foram marcados como obsoletos há muito. A abordagem atual é o CloudWatch Agent unificado, que recolhe não só memória e disco, mas também swap, carga da CPU, interfaces de rede e cerca de duas dezenas de outras métricas de raiz.

Transferência e instalação

Ligue-se à instância via SSH e transfira o pacote do agente para Ubuntu:

1
wget https://amazoncloudwatch-agent.s3.amazonaws.com/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb

Instale o pacote com o dpkg:

1
sudo dpkg -i amazon-cloudwatch-agent.deb

Se o gestor de pacotes se queixar de dependências em falta, instale-as com um único comando:

1
sudo apt-get install -f

O agente está instalado, mas ainda não sabe que métricas recolher nem que chaves usar para a autenticação no CloudWatch. Vamos configurá-lo.

Nota: o agente também está disponível através do AWS Systems Manager (SSM). Se tiver dezenas de instâncias, implementá-lo centralmente via Run Command sem SSH para cada máquina é mais conveniente. Para uma ou duas instâncias, a instalação manual é mais simples e rápida.

Configurar o agente

Criar o ficheiro de configuração

A configuração do CloudWatch Agent é um documento JSON que descreve quais as métricas a recolher e com que intervalo. Execute o assistente integrado:

1
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard

O assistente fará várias perguntas interativas: tipo de servidor (EC2/on-premises), para onde enviar as métricas (CloudWatch) e quais métricas recolher. Para monitorizar memória e disco, responda da seguinte forma:

• Sistema operativo: Linux
• Está a utilizar o Amazon EC2?: Sim
• Quais as métricas a recolher: Métricas personalizadas (mem e disk_used_percent)
• Resolução: 60 segundos (Standard)
• Ficheiros de log: ignore se não precisar de logs

O assistente irá gerar um ficheiro config.json no diretório /opt/aws/amazon-cloudwatch-agent/bin/. Eis um exemplo mínimo funcional para percentagem de memória utilizada + percentagem de disco utilizado + swap:

1
{
2
    "agent": {
3
        "metrics_collection_interval": 60,
4
        "run_as_user": "root"
5
    },
6
    "metrics": {
7
        "metrics_collected": {
8
            "mem": {
9
                "measurement": [
10
                    "mem_used_percent"
11
                ]
12
            },
13
            "disk": {
14
                "measurement": [
15
                    "disk_used_percent"
16
                ],
17
                "resources": [
18
                    "/"
19
                ]
20
            },
21
            "swap": {
22
                "measurement": [
23
                    "swap_used_percent"
24
                ]
25
            }
26
        }
27
    }
28
}

O parâmetro resources para disk especifica o ponto de montagem: "/" é o volume raiz EBS NVMe SSD, o armazenamento principal da instância. Se tiver volumes adicionais (por exemplo, /data), adicione-os ao array.

Credenciais do agente

As chaves de acesso guardadas durante o passo do IAM precisam de ser fornecidas ao agente. Crie um ficheiro de credenciais no diretório home do utilizador:

1
sudo nano /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.toml

Adicione esta secção:

1
[credentials]
2
    shared_credential_profile = "AmazonCloudWatchAgent"

Depois, adicione as credenciais ao ficheiro de credenciais padrão da AWS:

1
aws configure --profile AmazonCloudWatchAgent

O sistema solicitará o Access Key ID, a Secret Access Key e a região. Depois de as preencher, o agente poderá enviar métricas em nome do utilizador IAM que criou.

Uma abordagem alternativa é uma função do IAM (IAM role) associada à instância. Isto é mais seguro (não há chaves guardadas em disco) e mais simples ao escalar. Se iniciar o EC2 com uma função do IAM que tenha a permissão cloudwatch:PutMetricData, o agente obterá as permissões automaticamente e pode saltar o passo das credenciais.

Testes

Inicie o agente manualmente e verifique se as métricas estão a ser enviadas:

1
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
2
  -a fetch-config \
3
  -m ec2 \
4
  -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json \
5
  -s

A flag -s inicia o agente como um serviço. Dentro de um ou dois minutos, as primeiras métricas aparecerão no CloudWatch. Para confirmar que os dados estão a fluir, abra a consola CloudWatch, vá a Metrics → All metrics e encontre o namespace CWAgent (o agente escreve lá por predefinição).

Expanda o namespace e verá as dimensões InstanceId discriminadas por métricas: mem_used_percent, disk_used_percent e swap_used_percent. Clique em qualquer linha para gerar um gráfico; pode verificar imediatamente se os dados estão a chegar e parecem coerentes.

Quatro métricas básicas (memória, disco, swap, CPU) em duas instâncias equivalem a 8 métricas. O nível gratuito do CloudWatch inclui 10 métricas personalizadas por mês, conforme descrito na página de preços. Está dentro desse limite. Se tiver mais de três instâncias, algumas métricas excederão o limite, mas o custo é modesto: 0,30 $ por métrica por mês (dados da AWS à data de 2026).

Configurar o agendamento

Por predefinição, o agente é executado como um serviço systemd e envia métricas no intervalo especificado em metrics_collection_interval (60 segundos na nossa configuração). Não são necessárias entradas adicionais no cron; o systemd garante que o agente se mantém ativo e o reinicia se falhar.

Verifique o estado:

1
sudo systemctl status amazon-cloudwatch-agent

Confirme que o serviço está active (running) e ativado para o arranque (enabled). Se não estiver, inicie-o e ative-o:

1
sudo systemctl enable amazon-cloudwatch-agent
2
sudo systemctl start amazon-cloudwatch-agent

Após um reinício, o agente será iniciado automaticamente.

Para uma demonstração visual de todo o processo, desde o IAM até ao painel, veja este vídeo:

Criar um dashboard personalizado

As métricas estão a chegar; agora precisa de as apresentar de forma organizada. Vou mostrar-lhe como criar um dashboard para monitorizar uma instância de produção: memória, disco, carga de CPU e saldo de créditos (para a série T) num único ecrã.

Criar o dashboard

Na consola CloudWatch, vá a Dashboards → Criar dashboard. Introduza um nome (por exemplo, Production-EC2) e escolha um tipo de widget.

Selecione Linha para o primeiro gráfico; este tipo é o mais adequado para apresentar métricas ao longo do tempo.

Widget de gráfico

Clique em Adicionar widget e selecione o tipo Linha, um gráfico de linhas simples e a melhor escolha para a maioria das métricas. Na janela que se abre, clique em Configurar e navegue até ao namespace CWAgent.

Encontre a métrica mem_used_percent para a sua instância (por InstanceId) e clique na linha; o CloudWatch apresenta imediatamente um gráfico.

Dica: o tipo Área empilhada funciona bem quando um único widget tem várias métricas (por exemplo, memória + swap); Número é útil para ler instantaneamente o valor atual (prático num canto do dashboard); Texto serve para títulos e notas entre gráficos.

Afinar o gráfico

Algumas definições que tornam o gráfico legível:

• Período: se o agente envia métricas uma vez por minuto, escolha um período de 1 minuto para ver a resolução completa dos dados.

• Título: mude o nome da legenda do gráfico para algo compreensível, como "RAM utilizada%" em vez de mem_used_percent / i-1234567890abcdef0.

• Máximo do eixo Y (Opções do gráfico): fixe o limite (por exemplo, 100 para percentagens ou 16 para 16 GB de RAM). Sem isto, o CloudWatch faz escala automática do eixo e um pequeno pico parece tão alarmante como uma situação crítica. Com um limite fixo, percebe-se de relance quão perto se está do limite.

Clique em Criar widget; o primeiro bloco do dashboard está pronto. Repita para cada métrica: disk_used_percent, depois swap_used_percent, depois cpu_usage (uma métrica integrada do EC2, não do CWAgent) e CPUCreditBalance para a série T. Pode arrastar, redimensionar e editar widgets. Quando tudo estiver correto, clique em Guardar dashboard.

O dashboard está pronto. Adicione-o aos favoritos (a estrela no menu superior) e regresse com um clique sempre que precisar de verificar o estado da instância antes de um deploy ou após um pico de tráfego.

⁉️🤔 Perguntas frequentes

Por que razão as métricas padrão do EC2 não incluem memória e disco?

A AWS virtualiza CPU e rede ao nível do hipervisor; estas métricas estão disponíveis externamente sem entrar no SO convidado. A memória e o disco são recursos internos da máquina virtual; o hipervisor não tem conhecimento sobre eles. Para os ver, precisa de um agente dentro do SO que leia /proc/meminfo e df e envie os dados para o CloudWatch. É exatamente isso que o CloudWatch Agent faz: uma vez por minuto consulta os contadores do sistema e envia-os para o namespace CWAgent. A lista completa de cerca de duas dezenas de métricas está na documentação oficial da AWS.

Quanto é que isto custa?

Para um cenário típico de 1 a 2 instâncias com 4 métricas cada, nada. O nível gratuito do CloudWatch inclui 10 métricas personalizadas, 10 alarmes e 3 dashboards por conta e por mês, de acordo com a página de preços do CloudWatch. Duas instâncias com 4 métricas cada totalizam 8 das 10 métricas gratuitas. Se tiver mais de três instâncias, exceder o limite custa $0,30 por métrica por mês. Para uma dúzia de servidores, são $6 a $9 por mês, o preço para evitar surpresas às três da manhã.

Por que razão o CloudWatch Agent é melhor do que os antigos scripts Perl?

Os scripts Perl (mon-put-instance-data.pl) foram oficialmente descontinuados desde 2023 e não recebem atualizações. O CloudWatch Agent é a ferramenta oficialmente suportada que escreve não só no CloudWatch, mas também no Amazon Managed Prometheus; recolhe métricas via StatsD e collectd; pode enviar logs e traces. Mais importante ainda, integra-se com o Systems Manager, o que significa que pode implementá-lo em 50 instâncias com um único comando a partir da consola, sem SSH. Se ainda tem scripts Perl em execução, migre: o antigo formato awscreds.conf com chaves em texto simples no disco é uma falha de segurança. O CloudWatch Agent funciona com funções IAM e não requer o armazenamento de segredos num ficheiro de texto.

O que devo fazer se as métricas não aparecerem no CloudWatch?

Verifique por ordem: (1) estado do serviço via systemctl status amazon-cloudwatch-agent, que deve estar active; (2) logs do agente em /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log, onde encontrará o erro específico; (3) permissões IAM, o utilizador ou a função devem ter a permissão cloudwatch:PutMetricData; (4) região, o agente e a consola devem apontar para a mesma região AWS. Na minha experiência, a esmagadora maioria dos problemas são ou permissões ou incompatibilidade de região.

Posso monitorizar instâncias Windows?

Sim, o CloudWatch Agent suporta Windows Server em paridade com o Linux. A instalação é feita através de um instalador MSI do mesmo bucket S3 (amazon-cloudwatch-agent.s3.amazonaws.com/windows/amd64/latest/). A configuração usa o mesmo JSON, mas os nomes das métricas diferem: em vez de mem_used_percent, use Memory % Committed Bytes In Use. O assistente de configuração no Windows substituirá automaticamente os nomes corretos.

O que a monitorização de memória e disco proporciona na prática

Lançou o CloudWatch Agent numa instância Ubuntu, configurou a recolha de memória, disco e swap e adicionou um dashboard com gráficos. O que mudou? Exatamente uma coisa: o ponto cego desapareceu. Vê não só CPU e rede, mas também os dois principais causadores de falhas nas instâncias: fugas de memória e discos cheios.

Na prática, isto significa que repara na memória a aumentar gradualmente três dias ANTES de o OOM Killer terminar o PHP-FPM. Vê que o disco encheu quase completamente após uma atualização do tema e limpa os logs ANTES de a base de dados falhar. Sem estas métricas, cada incidente torna-se uma investigação post-mortem. Com elas, recebe um alerta no canal meia hora antes da indisponibilidade.

Se tiver mais de três instâncias, configure CloudWatch Alarms com valores limite (por exemplo, mem_used_percent > 90 durante 5 minutos) e ligue notificações via SNS ao Slack ou Telegram. Agente + alarmes = fica a saber do problema pela AWS, não por um cliente.

A configuração do agente é um investimento único de 20 minutos por instância. Depois disso, funciona sozinho.