Claude Code × AWS CloudWatch : logs, métriques, alarmes, dashboards et incidents

Lors d’un incident de production, le pire n’est pas toujours l’absence de logs. Le cas le plus courant est plutôt l’inverse : trop de logs, des champs incohérents, des alarmes bruyantes et aucune méthode claire pour passer du symptôme à la décision. AWS CloudWatch fournit Logs, Metrics, Alarms, Dashboards et Logs Insights, mais ces briques ne deviennent utiles que si l’application émet des données structurées et si l’équipe dispose de requêtes et de runbooks répétables.

Ce guide montre comment utiliser Claude Code pour transformer CloudWatch en workflow concret d’observabilité pour Lambda, ECS, API Gateway, ALB et les métriques métier. L’objectif n’est pas de laisser un agent modifier la production sans contrôle. L’objectif est de générer et relire plus vite les parties répétitives : logs JSON, requêtes Logs Insights, filtres de métriques, alarmes CloudFormation/SAM, widgets de dashboard, permissions IAM en lecture seule et prompt de revue d’incident.

Quelques termes simples : un log structuré est un log avec des champs stables, souvent en JSON. Une métrique est une série numérique comme le nombre de requêtes, les 5xx ou la latence p95. Une alarme est une règle sur une métrique. Un runbook est une procédure à suivre pendant un incident. Le moindre privilège consiste à donner à Claude Code uniquement les permissions nécessaires, d’abord en lecture.

Architecture

flowchart LR
  App["Lambda / ECS / API Gateway"] --> Logs["CloudWatch Logs"]
  App --> Metrics["CloudWatch Metrics"]
  Logs --> Insights["Requêtes Logs Insights"]
  Logs --> Filter["Metric filters"]
  Metrics --> Alarms["CloudWatch Alarms"]
  Metrics --> Dash["Dashboards"]
  Insights --> Claude["Revue avec Claude Code"]
  Alarms --> Runbook["SNS / PagerDuty / runbook"]

Claude Code donne de meilleurs résultats quand le contexte est précis : format des logs, fenêtre temporelle, services visés, intention de l’alarme et commandes autorisées.

Cas d’usage réels

Premier cas : un batch Lambda échoue. Les lignes REPORT ne suffisent pas à comprendre la cause métier. Ajoutez jobId, nom du fournisseur externe, nombre de tentatives et nom d’exception dans les logs JSON. Claude Code peut ensuite résumer si les échecs des deux dernières heures sont liés à un fournisseur, une version déployée ou une classe d’entrées.

Deuxième cas : les 5xx augmentent sur une API ECS. La métrique ALB HTTPCode_Target_5XX_Count signale le problème mais pas l’endroit. Avec Logs Insights groupé par route, statusCode et durationMs, Claude Code peut lister les routes les plus bruyantes, les p95 les plus élevées et les erreurs apparues après le dernier déploiement.

Troisième cas : latence API Gateway. Comparer Latency et IntegrationLatency aide à savoir si le problème vient de Gateway, d’un authorizer ou du backend Lambda/ECS. Le dashboard doit montrer p95 et p99, pas uniquement la moyenne.

Quatrième cas : fatigue d’alarme. Les Warning peuvent aller vers Slack, les Critical vers PagerDuty. Plusieurs alarmes liées à la même cause peuvent être regroupées. TreatMissingData doit être explicite.

Émettre des logs JSON structurés

Ce logger Node.js fonctionne dans Lambda ou ECS. Les noms de champs restent constants pour faciliter les requêtes.

// logger.mjs
export function logEvent(level, message, fields = {}) {
  const entry = {
    timestamp: new Date().toISOString(),
    level,
    message,
    service: process.env.SERVICE_NAME || "checkout-api",
    env: process.env.NODE_ENV || "development",
    requestId: fields.requestId || "unknown",
    route: fields.route,
    statusCode: fields.statusCode,
    durationMs: fields.durationMs,
    userId: fields.userId,
    errorName: fields.error?.name,
    errorMessage: fields.error?.message,
  };

  console.log(JSON.stringify(entry));
}

logEvent("ERROR", "payment authorization failed", {
  requestId: "req-123",
  route: "POST /checkout",
  statusCode: 502,
  durationMs: 842,
  userId: "user-456",
  error: new Error("upstream timeout"),
});

Test local :

node logger.mjs | jq .

Ne journalisez pas les numéros de carte, les tokens ou les e-mails complets. CloudWatch Logs propose des protections de données, mais la meilleure défense est de ne pas émettre ces valeurs.

Générer les requêtes Logs Insights

Donnez à Claude Code le schéma des logs et la question opérationnelle.

claude -p "
Crée des requêtes CloudWatch Logs Insights.
Les logs sont en JSON avec timestamp, level, message, service, route, statusCode, durationMs, requestId, userId.
Besoins:
1. Top 10 des routes par nombre de 5xx sur la dernière heure
2. Routes avec la plus forte latence p95
3. Timeline pour un requestId
4. errorName qui augmentent après un déploiement
Retourne seulement les requêtes avec de courts commentaires.
"

Exemples utilisables :

-- 5xx par route
fields @timestamp, route, statusCode, requestId
| filter statusCode >= 500
| stats count(*) as errors by route
| sort errors desc
| limit 10

-- latence p95 par route
fields route, durationMs
| filter ispresent(durationMs)
| stats pct(durationMs, 95) as p95, count(*) as requests by route
| sort p95 desc
| limit 20

-- timeline requestId
fields @timestamp, level, message, route, statusCode, durationMs
| filter requestId = "req-123"
| sort @timestamp asc

-- erreurs par nom
fields @timestamp, errorName, route
| filter level = "ERROR" and ispresent(errorName)
| stats count(*) as count by errorName, route
| sort count desc
| limit 20

Le piège de coût est de scanner trop large. Limitez la période et les log groups interrogés.

Metric Filter et alarme SAM

Un événement de log peut devenir une métrique CloudWatch grâce à Metric Filter.

Resources:
  CheckoutLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: /aws/lambda/checkout-api
      RetentionInDays: 30

  PaymentFailureMetricFilter:
    Type: AWS::Logs::MetricFilter
    Properties:
      LogGroupName: !Ref CheckoutLogGroup
      FilterPattern: '{ $.level = "ERROR" && $.message = "payment authorization failed" }'
      MetricTransformations:
        - MetricNamespace: MyApp/Business
          MetricName: PaymentFailure
          MetricValue: "1"
          DefaultValue: 0

  PaymentFailureAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: prod-payment-failure-critical
      AlarmDescription: Five or more payment failures in ten minutes
      Namespace: MyApp/Business
      MetricName: PaymentFailure
      Statistic: Sum
      Period: 300
      EvaluationPeriods: 2
      DatapointsToAlarm: 2
      Threshold: 5
      ComparisonOperator: GreaterThanOrEqualToThreshold
      TreatMissingData: notBreaching
      AlarmActions:
        - arn:aws:sns:eu-west-3:123456789012:prod-alerts

EvaluationPeriods indique combien de périodes sont évaluées. DatapointsToAlarm indique combien doivent dépasser le seuil. Une seule période est rapide mais bruyante ; trop de périodes détectent trop tard.

Gérer le dashboard en JSON

Un dashboard uniquement créé dans la console est difficile à reproduire. Stockez le JSON et faites ajouter les lignes Lambda, ECS, API Gateway, ALB et métier par Claude Code.

{
  "widgets": [
    {
      "type": "metric",
      "x": 0,
      "y": 0,
      "width": 12,
      "height": 6,
      "properties": {
        "region": "eu-west-3",
        "title": "API health: requests, 5xx, latency",
        "view": "timeSeries",
        "metrics": [
          ["AWS/ApplicationELB", "RequestCount", "LoadBalancer", "app/myapp/abc", { "stat": "Sum" }],
          [".", "HTTPCode_Target_5XX_Count", ".", ".", { "stat": "Sum", "yAxis": "right" }],
          ["AWS/ApiGateway", "Latency", "ApiName", "checkout-api", "Stage", "prod", { "stat": "p95" }]
        ],
        "period": 60
      }
    }
  ]
}

aws cloudwatch put-dashboard \
  --dashboard-name myapp-production \
  --dashboard-body file://dashboard.json

Prompt d’incident et IAM

Pendant l’incident, bornez le périmètre et les commandes.

claude -p "
Analyse cet incident de production. Sépare les faits des hypothèses.
Périmètre:
- log groups: /aws/lambda/checkout-api, /ecs/checkout-api
- window: 2026-06-02T10:00:00+09:00 to 2026-06-02T11:00:00+09:00
- changement récent: checkout-api v1.42.0 deploy
Commandes en lecture seule autorisées:
- aws logs start-query / get-query-results
- aws cloudwatch get-metric-data
- aws cloudwatch describe-alarms
Sortie: timeline, impact, top 3 hypothèses, mitigation immédiate, prévention, alarmes manquantes.
"

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:StartQuery",
        "logs:GetQueryResults",
        "logs:FilterLogEvents",
        "cloudwatch:GetMetricData",
        "cloudwatch:DescribeAlarms",
        "cloudwatch:GetDashboard"
      ],
      "Resource": "*"
    }
  ]
}

Pièges fréquents

La fatigue d’alarme arrive quand chaque symptôme technique réveille quelqu’un. Priorisez les métriques proches de l’impact utilisateur : 5xx, p95, backlog, échec de paiement et jobs échoués.

La rétention illimitée des logs est une fuite de coût silencieuse. Configurez la rétention sur Lambda et ECS ; gardez plus longtemps uniquement ce qui sert à l’audit.

Les métriques à forte cardinalité coûtent cher et deviennent illisibles. Ne mettez pas userId ou requestId en dimensions. Gardez ces détails dans les logs.

Enfin, ne collez pas des logs sans limite dans Claude Code. Interrogez d’abord, réduisez la fenêtre, masquez les données sensibles et demandez des conclusions appuyées par des preuves.

Étape suivante

Choisissez une API critique et ajoutez cinq éléments : logs JSON, requête 5xx, requête p95, une alarme Critical et une ligne de dashboard. Reliez ensuite ce socle aux pratiques de Claude Code × AWS ECS/Fargate et Claude Code × AWS IAM.

Vérification pratique : j’ai contrôlé la sortie du logger avec jq, et le fragment SAM est structuré pour être intégré après remplacement des noms, région, compte et ARN SNS. Réglez les seuils dans un compte de test avant de notifier de vrais astreintes.

Références officielles

• Amazon CloudWatch Logs
• CloudWatch Logs Insights query syntax
• Using Amazon CloudWatch alarms
• Using Amazon CloudWatch dashboards
• Identity and access management for Amazon CloudWatch