Claude Code × AWS CloudWatch Guia Completo | Análise de Logs, Alarmes e Dashboards Automáticos

“Aconteceu um erro em produção! Mas há tantos logs que não sei por onde começar.” — O pânico clássico durante a gestão de incidentes.

O CloudWatch é o serviço de monitoramento padrão da AWS, mas com volumes enormes de logs as informações críticas ficam soterradas e a configuração de alarmes costuma ser adiada. Eu monitoro um sistema ECS + Lambda no trabalho, e deixar o Claude Code ler os logs para identificar a causa reduziu nosso tempo médio de resposta a incidentes em 40%.

Este artigo explica passo a passo como automatizar a análise de logs do CloudWatch, o design de alarmes e a construção de dashboards com o Claude Code.

---

Principais Componentes do CloudWatch

CloudWatch Logs      : Armazenar e pesquisar logs de apps e serviços AWS
CloudWatch Metrics   : Dados numéricos como uso de CPU e contagem de requisições
CloudWatch Alarms    : Detectar limites excedidos em métricas e notificar SNS etc.
CloudWatch Dashboards: Visualizações personalizadas de métricas e logs
Log Insights         : Motor de consultas similar a SQL para analisar logs

---

Passo 1: Delegar a Análise de Padrões de Logs ao Claude Code

Durante um incidente, a primeira prioridade é entender o padrão dos logs de erro.

# Obter logs de erro da última hora
aws logs filter-log-events \
  --log-group-name "/ecs/myapp" \
  --start-time $(date -d "1 hour ago" +%s000) \
  --filter-pattern "ERROR" \
  --output json > error-logs.json

claude -p "
Analise os seguintes logs de erro do CloudWatch e:

1. Classifique os erros por tipo (5xx, 4xx, erros de conexão ao BD, timeouts, etc.)
2. Identifique o erro mais frequente
3. Determine o momento em que os erros dispararam
4. Proponha hipóteses sobre a causa raiz
5. Sugira os próximos passos de investigação

$(cat error-logs.json | head -500)
"

Gerar Automaticamente Consultas do Log Insights

claude -p "
Gere consultas do CloudWatch Log Insights para os seguintes propósitos:

1. Taxa de erro por endpoint na última hora (top 10)
2. Detalhes de requisições com latência acima de 500 ms
3. Todos os logs de operações de um usuário específico (user_id: 12345)
4. Primeiros erros ocorridos nos 30 minutos após um deploy

Formato de log: JSON (timestamp, level, message, user_id, endpoint, duration_ms, status_code)
"

Exemplo de consultas do Log Insights geradas:

-- Taxa de erro por endpoint
fields @timestamp, endpoint, status_code
| filter status_code >= 400
| stats count() as error_count by endpoint
| sort error_count desc
| limit 10

-- Requisições com latência acima de 500 ms
fields @timestamp, endpoint, duration_ms, user_id
| filter duration_ms > 500
| sort duration_ms desc
| limit 50

-- Logs de operações de um usuário específico
fields @timestamp, level, message, endpoint
| filter user_id = "12345"
| sort @timestamp desc
| limit 100

---

Passo 2: Gerar Automaticamente a Configuração de Alarmes

claude -p "
Projete todos os alarmes do CloudWatch necessários para o sistema abaixo.
Implemente em CDK TypeScript.

[Arquitetura do Sistema]
- ECS Fargate (servidor de API, 2–10 instâncias)
- RDS PostgreSQL
- ALB (Application Load Balancer)
- Lambda (processamento em lote)

[Requisitos de Alarmes]
- Produção: alarmes disparados em menos de 5 minutos
- Destinos de notificação: SNS → Slack e PagerDuty
- Alarmes em dois níveis (Warning / Critical)
- Fora do horário comercial: apenas Critical
"

// lib/monitoring-stack.ts
import * as cdk from "aws-cdk-lib";
import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
import * as actions from "aws-cdk-lib/aws-cloudwatch-actions";
import * as sns from "aws-cdk-lib/aws-sns";

export class MonitoringStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const alertTopic = sns.Topic.fromTopicArn(
      this, "AlertTopic",
      `arn:aws:sns:${this.region}:${this.account}:prod-alerts`
    );
    const warnTopic = sns.Topic.fromTopicArn(
      this, "WarnTopic",
      `arn:aws:sns:${this.region}:${this.account}:prod-warnings`
    );

    // Alarme de taxa de erro 5xx do ALB
    const alb5xxAlarm = new cloudwatch.Alarm(this, "Alb5xxAlarm", {
      alarmName: "prod-alb-5xx-critical",
      alarmDescription: "Taxa de erro 5xx do ALB ultrapassou 5%",
      metric: new cloudwatch.Metric({
        namespace: "AWS/ApplicationELB",
        metricName: "HTTPCode_Target_5XX_Count",
        dimensionsMap: { LoadBalancer: "app/myapp/xxx" },
        statistic: "Sum",
        period: cdk.Duration.minutes(5),
      }),
      threshold: 10,
      evaluationPeriods: 2,
      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
    });
    alb5xxAlarm.addAlarmAction(new actions.SnsAction(alertTopic));

    // Alarme de uso de CPU do ECS (Warning/Critical)
    const ecsCpuWarning = new cloudwatch.Alarm(this, "EcsCpuWarning", {
      alarmName: "prod-ecs-cpu-warning",
      metric: new cloudwatch.Metric({
        namespace: "AWS/ECS",
        metricName: "CPUUtilization",
        dimensionsMap: { ClusterName: "myapp-cluster", ServiceName: "myapp-service" },
        statistic: "Average",
        period: cdk.Duration.minutes(5),
      }),
      threshold: 70,
      evaluationPeriods: 3,
    });
    ecsCpuWarning.addAlarmAction(new actions.SnsAction(warnTopic));

    const ecsCpuCritical = new cloudwatch.Alarm(this, "EcsCpuCritical", {
      alarmName: "prod-ecs-cpu-critical",
      metric: new cloudwatch.Metric({
        namespace: "AWS/ECS",
        metricName: "CPUUtilization",
        dimensionsMap: { ClusterName: "myapp-cluster", ServiceName: "myapp-service" },
        statistic: "Average",
        period: cdk.Duration.minutes(5),
      }),
      threshold: 90,
      evaluationPeriods: 2,
    });
    ecsCpuCritical.addAlarmAction(new actions.SnsAction(alertTopic));

    // Alarme de número de conexões do RDS
    const rdsConnectionAlarm = new cloudwatch.Alarm(this, "RdsConnectionAlarm", {
      alarmName: "prod-rds-connections-critical",
      metric: new cloudwatch.Metric({
        namespace: "AWS/RDS",
        metricName: "DatabaseConnections",
        dimensionsMap: { DBInstanceIdentifier: "myapp-db" },
        statistic: "Maximum",
        period: cdk.Duration.minutes(5),
      }),
      threshold: 80,  // 80% das conexões máximas do db.t3.micro
      evaluationPeriods: 2,
    });
    rdsConnectionAlarm.addAlarmAction(new actions.SnsAction(alertTopic));

    // Alarme de erros do Lambda
    const lambdaErrorAlarm = new cloudwatch.Alarm(this, "LambdaErrorAlarm", {
      alarmName: "prod-lambda-errors-critical",
      metric: new cloudwatch.Metric({
        namespace: "AWS/Lambda",
        metricName: "Errors",
        dimensionsMap: { FunctionName: "myapp-batch" },
        statistic: "Sum",
        period: cdk.Duration.minutes(15),
      }),
      threshold: 5,
      evaluationPeriods: 1,
    });
    lambdaErrorAlarm.addAlarmAction(new actions.SnsAction(alertTopic));
  }
}

---

Passo 3: Gerar Automaticamente um Dashboard Personalizado

claude -p "
Gere um dashboard do CloudWatch em CDK que exiba as seguintes informações.

[Layout do Dashboard]
Linha 1: Saúde geral do sistema (requisições ALB, taxa 5xx, latência P50/P95/P99)
Linha 2: Serviço ECS (CPU, memória, número de tasks em execução)
Linha 3: RDS (conexões, latência, uso de CPU)
Linha 4: Lambda (invocações, erros, duração)
Linha 5: Métricas de negócio (novos cadastros, taxa de sucesso de pagamentos) ← métricas personalizadas
"

// Definição do dashboard (trecho)
const dashboard = new cloudwatch.Dashboard(this, "AppDashboard", {
  dashboardName: "myapp-production",
});

dashboard.addWidgets(
  new cloudwatch.Row(
    new cloudwatch.GraphWidget({
      title: "Requisições ALB",
      left: [new cloudwatch.Metric({
        namespace: "AWS/ApplicationELB",
        metricName: "RequestCount",
        statistic: "Sum",
        period: cdk.Duration.minutes(1),
      })],
      width: 8,
    }),
    new cloudwatch.GraphWidget({
      title: "Taxa de Erro 5xx do ALB (%)",
      left: [new cloudwatch.MathExpression({
        expression: "5xx / (2xx + 3xx + 4xx + 5xx) * 100",
        usingMetrics: {
          "5xx": new cloudwatch.Metric({ metricName: "HTTPCode_Target_5XX_Count", namespace: "AWS/ApplicationELB", statistic: "Sum" }),
          "2xx": new cloudwatch.Metric({ metricName: "HTTPCode_Target_2XX_Count", namespace: "AWS/ApplicationELB", statistic: "Sum" }),
          "3xx": new cloudwatch.Metric({ metricName: "HTTPCode_Target_3XX_Count", namespace: "AWS/ApplicationELB", statistic: "Sum" }),
          "4xx": new cloudwatch.Metric({ metricName: "HTTPCode_Target_4XX_Count", namespace: "AWS/ApplicationELB", statistic: "Sum" }),
        },
        period: cdk.Duration.minutes(1),
      })],
      width: 8,
    }),
  )
);

---

Passo 4: Delegar a Investigação de Incidentes ao Claude Code

claude -p "
Quero investigar um incidente em produção. Execute os seguintes comandos e analise os resultados:

1. aws logs filter-log-events --log-group-name '/ecs/myapp' \
   --start-time \$(date -d '2 hours ago' +%s000) \
   --filter-pattern 'ERROR' --limit 100

2. aws cloudwatch get-metric-statistics \
   --namespace AWS/ApplicationELB \
   --metric-name HTTPCode_Target_5XX_Count \
   --start-time \$(date -d '2 hours ago' -u +%Y-%m-%dT%H:%M:%SZ) \
   --end-time \$(date -u +%Y-%m-%dT%H:%M:%SZ) \
   --period 300 --statistics Sum

Com base nos resultados acima, resuma:
- Horário de início do incidente
- Número estimado de usuários afetados
- Top 3 hipóteses da causa raiz
- Ações de resposta imediata
"

---

Passo 5: Projetar Métricas Personalizadas Automaticamente

claude -p "
Gere código Node.js (AWS SDK v3) para medir os seguintes KPIs de negócio de um e-commerce
como métricas personalizadas do CloudWatch.

Métricas a medir:
- Número de pagamentos bem-sucedidos e falhos (a cada minuto)
- Taxa de abandono de carrinho (a cada 5 minutos)
- Novos cadastros de membros (a cada hora)

Namespace: MyApp/Business
Adicionar tag de ambiente a cada métrica (Production/Staging)
"

// src/monitoring/business-metrics.ts
import { CloudWatchClient, PutMetricDataCommand } from "@aws-sdk/client-cloudwatch";

const cw = new CloudWatchClient({ region: process.env.AWS_REGION });
const NAMESPACE = "MyApp/Business";
const ENV = process.env.NODE_ENV ?? "development";

export async function recordPaymentSuccess() {
  await cw.send(new PutMetricDataCommand({
    Namespace: NAMESPACE,
    MetricData: [{
      MetricName: "PaymentSuccess",
      Value: 1,
      Unit: "Count",
      Dimensions: [{ Name: "Environment", Value: ENV }],
    }],
  }));
}

export async function recordPaymentFailure(reason: string) {
  await cw.send(new PutMetricDataCommand({
    Namespace: NAMESPACE,
    MetricData: [{
      MetricName: "PaymentFailure",
      Value: 1,
      Unit: "Count",
      Dimensions: [
        { Name: "Environment", Value: ENV },
        { Name: "Reason", Value: reason },
      ],
    }],
  }));
}

---

4 Armadilhas Comuns a Evitar

1. evaluationPeriods muito curto

// ❌ Alarme dispara em picos momentâneos
evaluationPeriods: 1,
threshold: 10,

// ✅ Alarme só dispara após 3 períodos consecutivos (reduz falsos positivos)
evaluationPeriods: 3,
threshold: 10,
datapointsToAlarm: 2,  // Alarme quando o limite é excedido em 2 de 3 períodos

2. Ignorar os custos do Log Insights

O Log Insights cobra com base na quantidade de dados varridos. Executar consultas sem limitar o intervalo de tempo pode gerar cobranças inesperadas. Sempre especifique --start-time e --end-time.

3. Métricas personalizadas de alta resolução são caras

Métricas padrão (60 segundos) são gratuitas, mas métricas de alta resolução (1 segundo) custam cerca de 10 vezes mais. Agregação de 1 minuto geralmente é suficiente para métricas de negócio.

4. Não configurar o período de retenção de logs do Lambda

O padrão é “Nunca expirar”, fazendo os custos de armazenamento crescerem indefinidamente. Sempre configure um período de retenção nos grupos de logs.

new logs.LogGroup(this, "AppLogGroup", {
  logGroupName: "/ecs/myapp",
  retention: logs.RetentionDays.ONE_MONTH,  // Exclusão automática após 30 dias
});

---

Resumo

Tarefa	Contribuição do Claude Code
Análise de logs	Lê logs de erro e propõe hipóteses de causa raiz com etapas de solução
Consultas Log Insights	Gera consultas a partir de uma descrição do objetivo de análise
Configuração de alarmes	Gera código CDK em bloco a partir de uma descrição do sistema
Dashboard	Gera definições de widgets a partir de uma descrição do que quer exibir
Investigação de incidentes	Executa comandos AWS CLI e analisa os resultados

“Vamos configurar o monitoramento depois” — e então um incidente acontece e não há visibilidade alguma. Com o Claude Code, você pode ter alarmes e dashboards de nível produção prontos em 30 minutos.

Artigos Relacionados

• Claude Code × AWS ECS/Fargate Guia Completo
• Claude Code × AWS CodePipeline/CodeBuild Guia Completo
• Claude Code × AWS IAM Guia Completo

Referências

• Documentação Oficial do Amazon CloudWatch
• Sintaxe de Consultas do CloudWatch Log Insights
• Módulo CDK CloudWatch