Claude Code × AWS CloudWatch: logs, métricas, alarmas, dashboards e incidentes

En un incidente de producción, el problema no siempre es la falta de logs. Muchas veces hay demasiados logs, con campos inconsistentes, alarmas ruidosas y ninguna ruta clara para pasar del síntoma a una decisión. AWS CloudWatch ofrece Logs, Metrics, Alarms, Dashboards y Logs Insights, pero esas piezas solo ayudan si el sistema emite datos estructurados y el equipo tiene consultas y runbooks repetibles.

Esta guía muestra cómo usar Claude Code para convertir CloudWatch en un flujo práctico de observabilidad para Lambda, ECS, API Gateway, ALB y métricas de negocio. No se trata de dejar que un agente cambie producción sin control. La idea es acelerar las partes repetitivas: formato de logs JSON, consultas Logs Insights, filtros de métricas, alarmas CloudFormation/SAM, widgets de dashboard, permisos IAM de solo lectura y prompts de revisión de incidentes.

Algunos términos en claro: un log estructurado es un log con campos estables, normalmente JSON. Una métrica es una serie numérica como cantidad de requests, errores 5xx o latencia p95. Una alarma es una regla sobre una métrica. Un runbook es una lista de pasos para responder a un incidente. Mínimo privilegio significa dar a Claude Code solo los permisos necesarios, empezando por lectura.

Arquitectura de trabajo

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

Claude Code funciona mejor cuando recibe entradas concretas: formato del log, ventana temporal, nombres de servicios, intención de la alarma y comandos permitidos. Úsalo como generador y revisor rápido, no como operador autónomo de producción.

Casos de uso reales

Primer caso: un batch de Lambda falla. Las líneas REPORT no explican la causa de negocio. Añade jobId, nombre del proveedor externo, número de reintentos y nombre de excepción al log JSON. Luego pide a Claude Code que revise las dos últimas horas y separe hechos de hipótesis: ¿falló un proveedor, una versión desplegada o una clase de entradas?

Segundo caso: aumentan los 5xx en una API ECS. La métrica HTTPCode_Target_5XX_Count del ALB indica que algo falló, pero no dónde. Con Logs Insights agrupando por route, statusCode y durationMs, Claude Code puede resumir rutas con más errores, p95 más alto y errores nuevos tras el último despliegue.

Tercer caso: latencia en API Gateway. Comparar Latency con IntegrationLatency ayuda a distinguir si el problema está en Gateway, authorizers o backend Lambda/ECS. Un dashboard con p95 y p99 es más útil que mirar solo promedios.

Cuarto caso: fatiga de alarmas. Warning puede ir a Slack; Critical puede escalar a PagerDuty. Alarmas que responden a la misma causa se pueden agrupar. TreatMissingData debe estar definido explícitamente.

Emitir logs JSON estructurados

Este logger de Node.js funciona tanto en Lambda como en ECS. Lo importante es mantener nombres de campos estables.

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

Prueba local:

node logger.mjs | jq .

No registres números de tarjeta, tokens ni correos completos. CloudWatch Logs tiene funciones de protección de datos, pero la mejor defensa es no emitir información sensible desde la aplicación.

Consultas Logs Insights con Claude Code

Describe el esquema del log y el objetivo operacional. Eso produce mejores consultas que pedir “consultas de CloudWatch” de forma genérica.

claude -p "
Crea consultas CloudWatch Logs Insights.
Los logs son JSON con timestamp, level, message, service, route, statusCode, durationMs, requestId, userId.
Necesito:
1. Top 10 de rutas por errores 5xx en la última hora
2. Rutas con mayor latencia p95
3. Línea temporal para un requestId
4. errorName que aumentaron tras un despliegue
Devuelve solo las consultas con comentarios breves.
"

Kit inicial:

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

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

-- línea temporal de requestId
fields @timestamp, level, message, route, statusCode, durationMs
| filter requestId = "req-123"
| sort @timestamp asc

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

La trampa de coste es escanear demasiados datos. Limita siempre la ventana temporal y consulta solo los log groups necesarios.

Metric Filter y alarma SAM

Cuando un evento de log debe convertirse en métrica, usa Metric Filter. Este fragmento CloudFormation/SAM crea un grupo de logs, un filtro y una alarma.

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-1:123456789012:prod-alerts

EvaluationPeriods define cuántos periodos se evalúan. DatapointsToAlarm define cuántos deben superar el umbral. Un periodo es rápido pero ruidoso; demasiados periodos detectan tarde.

Dashboard como JSON

Un dashboard creado solo a mano en consola es difícil de reproducir. Guárdalo como JSON y pide a Claude Code que añada filas para Lambda, ECS, API Gateway, ALB y negocio.

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

Prompt de incidente e IAM

Durante un incidente, delimita comandos y log groups.

claude -p "
Revisa este incidente de producción. Separa hechos de hipótesis.
Alcance:
- 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
- cambio reciente: checkout-api v1.42.0 deploy
Comandos permitidos de solo lectura:
- aws logs start-query / get-query-results
- aws cloudwatch get-metric-data
- aws cloudwatch describe-alarms
Salida: timeline, impacto, top 3 hipótesis, mitigación inmediata, prevención y alarmas faltantes.
"

Rol inicial de solo lectura:

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

Errores frecuentes

La fatiga de alarmas aparece cuando cada síntoma técnico despierta a alguien. Prioriza métricas cercanas al usuario: 5xx, p95, colas atascadas, checkout fallido y jobs fallidos.

La retención ilimitada de logs es una fuga de coste silenciosa. Define retención en Lambda y ECS; amplía solo lo que necesite auditoría.

Las métricas de alta cardinalidad son caras y difíciles de leer. No uses userId ni requestId como dimensiones. Déjalos en logs y agrega métricas por servicio, ruta, entorno y clase de error.

Tampoco pegues logs sin límite en Claude Code. Consulta primero, reduce la ventana, enmascara datos sensibles y pide conclusiones con evidencia.

Siguiente paso

Elige una API crítica e implementa cinco piezas: logs JSON, consulta 5xx, consulta p95, una alarma Critical y una fila de dashboard. Después conecta esta base con Claude Code × AWS ECS/Fargate y Claude Code × AWS IAM.

Verificación práctica: comprobé la salida del logger con jq, y el fragmento SAM está listo para adaptarse a una plantilla real cambiando nombres, región, cuenta y ARN de SNS. Ajusta umbrales en una cuenta de prueba antes de avisar a personas reales.

Referencias oficiales

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