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

Em um incidente de produção, o problema nem sempre é a falta de logs. Muitas vezes existem logs demais, campos inconsistentes, alarmes barulhentos e nenhum caminho claro entre o sintoma e a decisão. O AWS CloudWatch oferece Logs, Metrics, Alarms, Dashboards e Logs Insights, mas essas peças só ajudam quando a aplicação emite dados estruturados e o time tem consultas e runbooks repetíveis.

Este guia mostra como usar Claude Code para transformar CloudWatch em um fluxo prático de observabilidade para Lambda, ECS, API Gateway, ALB e métricas de negócio. A ideia não é deixar um agente alterar produção sem revisão. A ideia é acelerar as partes repetitivas: formato de logs JSON, consultas Logs Insights, filtros de métricas, alarmes CloudFormation/SAM, widgets de dashboard, IAM de leitura e prompt de revisão de incidente.

Termos rápidos: log estruturado é log com campos estáveis, normalmente JSON. Métrica é uma série numérica como requests, 5xx ou latência p95. Alarme é uma regra sobre uma métrica. Runbook é o checklist de resposta. Menor privilégio significa dar ao Claude Code apenas as permissões necessárias, começando por leitura.

Arquitetura

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["Revisão com Claude Code"]
  Alarms --> Runbook["SNS / PagerDuty / runbook"]

Claude Code funciona melhor com entradas objetivas: formato do log, janela de tempo, serviços, intenção do alarme e comandos permitidos. Use como gerador e revisor, não como operador autônomo.

Casos reais de uso

Primeiro: falha em batch Lambda. Linhas REPORT não explicam a causa de negócio. Inclua jobId, API externa, tentativas e nome da exceção no log JSON. Depois peça ao Claude Code para verificar se as falhas das últimas duas horas se concentram em um fornecedor, deploy ou tipo de entrada.

Segundo: aumento de 5xx em uma API ECS. A métrica HTTPCode_Target_5XX_Count do ALB mostra que algo falhou, mas não onde. Com Logs Insights agrupando por route, statusCode e durationMs, Claude Code resume rotas mais problemáticas, maiores p95 e erros novos depois do deploy.

Terceiro: latência no API Gateway. Comparar Latency e IntegrationLatency ajuda a separar problema de gateway, authorizer ou backend Lambda/ECS. Dashboard com p95 e p99 é melhor que média.

Quarto: fadiga de alarmes. Warning pode ir para Slack; Critical para PagerDuty. Alarmes da mesma causa podem virar composite alarm. TreatMissingData precisa estar explícito.

Emitir logs JSON estruturados

Este logger Node.js serve para Lambda e ECS.

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

Teste local:

node logger.mjs | jq .

Não registre número de cartão, token ou e-mail completo. CloudWatch Logs tem recursos de proteção, mas o melhor é não emitir dados sensíveis.

Consultas Logs Insights

Passe ao Claude Code o schema do log e a pergunta operacional.

claude -p "
Crie consultas CloudWatch Logs Insights.
Os logs são JSON com timestamp, level, message, service, route, statusCode, durationMs, requestId, userId.
Preciso de:
1. Top 10 rotas por 5xx na última hora
2. Rotas com maior latência p95
3. Linha do tempo para um requestId
4. errorName que aumentaram após um deploy
Retorne só as consultas com comentários curtos.
"

Consultas iniciais:

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

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

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

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

A armadilha de custo é varrer dados demais. Restrinja tempo e log groups.

Metric Filter e alarme SAM

Use Metric Filter quando um evento de log precisa virar métrica.

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

EvaluationPeriods define quantos períodos são avaliados. DatapointsToAlarm define quantos precisam violar o limite.

Dashboard em JSON

Dashboard feito apenas no console é difícil de reproduzir.

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

Limite comandos e log groups.

claude -p "
Revise este incidente de produção. Separe fatos de hipóteses.
Escopo:
- 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
- mudança recente: checkout-api v1.42.0 deploy
Comandos somente leitura permitidos:
- aws logs start-query / get-query-results
- aws cloudwatch get-metric-data
- aws cloudwatch describe-alarms
Saída: timeline, impacto, top 3 hipóteses, mitigação imediata, prevenção e alarmes faltantes.
"

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

Armadilhas comuns

Fadiga de alarmes acontece quando todo sintoma técnico chama alguém. Prefira métricas próximas do usuário: 5xx, p95, backlog, falha de checkout e jobs falhos.

Retenção ilimitada de logs vira custo silencioso. Configure retenção em Lambda e ECS; mantenha mais tempo apenas o que tiver requisito de auditoria.

Métricas de alta cardinalidade são caras. Não use userId ou requestId como dimensions. Detalhes ficam nos logs; agregações ficam nas métricas.

Também não cole logs sem limite no Claude Code. Consulte primeiro, reduza a janela, mascare dados sensíveis e peça conclusões com evidência.

Próximo passo

Escolha uma API crítica e implemente cinco itens: logs JSON, consulta 5xx, consulta p95, um alarme Critical e uma linha de dashboard. Depois conecte com Claude Code × AWS ECS/Fargate e Claude Code × AWS IAM.

Verificação prática: testei a saída do logger com jq, e o trecho SAM está pronto para adaptação com nomes, região, conta e ARN de SNS. Ajuste limiares em conta de teste antes de acionar pessoas de plantão.

Referências oficiais

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