Il tuo EC2 instance ha smesso di rispondere, eppure CloudWatch mostra che è tutto a posto? Classico. AWS fornisce metriche di CPU, rete e I/O del disco pronte all'uso, ma non mostra l'utilizzo della memoria né lo spazio libero su disco. Quei dati sono nascosti dentro la macchina virtuale e, finché non li estrai, stai volando alla cieca.

Quando la memoria si esaurisce, l'instance non ti avvisa; semplicemente va in crash. L'OOM Killer termina i processi in ordine casuale e tu rimani a fare ipotesi: si è bloccato un plugin? È caduto il database? La causa reale è che hai finito i gigabyte di RAM che non stavi monitorando. Il disco racconta la stessa storia: log, backup e file temporanei riempiono lo storage in silenzio e una mattina ti trovi No space left on device.

La soluzione è CloudWatch Agent, l'agente standard AWS che raccoglie memoria, disco, swap e circa due dozzine di altre metriche di sistema e le invia a CloudWatch. La configurazione richiede 20 minuti e rientra nel free tier (10 metriche personalizzate al mese). Ecco una guida passo passo, dalla IAM a una dashboard completa.

💡 Panoramica rapida:

• Crea una policy IAM con cloudwatch:PutMetricData e assegnala a un utente
• Scarica e installa CloudWatch Agent su un'istanza Ubuntu
• Configura il file JSON: memoria, disco, swap
• Avvia l'agente e verifica che le metriche arrivino a CloudWatch
• Costruisci una dashboard personalizzata con i grafici di utilizzo di memoria e disco

AWS identity and access management

L'agente ha bisogno dei permessi per inviare metriche a CloudWatch. Creeremo una policy IAM e la assegneremo a un utente con accesso programmatico.

Policy IAM

Apri la console IAM, vai su Policies → Create policy e passa alla scheda JSON. Incolla questo 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
}

Clicca Review policy, inserisci un nome (ad esempio CloudWatchAgentPolicy) e clicca Create policy.

Utente IAM

Vai su Users → Add user. Inserisci un nome e assicurati di spuntare la casella "Programmatic access"; questo fornisce l'Access Key ID e la Secret Access Key che l'agente userà per l'autenticazione.

Nella schermata dei permessi, seleziona Attach existing policies directly. Nel filtro per tipo di policy, scegli Customer managed per trovare rapidamente la CloudWatchAgentPolicy che hai appena creato.

Seleziona la policy e clicca Next → Create user. AWS mostrerà le chiavi di accesso. Salva subito l'Access Key ID e la Secret Access Key. Se chiudi la pagina, le chiavi scompaiono per sempre e dovrai ricrearle.

Installazione di CloudWatch Agent

I vecchi script di monitoraggio in Perl (CloudWatchMonitoringScripts-1.2.2.zip) sono stati dichiarati deprecati da tempo. L'approccio attuale è il CloudWatch Agent unificato, che raccoglie non solo memoria e disco, ma anche swap, carico CPU, interfacce di rete e circa due dozzine di altre metriche pronte all'uso.

Download e installazione

Connettiti all'instance via SSH e scarica il pacchetto dell'agente per Ubuntu:

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

Installa il pacchetto con dpkg:

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

Se il gestore di pacchetti segnala dipendenze mancanti, installale con un unico comando:

1
sudo apt-get install -f

L'agente è installato ma non sa ancora quali metriche raccogliere né quali chiavi usare per l'autenticazione a CloudWatch. Configuriamolo.

Nota: l'agente è disponibile anche tramite AWS Systems Manager (SSM). Se hai decine di instance, distribuirlo centralmente via Run Command senza fare SSH su ogni macchina è più comodo. Per una o due instance, l'installazione manuale è più semplice e veloce.

Configurazione dell'agente

Creazione del file di configurazione

La configurazione del CloudWatch Agent è un documento JSON che descrive quali metriche raccogliere e con quale intervallo. Esegui la procedura guidata integrata:

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

La procedura guidata farà alcune domande interattive: tipo di server (EC2/on-premises), dove inviare le metriche (CloudWatch) e quali metriche raccogliere. Per monitorare memoria e disco, rispondi come segue:

• Sistema operativo: Linux
• Stai usando Amazon EC2?: Sì
• Quali metriche raccogliere: Metriche personalizzate (mem e disk_used_percent)
• Risoluzione: 60 secondi (Standard)
• File di log: salta se non ti servono i log

La procedura guidata genererà un file config.json nella directory /opt/aws/amazon-cloudwatch-agent/bin/. Ecco un esempio minimo funzionante per percentuale di memoria usata + percentuale di disco usato + 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
}

Il parametro resources per disk specifica il punto di mount: "/" è il volume root EBS NVMe SSD, lo storage primario dell'istanza. Se hai volumi aggiuntivi (ad esempio, /data), aggiungili all'array.

Credenziali dell'agente

Le chiavi di accesso salvate durante il passaggio IAM devono essere fornite all'agente. Crea un file di credenziali nella home directory dell'utente:

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

Aggiungi questa sezione:

1
[credentials]
2
    shared_credential_profile = "AmazonCloudWatchAgent"

Poi aggiungi le credenziali al file standard delle credenziali AWS:

1
aws configure --profile AmazonCloudWatchAgent

Il sistema chiederà l'Access Key ID, la Secret Access Key e la regione. Dopo averle inserite, l'agente potrà inviare metriche per conto dell'utente IAM che hai creato.

Un approccio alternativo è un ruolo IAM associato all'istanza. È più sicuro (nessuna chiave salvata su disco) e più semplice quando si scala. Se avvii EC2 con un ruolo IAM che ha il permesso cloudwatch:PutMetricData, l'agente rileverà automaticamente i permessi e potrai saltare il passaggio delle credenziali.

Test

Avvia l'agente manualmente e verifica che le metriche vengano inviate:

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

Il flag -s avvia l'agente come servizio. Entro un minuto o due, le prime metriche appariranno su CloudWatch. Per confermare che i dati stiano arrivando, apri la console CloudWatch, vai su Metriche → Tutte le metriche e cerca il namespace CWAgent (l'agente scrive lì per impostazione predefinita).

Espandi il namespace e vedrai le dimensioni InstanceId suddivise per metriche: mem_used_percent, disk_used_percent e swap_used_percent. Clicca su qualsiasi riga per generare un grafico; puoi verificare subito che i dati stiano arrivando e che abbiano valori sensati.

Quattro metriche di base (memoria, disco, swap, CPU) su due istanze equivalgono a 8 metriche. Il piano gratuito di CloudWatch include 10 metriche personalizzate al mese, come descritto nella pagina dei prezzi. Rientri in quel limite. Se hai più di tre istanze, alcune metriche supereranno il limite, ma il costo è contenuto: $0,30 per metrica al mese (dati AWS aggiornati al 2026).

Impostare la schedulazione

Per impostazione predefinita, l'agente viene eseguito come servizio systemd e invia le metriche all'intervallo specificato in metrics_collection_interval (60 secondi nella nostra configurazione). Non sono necessarie voci cron aggiuntive; systemd garantisce che l'agente resti attivo e si riavvii in caso di crash.

Controlla lo stato:

1
sudo systemctl status amazon-cloudwatch-agent

Verifica che il servizio sia active (running) e abilitato all'avvio (enabled). In caso contrario, avvialo e abilitalo:

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

Dopo un riavvio, l'agente si avvierà automaticamente.

Per una dimostrazione visiva dell'intero processo, dalla configurazione IAM alla dashboard, guarda questo video:

Creare una dashboard personalizzata

Le metriche arrivano; ora devi impacchettarle in modo presentabile. Ti mostro come costruire una dashboard per monitorare un'istanza di produzione: memoria, disco, carico CPU e saldo crediti (per le T-series) su un'unica schermata.

Creare la dashboard

Nella console CloudWatch, vai su Dashboard → Crea dashboard. Inserisci un nome (ad esempio Production-EC2) e scegli un tipo di widget.

Seleziona Linea per il primo grafico; questo tipo è il più adatto per visualizzare metriche nel tempo.

Widget grafico

Clicca Aggiungi widget e seleziona il tipo Linea, un semplice grafico a linee e la scelta migliore per la maggior parte delle metriche. Nella finestra di dialogo che si apre, clicca Configura e naviga fino al namespace CWAgent.

Trova la metrica mem_used_percent per la tua istanza (tramite InstanceId) e clicca sulla riga; CloudWatch mostrerà immediatamente un grafico.

Suggerimento: il tipo Area in pila funziona bene quando un singolo widget ha più metriche (ad esempio, memoria + swap); Numero è utile per leggere istantaneamente il valore corrente (comodo in un angolo della dashboard); Testo serve per intestazioni e note tra i grafici.

Perfezionare il grafico

Alcune impostazioni che rendono il grafico leggibile:

• Periodo: se l'agente invia metriche una volta al minuto, scegli un periodo di 1 minuto per vedere la piena risoluzione dei dati.

• Titolo: rinomina la legenda del grafico con qualcosa di più comprensibile, "RAM usata%" anziché mem_used_percent / i-1234567890abcdef0.

• Massimo asse Y (Opzioni grafico): fissa il limite (ad esempio, 100 per le percentuali o 16 per 16 GB di RAM). Senza, CloudWatch scala automaticamente l'asse e un piccolo picco sembra allarmante quanto una situazione critica. Con un limite fisso, puoi capire a colpo d'occhio quanto sei vicino al bordo.

Clicca Crea widget; il primo blocco della dashboard è pronto. Ripeti per ogni metrica: disk_used_percent, poi swap_used_percent, poi cpu_usage (una metrica EC2 integrata, non da CWAgent) e CPUCreditBalance per le T-series. Puoi trascinare, ridimensionare e modificare i widget. Quando tutto è a posto, clicca Salva dashboard.

La dashboard è pronta. Aggiungila ai preferiti (la stella nel menu in alto) e torna con un clic ogni volta che devi controllare lo stato dell'istanza prima di un deploy o dopo un picco di traffico.

⁉️🤔 Domande frequenti

Perché le metriche EC2 standard non includono memoria e disco?

AWS virtualizza CPU e rete a livello di hypervisor; queste metriche sono disponibili esternamente senza entrare nel sistema operativo guest. Memoria e disco sono risorse interne della macchina virtuale; l'hypervisor non ne è a conoscenza. Per vederle, serve un agente dentro il sistema operativo che legga /proc/meminfo e df e invii i dati a CloudWatch. È esattamente ciò che fa CloudWatch Agent: una volta al minuto interroga i contatori di sistema e li invia al namespace CWAgent. L'elenco completo di circa due dozzine di metriche è nella documentazione ufficiale AWS.

Quanto costa?

Per uno scenario tipico di 1-2 istanze con 4 metriche ciascuna, nulla. Il piano gratuito CloudWatch include 10 metriche personalizzate, 10 allarmi e 3 dashboard per account al mese, secondo la pagina dei prezzi CloudWatch. Due istanze con 4 metriche ciascuna fanno 8 delle 10 metriche gratuite. Se hai più di tre istanze, superare il limite costa $0,30 per metrica al mese. Per una dozzina di server, sono $6-9 al mese, il prezzo per evitare sorprese alle tre del mattino.

Perché CloudWatch Agent è migliore dei vecchi script Perl?

Gli script Perl (mon-put-instance-data.pl) sono ufficialmente deprecati dal 2023 e non ricevono aggiornamenti. CloudWatch Agent è lo strumento ufficialmente supportato che scrive non solo su CloudWatch ma anche su Amazon Managed Prometheus; raccoglie metriche via StatsD e collectd; può inviare log e tracce. Soprattutto, si integra con Systems Manager, il che significa che puoi distribuirlo su 50 istanze con un solo comando dalla console, senza SSH. Se hai ancora script Perl in esecuzione, migra: il vecchio formato awscreds.conf con chiavi in chiaro su disco è una falla di sicurezza. CloudWatch Agent funziona con ruoli IAM e non richiede di memorizzare segreti in un file di testo.

Cosa devo fare se le metriche non compaiono in CloudWatch?

Verifica in ordine: (1) stato del servizio con systemctl status amazon-cloudwatch-agent, che deve essere active; (2) log dell'agente in /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log, dove troverai l'errore specifico; (3) permessi IAM, l'utente o il ruolo deve avere il permesso cloudwatch:PutMetricData; (4) regione, l'agente e la console devono puntare alla stessa regione AWS. Nella mia esperienza, la stragrande maggioranza dei problemi sono permessi o mancata corrispondenza di regione.

Posso monitorare istanze Windows?

Sì, CloudWatch Agent supporta Windows Server al pari di Linux. L'installazione avviene tramite un installer MSI dallo stesso bucket S3 (amazon-cloudwatch-agent.s3.amazonaws.com/windows/amd64/latest/). La configurazione usa lo stesso JSON, ma i nomi delle metriche differiscono: invece di mem_used_percent, usa Memory % Committed Bytes In Use. La procedura guidata di configurazione su Windows sostituirà automaticamente i nomi corretti.

Cosa offre in pratica il monitoraggio di memoria e disco

Hai avviato CloudWatch Agent su un'istanza Ubuntu, configurato la raccolta di memoria, disco e swap e aggiunto una dashboard con grafici. Cosa è cambiato? Esattamente una cosa: il punto cieco è sparito. Vedi non solo CPU e rete ma anche i due principali killer delle istanze: memory leak e dischi pieni.

In pratica, questo significa che noti la memoria che cresce gradualmente tre giorni PRIMA che l'OOM Killer termini PHP-FPM. Vedi che il disco si è riempito quasi completamente dopo un aggiornamento del tema e pulisci i log PRIMA che il database vada in crash. Senza queste metriche, ogni incidente diventa un'indagine post-mortem. Con queste, ricevi un avviso nel canale mezz'ora prima del disservizio.

Se hai più di tre istanze, imposta CloudWatch Alarms su valori soglia (ad esempio, mem_used_percent > 90 per 5 minuti) e collega le notifiche via SNS a Slack o Telegram. Agente + allarmi = vieni a sapere del problema da AWS, non da un cliente.

La configurazione dell'agente è un investimento una tantum di 20 minuti per istanza. Dopodiché, funziona da solo.