Claude Code × AWS CloudWatch: Logs, Metriken, Alarme, Dashboards und Incidents

Bei einem Produktionsvorfall ist nicht immer fehlendes Logging das Hauptproblem. Oft gibt es sehr viele Logs, uneinheitliche Felder, zu laute Alarme und keinen klaren Weg von einem Symptom zu einer Entscheidung. AWS CloudWatch bietet Logs, Metrics, Alarms, Dashboards und Logs Insights. Nützlich wird das Ganze aber erst, wenn Anwendungen strukturierte Daten ausgeben und das Team wiederholbare Abfragen und Runbooks besitzt.

Dieser Leitfaden zeigt, wie Claude Code CloudWatch in einen konkreten Observability-Workflow für Lambda, ECS, API Gateway, ALB und Business-Metriken verwandeln kann. Es geht nicht darum, einen Agenten unkontrolliert Produktion ändern zu lassen. Claude Code soll die mühsamen Teile beschleunigen: JSON-Logformat, Logs-Insights-Abfragen, Metric Filter, CloudFormation/SAM-Alarme, Dashboard-Widgets, IAM-Lesezugriff und Prompts für Incident-Reviews.

Kurz erklärt: Strukturierte Logs sind Logs mit stabilen Feldern, meist JSON. Metriken sind Zahlenreihen wie Request Count, 5xx Count oder p95-Latenz. Alarme sind Regeln auf Metriken. Ein Runbook ist eine Checkliste für die Reaktion im Incident. Least Privilege bedeutet, Claude Code zunächst nur die nötigen Leserechte zu geben.

Architektur

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

Claude Code liefert die besten Ergebnisse, wenn Eingaben präzise sind: Logformat, Zeitfenster, Servicenamen, Alarmziel und erlaubte Befehle. Es ist Generator und Reviewer, nicht autonomer Operator.

Reale Einsatzfälle

Erster Fall: Ein Lambda-Batch schlägt fehl. REPORT-Zeilen erklären selten die fachliche Ursache. Ergänze jobId, externen Anbieter, Retry-Zahl und Exception-Name im JSON-Log. Danach kann Claude Code prüfen, ob Fehler der letzten zwei Stunden an einem Anbieter, einem Deployment oder einer Eingabeklasse hängen.

Zweiter Fall: 5xx in einer ECS-API steigen. Die ALB-Metrik HTTPCode_Target_5XX_Count zeigt nur, dass Targets Fehler liefern. Mit Logs Insights nach route, statusCode und durationMs gruppiert kann Claude Code die lautesten Routen, die höchsten p95-Werte und neue Fehler nach dem Deployment zusammenfassen.

Dritter Fall: API-Gateway-Latenz. Der Vergleich von Latency und IntegrationLatency zeigt, ob das Gateway, ein Authorizer oder das Backend langsam ist. Ein Dashboard mit p95 und p99 ist operativ nützlicher als ein Durchschnitt.

Vierter Fall: Alarmmüdigkeit. Warning geht in Slack, Critical an PagerDuty. Mehrere Symptome derselben Ursache können als Composite Alarm gebündelt werden. TreatMissingData sollte nie implizit bleiben.

Strukturierte JSON-Logs ausgeben

Dieser Node.js-Logger funktioniert in Lambda und ECS. Wichtig sind konstante Feldnamen.

// 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"),
});

Lokaler Test:

node logger.mjs | jq .

Kreditkartennummern, Tokens und vollständige E-Mail-Adressen gehören nicht ins Log. CloudWatch Logs kann Daten schützen, aber die bessere Lösung ist, sensible Werte gar nicht erst auszugeben.

Logs-Insights-Abfragen erzeugen

Gib Claude Code Schema und Fragestellung.

claude -p "
Erzeuge CloudWatch Logs Insights Queries.
Die Logs sind JSON mit timestamp, level, message, service, route, statusCode, durationMs, requestId, userId.
Ich brauche:
1. Top 10 Routen nach 5xx in der letzten Stunde
2. Routen mit höchster p95-Latenz
3. Timeline für eine requestId
4. errorName, die nach einem Deployment zugenommen haben
Nur Queries mit kurzen Kommentaren ausgeben.
"

Startabfragen:

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

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

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

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

Kostenfalle: zu breite Scans. Logs Insights kostet nach gescannter Datenmenge. Zeitfenster und Log Groups eng halten.

Metric Filter und SAM-Alarm

Wenn ein Logevent zu einer CloudWatch-Metrik werden soll, nutze 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-central-1:123456789012:prod-alerts

EvaluationPeriods legt fest, wie viele Perioden betrachtet werden. DatapointsToAlarm legt fest, wie viele davon den Schwellwert reißen müssen.

Dashboard als JSON

Dashboards nur in der Konsole zu pflegen ist schlecht reproduzierbar. Lege JSON im Repository ab.

{
  "widgets": [
    {
      "type": "metric",
      "x": 0,
      "y": 0,
      "width": 12,
      "height": 6,
      "properties": {
        "region": "eu-central-1",
        "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

Incident-Prompt und IAM

Grenze Befehle und Log Groups ein.

claude -p "
Analysiere diesen Produktions-Incident. Trenne Fakten und Hypothesen.
Scope:
- 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
- recent change: checkout-api v1.42.0 deploy
Erlaubte Read-only-Befehle:
- aws logs start-query / get-query-results
- aws cloudwatch get-metric-data
- aws cloudwatch describe-alarms
Ausgabe: Timeline, Auswirkung, Top-3-Hypothesen, Sofortmaßnahme, Prävention, fehlende Alarme.
"

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

Häufige Fallen

Alarmmüdigkeit entsteht, wenn jedes technische Symptom Menschen weckt. Priorisiere nutzernahe Metriken: 5xx, p95, Queue-Backlog, Checkout-Fehler und fehlgeschlagene Jobs.

Unbegrenzte Logaufbewahrung ist eine stille Kostenquelle. Setze Retention für Lambda und ECS; verlängere nur auditrelevante Logs.

High-Cardinality-Metriken sind teuer und unübersichtlich. userId und requestId gehören in Logs, nicht in Metric Dimensions.

Kopiere auch nicht unbegrenzt Logs in Claude Code. Erst abfragen, Zeitfenster verkleinern, sensible Daten maskieren und belegbare Schlussfolgerungen verlangen.

Nächster Schritt

Wähle eine kritische API und implementiere fünf Teile: JSON-Logs, 5xx-Query, p95-Query, einen Critical-Alarm und eine Dashboard-Zeile. Verbinde das danach mit Claude Code × AWS ECS/Fargate und Claude Code × AWS IAM.

Praktische Prüfung: Die Logger-Ausgabe habe ich lokal mit jq geprüft. Das SAM-Fragment ist so aufgebaut, dass du Namen, Region, Konto und SNS-ARN ersetzen und es in eine bestehende Vorlage übernehmen kannst. Schwellenwerte zuerst in einem Testkonto kalibrieren.

Offizielle Quellen

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