Surveiller l'utilisation mémoire des instances EC2 avec l'agent CloudWatch

Vous venez d'ouvrir la console CloudWatch pour diagnostiquer une lenteur sur votre instance EC2, et la métrique RAM est introuvable. Ce n'est pas un bug, ni un oubli — c'est une limite architecturale fondamentale : CloudWatch ne peut pas voir à l'intérieur du système d'exploitation de votre instance sans un agent installé. Comprendre pourquoi cette limite existe, et comment la contourner correctement, est indispensable pour toute opération de production sérieuse sur la surveillance mémoire EC2.

TL;DR — Surveillance mémoire EC2

Aspect	Comportement
Métriques CloudWatch par défaut	CPU, réseau, disque EBS (I/O) — aucune métrique OS
Pourquoi pas de RAM par défaut	AWS n'a pas accès à l'intérieur du système d'exploitation invité
Solution	Installer l'agent CloudWatch sur l'instance
Métriques OS disponibles via l'agent	RAM utilisée, RAM disponible, utilisation disque, swap, processus
Prérequis IAM	Rôle IAM avec la politique `CloudWatchAgentServerPolicy`
Espace de noms CloudWatch	`CWAgent` (personnalisable)

Pourquoi CloudWatch ne voit pas la RAM par défaut

AWS opère selon un modèle de responsabilité partagée. La couche hyperviseur expose à CloudWatch certaines métriques observables depuis l'extérieur de la machine virtuelle : utilisation CPU (via les cycles d'horloge alloués), trafic réseau, et opérations d'I/O sur les volumes EBS. Ces données sont collectées par l'infrastructure AWS sans nécessiter d'accès au système d'exploitation invité.

La mémoire RAM, en revanche, est gérée entièrement à l'intérieur du système d'exploitation. L'hyperviseur alloue de la mémoire physique à l'instance, mais il ne sait pas comment le noyau Linux ou Windows la subdivise entre processus, caches, buffers, et espace libre. Cette information n'est accessible qu'en lisant /proc/meminfo (Linux) ou les compteurs WMI (Windows) — deux sources qui nécessitent un processus s'exécutant à l'intérieur de l'instance.

C'est comme surveiller un entrepôt depuis l'extérieur : vous pouvez compter les camions qui entrent et sortent, mais vous ne savez pas comment les étagères sont organisées à l'intérieur sans envoyer quelqu'un vérifier.

L'agent CloudWatch est ce 'quelqu'un' — un processus léger qui s'exécute dans l'instance, lit les métriques OS, et les publie vers CloudWatch via l'API PutMetricData.

graph TD HV["Hyperviseur AWS
métriques visibles depuis l'extérieur"] CW["CloudWatch
AWS/EC2 namespace"] OS["Système d'exploitation invité
RAM, swap, disque"] AGT["Agent CloudWatch
s'exécute dans l'instance"] CWA["CloudWatch
CWAgent namespace"] HV -->|"CPU, réseau, EBS I/O"| CW OS -->|"lit /proc/meminfo"| AGT AGT -->|"PutMetricData"| CWA style HV fill:#2d6a9f,color:#fff style CW fill:#1a7f5a,color:#fff style OS fill:#7d3c98,color:#fff style AGT fill:#b7500a,color:#fff style CWA fill:#1a7f5a,color:#fff

Hyperviseur AWS : collecte les métriques visibles depuis l'extérieur (CPU, réseau, EBS I/O) et les publie automatiquement dans CloudWatch.
Système d'exploitation invité : gère la mémoire RAM, le swap, et l'espace disque — ces données restent invisibles depuis l'hyperviseur.
Agent CloudWatch : s'exécute à l'intérieur de l'instance, lit les métriques OS, et les envoie à CloudWatch via PutMetricData.
Espace de noms CWAgent : les métriques publiées par l'agent apparaissent dans un espace de noms séparé des métriques EC2 par défaut.

Installation de l'agent CloudWatch sur EC2 — Prérequis IAM

Avant d'installer quoi que ce soit, l'instance doit avoir les permissions nécessaires pour publier des métriques. Sans le bon rôle IAM, l'agent démarre silencieusement mais n'envoie rien — et vous passerez du temps à chercher un problème de configuration qui n'existe pas.

Attachez la politique gérée AWS CloudWatchAgentServerPolicy au rôle IAM de l'instance. Cette politique accorde les permissions minimales requises : cloudwatch:PutMetricData, ec2:DescribeTags, et les permissions de lecture SSM si vous utilisez le Parameter Store pour stocker la configuration de l'agent.

# Créer un rôle IAM pour l'instance EC2
aws iam create-role \
  --role-name EC2CloudWatchAgentRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ec2.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# Attacher la politique gérée CloudWatchAgentServerPolicy
aws iam attach-role-policy \
  --role-name EC2CloudWatchAgentRole \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

# Créer un profil d'instance et y associer le rôle
aws iam create-instance-profile \
  --instance-profile-name EC2CloudWatchAgentProfile

aws iam add-role-to-instance-profile \
  --instance-profile-name EC2CloudWatchAgentProfile \
  --role-name EC2CloudWatchAgentRole

# Associer le profil à l'instance EC2 existante
aws ec2 associate-iam-instance-profile \
  --instance-id i-0123456789abcdef0 \
  --iam-instance-profile Name=EC2CloudWatchAgentProfile

Installation et configuration de l'agent CloudWatch sur Linux

L'agent CloudWatch est distribué via SSM ou directement téléchargeable. Sur Amazon Linux 2 et Amazon Linux 2023, le paquet est disponible dans les dépôts officiels. Sur d'autres distributions, utilisez le paquet RPM ou DEB fourni par AWS.

# Sur Amazon Linux 2 / Amazon Linux 2023
sudo yum install -y amazon-cloudwatch-agent

# Sur Ubuntu / Debian
wget https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb
sudo dpkg -i amazon-cloudwatch-agent.deb

L'agent utilise un fichier de configuration JSON pour définir quelles métriques collecter et à quelle fréquence. Vous pouvez générer ce fichier interactivement avec l'assistant de configuration, ou l'écrire directement. Voici une configuration minimale pour collecter les métriques mémoire et disque :

🔽 Cliquer pour afficher la configuration JSON de l'agent CloudWatch

{
  "agent": {
    "metrics_collection_interval": 60,
    "run_as_user": "cwagent"
  },
  "metrics": {
    "append_dimensions": {
      "AutoScalingGroupName": "${aws:AutoScalingGroupName}",
      "ImageId": "${aws:ImageId}",
      "InstanceId": "${aws:InstanceId}",
      "InstanceType": "${aws:InstanceType}"
    },
    "metrics_collected": {
      "mem": {
        "measurement": [
          "mem_used_percent",
          "mem_available",
          "mem_used",
          "mem_total"
        ],
        "metrics_collection_interval": 60
      },
      "disk": {
        "measurement": [
          "used_percent",
          "used",
          "free"
        ],
        "metrics_collection_interval": 60,
        "resources": [
          "/"
        ]
      },
      "swap": {
        "measurement": [
          "swap_used_percent",
          "swap_used",
          "swap_free"
        ],
        "metrics_collection_interval": 60
      }
    }
  }
}

Enregistrez cette configuration dans /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json, puis démarrez l'agent :

# Démarrer l'agent avec le fichier de configuration local
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -a fetch-config \
  -m ec2 \
  -s \
  -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json

# Vérifier le statut de l'agent
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -m ec2 \
  -a status

Un statut running confirme que l'agent collecte et publie les métriques. Les premières données apparaissent dans CloudWatch dans les deux minutes suivant le démarrage.

Vérifier que les métriques mémoire EC2 arrivent dans CloudWatch

Les métriques publiées par l'agent apparaissent dans l'espace de noms CWAgent, pas dans AWS/EC2. C'est la première chose que les gens ratent quand ils cherchent leurs métriques RAM dans la console — ils regardent au mauvais endroit.

# Lister les métriques disponibles dans l'espace de noms CWAgent
aws cloudwatch list-metrics \
  --namespace CWAgent \
  --region us-east-1

# Récupérer les statistiques de mémoire utilisée pour une instance spécifique
aws cloudwatch get-metric-statistics \
  --namespace CWAgent \
  --metric-name mem_used_percent \
  --dimensions Name=InstanceId,Value=i-0123456789abcdef0 \
  --start-time 2024-01-15T10:00:00Z \
  --end-time 2024-01-15T11:00:00Z \
  --period 300 \
  --statistics Average \
  --region us-east-1

Si la commande list-metrics ne retourne aucun résultat pour CWAgent, l'agent ne publie pas. Vérifiez les journaux de l'agent avant de chercher ailleurs.

# Consulter les journaux de l'agent pour diagnostiquer les erreurs
sudo tail -f /opt/aws/amazon-cloudwatch-agent/logs/amazon-cloudwatch-agent.log

graph TD S1["1. Vérifier le statut de l'agent
amazon-cloudwatch-agent-ctl -a status"] S2{"Agent en cours
d'exécution ?"} S3["Consulter les journaux système
/var/log/messages"] S4["Consulter les journaux de l'agent
amazon-cloudwatch-agent.log"] S5{"Erreur AccessDenied
ou RequestError ?"} S6["Vérifier le rôle IAM
et le profil d'instance"] S7["Redémarrer l'agent
après correction IAM"] S8["Vérifier les métriques
dans l'espace de noms CWAgent"] S9["Créer alarmes
et tableaux de bord"] S1 --> S2 S2 -->|"Non"| S3 S2 -->|"Oui"| S4 S3 --> S4 S4 --> S5 S5 -->|"Oui"| S6 S5 -->|"Non"| S8 S6 --> S7 S7 --> S8 S8 --> S9 style S1 fill:#2d6a9f,color:#fff style S6 fill:#b7500a,color:#fff style S9 fill:#1a7f5a,color:#fff

Vérifier le statut : la commande status confirme si l'agent tourne. Un état stopped indique un problème de démarrage — consultez les journaux système.
Vérifier les journaux de l'agent : les erreurs d'authentification IAM (AccessDenied) apparaissent ici. C'est souvent la cause racine quand l'agent tourne mais ne publie rien.
Vérifier le rôle IAM : confirmez que le profil d'instance est bien attaché à l'instance et que le rôle contient CloudWatchAgentServerPolicy.
Vérifier l'espace de noms : cherchez dans CWAgent, pas dans AWS/EC2.

Erreur classique : l'agent tourne mais aucune métrique n'apparaît

Voici un scénario que vous rencontrerez probablement une fois. L'agent affiche le statut running, les journaux ne montrent aucune erreur évidente, mais list-metrics retourne une liste vide pour CWAgent.

Le réflexe initial est de vérifier la configuration JSON — mauvais nom de métrique, mauvaise syntaxe. Après vingt minutes à comparer la configuration avec la documentation, tout semble correct.

La vraie cause : le profil d'instance IAM a été attaché à l'instance après le démarrage de l'agent. L'agent récupère les credentials IAM au démarrage via le service de métadonnées de l'instance (IMDS). Si le rôle n'était pas encore attaché à ce moment-là, l'agent démarre sans credentials valides et échoue silencieusement sur chaque appel PutMetricData.

Le journal de l'agent contient la ligne révélatrice, mais elle est facile à manquer si vous ne cherchez pas spécifiquement une erreur RequestError ou AccessDenied. La correction est simple : redémarrer l'agent après avoir attaché le rôle IAM.

# Redémarrer l'agent après modification du rôle IAM
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -m ec2 \
  -a stop

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -a fetch-config \
  -m ec2 \
  -s \
  -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json

Un détail que la documentation ne met pas en avant : si vous utilisez IMDSv2 (recommandé), l'agent CloudWatch le supporte nativement depuis les versions récentes. Sur les instances configurées pour exiger IMDSv2 exclusivement, une version ancienne de l'agent peut échouer à récupérer ses credentials. Vérifiez que vous utilisez une version récente de l'agent avant de chercher un problème de politique IAM.

Créer une alarme CloudWatch sur l'utilisation mémoire

Une fois les métriques disponibles, créer une alarme sur le pourcentage de RAM utilisée suit le même modèle que pour n'importe quelle métrique CloudWatch — à ceci près que vous devez spécifier l'espace de noms CWAgent et les dimensions correctes.

aws cloudwatch put-metric-alarm \
  --alarm-name "EC2-MemoryUsage-High" \
  --alarm-description "Alerte si utilisation memoire depasse 85%" \
  --namespace CWAgent \
  --metric-name mem_used_percent \
  --dimensions Name=InstanceId,Value=i-0123456789abcdef0 \
  --statistic Average \
  --period 300 \
  --evaluation-periods 2 \
  --threshold 85 \
  --comparison-operator GreaterThanThreshold \
  --alarm-actions arn:aws:sns:us-east-1:123456789012:AlertsTopic \
  --region us-east-1

Déploiement à grande échelle avec SSM et Systems Manager

Installer et configurer l'agent manuellement sur chaque instance n'est pas viable au-delà de quelques machines. AWS Systems Manager propose deux approches complémentaires : le document SSM AWS-ConfigureAWSPackage pour l'installation, et le Parameter Store pour centraliser la configuration de l'agent.

# Stocker la configuration de l'agent dans SSM Parameter Store
aws ssm put-parameter \
  --name "/cloudwatch-agent/config" \
  --type String \
  --value file://amazon-cloudwatch-agent.json \
  --region us-east-1

# Démarrer l'agent sur une instance en utilisant la configuration SSM
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
  -a fetch-config \
  -m ec2 \
  -s \
  -c ssm:/cloudwatch-agent/config

Pour un déploiement sur un parc d'instances, utilisez une commande SSM Run Command avec le document AmazonCloudWatch-ManageAgent — ce document gère l'installation, la configuration, et le démarrage de l'agent en une seule opération.

Conclusion — Surveillance mémoire EC2 en production

La surveillance mémoire EC2 nécessite l'agent CloudWatch parce que la frontière entre l'infrastructure AWS et le système d'exploitation invité est réelle et délibérée. CloudWatch ne traverse pas cette frontière sans un processus côté OS pour lui transmettre les données.

L'installation de l'agent est simple, mais les erreurs silencieuses liées au timing d'attachement du rôle IAM ou aux versions de l'agent face à IMDSv2 peuvent faire perdre du temps. Vérifiez toujours les journaux de l'agent en premier, et confirmez que les métriques apparaissent dans l'espace de noms CWAgent avant de construire des alarmes ou des tableaux de bord.

Pour les environnements avec de nombreuses instances, centralisez la configuration via SSM Parameter Store dès le départ — modifier la configuration sur chaque instance individuellement devient rapidement ingérable.

Glossaire

Terme	Définition
Agent CloudWatch	Processus s'exécutant à l'intérieur de l'instance EC2, responsable de collecter les métriques OS et de les publier vers CloudWatch via `PutMetricData`.
Espace de noms CWAgent	Espace de noms CloudWatch dans lequel l'agent publie les métriques collectées. Distinct de l'espace de noms `AWS/EC2` utilisé pour les métriques par défaut.
Profil d'instance IAM	Conteneur IAM qui associe un rôle à une instance EC2, permettant aux processus s'exécutant sur l'instance d'obtenir des credentials AWS temporaires via IMDS.
IMDS (Instance Metadata Service)	Service local accessible depuis l'instance à l'adresse `169.254.169.254`, fournissant les métadonnées de l'instance et les credentials IAM temporaires.
mem_used_percent	Nom de métrique publié par l'agent CloudWatch représentant le pourcentage de mémoire RAM utilisée sur l'instance, calculé à partir de `/proc/meminfo` sur Linux.

Rechercher dans ce blog

SW BBANG F