Lab 52 — SLO, error budget e alarme que acorda alguém

# Rode ANTES de mudar nada. Da conta de estados os ultimos 30 dias.
PROJETO=ffv-lab
for alarme in $(aws cloudwatch describe-alarms --alarm-name-prefix "${PROJETO}-" \
                  --query "MetricAlarms[].AlarmName" --output text); do
  n=$(aws cloudwatch describe-alarm-history --alarm-name "$alarme" \
        --history-item-type StateUpdate \
        --start-date "$(date -u -v-30d +%FT%TZ)" --end-date "$(date -u +%FT%TZ)" \
        --query "length(AlarmHistoryItems)" --output text)
  echo "$alarme: $n transicoes"
done
# Na Cadencia: 40 alarmes, 187 transicoes em 30 dias — media de 6 por dia, todas no
# mesmo topico, para as mesmas seis pessoas. Nenhuma delas distinguia gravidade.

// O que o CloudWatch entrega quando o alarme composto muda de estado. E o payload
// que o modelo do plano de resposta usa para preencher titulo e contexto.
{
  "source": "aws.cloudwatch",
  "detail-type": "CloudWatch Alarm State Change",
  "resources": ["arn:aws:cloudwatch:us-east-1:111122223333:alarm:ffv-lab-slo-disponibilidade-queima-rapida-confirmada"],
  "detail": {
    "alarmName": "ffv-lab-slo-disponibilidade-queima-rapida-confirmada",
    "state": {
      "value": "ALARM",
      // O motivo cita o alarm_rule inteiro — as DUAS janelas em ALARM, nao uma.
      "reason": "arn:...:burn-5m transitioned to ALARM, arn:...:burn-1h transitioned to ALARM"
    },
    "previousState": { "value": "OK" }
  }
}

# slo.tf — o SLO de disponibilidade, e o orcamento derivado dele

locals {
  # Meta de atingimento: 99,9% das requisicoes bem-sucedidas, medida numa
  # janela de 30 dias. NAO e um valor da documentacao da AWS: e a meta que
  # a Cadencia declara para a API de pedidos, e a que o restante do modulo
  # deriva.
  slo_meta_disponibilidade = 0.999

  # Orcamento de erro: quanto de falha o SLO tolera antes de deixar de
  # cumprir a meta. Com 99,9%, sao 0,1% das requisicoes na janela.
  slo_orcamento_erro = 1 - local.slo_meta_disponibilidade
}

# ── Janela curta: detecta rapido, nao decide sozinha ──────────────────────────
resource "aws_cloudwatch_metric_alarm" "queima_rapida_curta" {
  alarm_name          = "${var.projeto}-slo-disponibilidade-burn-5m"
  alarm_description   = "Burn rate do SLO de disponibilidade, janela de 5 minutos."
  comparison_operator = "GreaterThanOrEqualToThreshold"
  evaluation_periods  = 1
  # 14,4x e o limiar classico da pratica de SRE consolidada pela industria
  # para a janela rapida: neste ritmo o orcamento de 30 dias esgota em ~2h.
  threshold          = 14.4
  treat_missing_data = "notBreaching" # ausencia de trafego nao e falha

  metric_query {
    id          = "erros"
    return_data = false
    metric {
      namespace   = "AWS/ApplicationELB"
      metric_name = "HTTPCode_Target_5XX_Count"
      stat        = "Sum"
      period      = 300
      dimensions = {
        LoadBalancer = aws_lb.principal.arn_suffix
        TargetGroup  = aws_lb_target_group.api.arn_suffix
      }
    }
  }
  metric_query {
    id          = "total"
    return_data = false
    metric {
      namespace   = "AWS/ApplicationELB"
      metric_name = "RequestCount"
      stat        = "Sum"
      period      = 300
      dimensions = {
        LoadBalancer = aws_lb.principal.arn_suffix
        TargetGroup  = aws_lb_target_group.api.arn_suffix
      }
    }
  }
  metric_query {
    id          = "queima"
    return_data = true
    # taxa observada dividida pelo orcamento permitido: quantas vezes mais
    # rapido que o sustentavel o erro esta acontecendo agora.
    expression = "(erros / total * 100) / (${local.slo_orcamento_erro} * 100)"
    label      = "Burn rate — janela de 5 min"
  }
}

# ── Janela longa: confirma que o consumo persiste ─────────────────────────────
resource "aws_cloudwatch_metric_alarm" "queima_rapida_longa" {
  alarm_name          = "${var.projeto}-slo-disponibilidade-burn-1h"
  alarm_description   = "Burn rate do SLO de disponibilidade, janela de 1 hora."
  comparison_operator = "GreaterThanOrEqualToThreshold"
  evaluation_periods  = 1
  threshold           = 14.4 # o MESMO limiar da janela curta — o que muda e a duracao da confirmacao
  treat_missing_data  = "notBreaching"

  metric_query {
    id          = "erros"
    return_data = false
    metric {
      namespace   = "AWS/ApplicationELB"
      metric_name = "HTTPCode_Target_5XX_Count"
      stat        = "Sum"
      period      = 3600
      dimensions = {
        LoadBalancer = aws_lb.principal.arn_suffix
        TargetGroup  = aws_lb_target_group.api.arn_suffix
      }
    }
  }
  metric_query {
    id          = "total"
    return_data = false
    metric {
      namespace   = "AWS/ApplicationELB"
      metric_name = "RequestCount"
      stat        = "Sum"
      period      = 3600
      dimensions = {
        LoadBalancer = aws_lb.principal.arn_suffix
        TargetGroup  = aws_lb_target_group.api.arn_suffix
      }
    }
  }
  metric_query {
    id          = "queima"
    return_data = true
    expression  = "(erros / total * 100) / (${local.slo_orcamento_erro} * 100)"
    label       = "Burn rate — janela de 1 h"
  }
}

# ── O E logico: so acorda alguem quando as duas concordam ─────────────────────
resource "aws_cloudwatch_composite_alarm" "queima_rapida" {
  alarm_name        = "${var.projeto}-slo-disponibilidade-queima-rapida-confirmada"
  alarm_description = "Consumo sustentado do orcamento de erro, confirmado em duas janelas."

  # ALARM() casa pelo NOME do alarme, nao pela ARN. As duas janelas tem de
  # estar em ALARM ao mesmo tempo — e' isso que filtra o pico transiente.
  alarm_rule = "ALARM(\"${aws_cloudwatch_metric_alarm.queima_rapida_curta.alarm_name}\") AND ALARM(\"${aws_cloudwatch_metric_alarm.queima_rapida_longa.alarm_name}\")"

  # Dois destinos, dois papeis: o topico e visibilidade em canal de chat; a
  # ARN do plano de resposta e o que de fato abre o incidente e engaja o
  # plantao. O CloudWatch oferece isto como acao nativa de alarme ("Create
  # incident"), apontando para um plano do Incident Manager.
  alarm_actions = [
    aws_sns_topic.plantao.arn,
    aws_ssmincidents_response_plan.orcamento_de_erro.arn,
  ]
  ok_actions = [aws_sns_topic.plantao.arn]
}

# slo_lenta.tf — a segunda camada: consumo moderado, mas sustentado por horas

# Mesma estrutura do par rapido, com limiar mais baixo e janelas maiores:
# 6x consumido de forma sustentada por 6 horas tambem ameaca o mes, so que
# com menos urgencia — nao precisa acordar ninguem as 3h, mas precisa
# aparecer antes do fim do plantao.
resource "aws_cloudwatch_metric_alarm" "queima_lenta_curta" {
  alarm_name          = "${var.projeto}-slo-disponibilidade-burn-30m"
  comparison_operator = "GreaterThanOrEqualToThreshold"
  evaluation_periods  = 1
  threshold           = 6
  treat_missing_data  = "notBreaching"

  metric_query {
    id = "erros"
    metric {
      namespace = "AWS/ApplicationELB", metric_name = "HTTPCode_Target_5XX_Count"
      stat = "Sum", period = 1800
      dimensions = { LoadBalancer = aws_lb.principal.arn_suffix, TargetGroup = aws_lb_target_group.api.arn_suffix }
    }
    return_data = false
  }
  metric_query {
    id = "total"
    metric {
      namespace = "AWS/ApplicationELB", metric_name = "RequestCount"
      stat = "Sum", period = 1800
      dimensions = { LoadBalancer = aws_lb.principal.arn_suffix, TargetGroup = aws_lb_target_group.api.arn_suffix }
    }
    return_data = false
  }
  metric_query {
    id          = "queima"
    return_data = true
    expression  = "(erros / total * 100) / (${local.slo_orcamento_erro} * 100)"
  }
}

resource "aws_cloudwatch_metric_alarm" "queima_lenta_longa" {
  alarm_name          = "${var.projeto}-slo-disponibilidade-burn-6h"
  comparison_operator = "GreaterThanOrEqualToThreshold"
  evaluation_periods  = 1
  threshold           = 6
  treat_missing_data  = "notBreaching"

  metric_query {
    id = "erros"
    metric {
      namespace = "AWS/ApplicationELB", metric_name = "HTTPCode_Target_5XX_Count"
      stat = "Sum", period = 21600
      dimensions = { LoadBalancer = aws_lb.principal.arn_suffix, TargetGroup = aws_lb_target_group.api.arn_suffix }
    }
    return_data = false
  }
  metric_query {
    id = "total"
    metric {
      namespace = "AWS/ApplicationELB", metric_name = "RequestCount"
      stat = "Sum", period = 21600
      dimensions = { LoadBalancer = aws_lb.principal.arn_suffix, TargetGroup = aws_lb_target_group.api.arn_suffix }
    }
    return_data = false
  }
  metric_query {
    id          = "queima"
    return_data = true
    expression  = "(erros / total * 100) / (${local.slo_orcamento_erro} * 100)"
  }
}

resource "aws_cloudwatch_composite_alarm" "queima_lenta" {
  alarm_name  = "${var.projeto}-slo-disponibilidade-queima-lenta-confirmada"
  alarm_rule  = "ALARM(\"${aws_cloudwatch_metric_alarm.queima_lenta_curta.alarm_name}\") AND ALARM(\"${aws_cloudwatch_metric_alarm.queima_lenta_longa.alarm_name}\")"
  # Mesmo plano — a diferenca de urgencia esta no CONTEUDO do incidente, nao
  # no canal. Quem responde decide o horario de agir a partir do impacto
  # declarado no modelo do plano, nao a partir de qual alarme chamou.
  alarm_actions = [aws_sns_topic.plantao.arn, aws_ssmincidents_response_plan.orcamento_de_erro.arn]
  ok_actions    = [aws_sns_topic.plantao.arn]
}

# incident_manager.tf — o topico, o plano de resposta, e o que fica de fora

resource "aws_sns_topic" "plantao" {
  name = "${var.projeto}-plantao-slo"
}

# Assinatura de e-mail para visibilidade em equipe. NAO e o mecanismo que
# garante resposta — isso e o plano abaixo, com escalonamento. E-mail aqui
# e auditoria, nao dependencia.
resource "aws_sns_topic_subscription" "plantao_email" {
  topic_arn = aws_sns_topic.plantao.arn
  protocol  = "email"
  endpoint  = var.email_visibilidade_equipe
}

# O plano de resposta. Uso apenas os campos confirmados na documentacao no
# momento da escrita: nome, modelo do incidente (titulo e impacto) e a lista
# de contatos engajados. Campos adicionais existem (canal de chat, integracao
# com PagerDuty) — confira o esquema atual do provedor antes de os usar, pois
# nao foram conferidos aqui.
resource "aws_ssmincidents_response_plan" "orcamento_de_erro" {
  name         = "${var.projeto}-orcamento-de-erro"
  display_name = "Orcamento de erro do SLO de disponibilidade consumido rapido demais"

  incident_template {
    title = "Burn rate confirmado em duas janelas — orcamento do mes em risco"
    # Escala de impacto do Incident Manager: confirme o intervalo exato (a
    # documentacao descreve niveis de 1, mais grave, a 5) antes de aplicar em
    # producao. Aqui, 2 = grave o suficiente para acordar plantao, mas nao a
    # interrupcao total do servico.
    impact = 2
  }

  # O contato de plantao E o rodizio de escalonamento sao provisionados uma
  # vez pelo time de plataforma (aws_ssmcontacts_contact, aws_ssmcontacts_plan
  # e aws_ssmcontacts_rotation) e reaproveitados por varios planos de
  # resposta — nao recriados por laboratorio. Este modulo referencia a ARN
  # de um contato ja existente, deliberadamente fora do escopo aqui: a
  # rotacao de plantao e um recurso organizacional, nao deste servico.
  engagements = [var.contato_plantao_arn]
}

# O que os 40 alarmes tecnicos deixam de ter: uma acao que notifica gente.
# Continuam existindo (o Terraform que os criou nao muda), so perdem
# alarm_actions apontando para SNS de plantao. Ilustrativo — o recurso real
# de cada um ja existe desde antes deste laboratorio.
resource "aws_cloudwatch_metric_alarm" "exemplo_alarme_tecnico_rebaixado" {
  alarm_name          = "${var.projeto}-ecs-cpu-alta"
  comparison_operator = "GreaterThanThreshold"
  evaluation_periods  = 3
  metric_name         = "CPUUtilization"
  namespace           = "AWS/ECS"
  period              = 300
  statistic           = "Average"
  threshold           = 80
  dimensions = {
    ClusterName = aws_ecs_cluster.principal.name
    ServiceName = aws_ecs_service.api.name
  }
  # Sem alarm_actions: o estado continua calculado e visivel no painel de
  # diagnostico (dashboard), mas nao publica em lugar nenhum que acorde gente.
  alarm_actions = []
}

// Program.cs (trecho) — o sintoma sai do codigo, o calculo fica no CloudWatch

var builder = WebApplication.CreateBuilder(args);

// Reaproveita o OTel do L51: aqui so acrescentamos os CONTADORES que
// alimentam o terceiro SLO (fim a fim, correlacionado por trace). O calculo
// de burn rate NAO mora aqui — mora inteiramente em metric math no
// CloudWatch. A aplicacao so precisa emitir o sintoma com precisao.
var meter = new Meter("Cadencia.Pedidos", "1.0.0");
var pedidosTotal = meter.CreateCounter<long>(
    "pedidos_total", description: "Requisicoes ao endpoint de pedidos, por resultado");

builder.Services.AddOpenTelemetry()
    .WithMetrics(m => m
        .AddMeter("Cadencia.Pedidos")
        // O exportador OTLP do L51 ja aponta para o coletor ADOT; o proprio
        // coletor, configurado com o exportador awsemf, converte a metrica
        // OTel num Formato de Metrica Embutida e a publica como metrica
        // customizada no CloudWatch — sem SDK da AWS na aplicacao.
        .AddOtlpExporter());

var app = builder.Build();

app.MapGet("/api/pedidos/{id:guid}", async (Guid id, AppDb db) =>
{
    // O rotulo "resultado" e o que faz esta metrica virar SLI: separa
    // sucesso de erro por rota, na mesma cardinalidade que o painel de
    // trace do L51 ja usa — sem inventar um vocabulario novo de metrica.
    try
    {
        var pedido = await db.Pedidos.FindAsync(id);
        pedidosTotal.Add(1, new("rota", "pedidos/id"), new("resultado", pedido is null ? "nao_encontrado" : "sucesso"));
        return pedido is { } p ? Results.Ok(p) : Results.NotFound();
    }
    catch (Exception)
    {
        pedidosTotal.Add(1, new("rota", "pedidos/id"), new("resultado", "erro"));
        throw; // o middleware de erro do ASP.NET Core continua tratando a resposta
    }
});

app.Run();

#!/usr/bin/env bash
# provas.sh — cinco medicoes; a de numero 3 e a que mais gente pula
set -euo pipefail
PROJETO="${PROJETO:?defina PROJETO}"

# ── Prova 1: carga sintetica de erro sustentado forca o alarme composto ──────
# Gera 5xx real por 70 minutos (mais que a janela longa de 1h) numa rota de
# teste. Espera-se ALARM no composto entre o minuto 60 e 65.
./gerar_erro_sintetico.sh --duracao-min 70 --taxa-erro 0.05 &
sleep 3900
aws cloudwatch describe-alarms --alarm-names "${PROJETO}-slo-disponibilidade-queima-rapida-confirmada" \
  --query "MetricAlarms[0].StateValue" --output text
# Esperado: ALARM. Se ainda INSUFFICIENT_DATA ou OK, confira se as duas
# janelas (curta e longa) realmente estao em ALARM cada uma.

# ── Prova 2: pico isolado de 1 minuto NAO dispara o composto ─────────────────
./gerar_erro_sintetico.sh --duracao-min 1 --taxa-erro 0.20
sleep 360
aws cloudwatch describe-alarms --alarm-names "${PROJETO}-slo-disponibilidade-burn-5m" \
  --query "MetricAlarms[0].StateValue" --output text   # pode entrar em ALARM
aws cloudwatch describe-alarms --alarm-names "${PROJETO}-slo-disponibilidade-queima-rapida-confirmada" \
  --query "MetricAlarms[0].StateValue" --output text   # tem de continuar OK
# Se o COMPOSTO entrou em ALARM aqui, o alarm_rule esta com OR em vez de AND.

# ── Prova 3: os 40 alarmes tecnicos nao tem acao que notifica gente ──────────
# Nenhum alarme cujo nome NAO comece pelo prefixo do SLO pode ter o topico
# de plantao em AlarmActions. Esta prova falhando e o defeito mais caro do
# laboratorio inteiro: alarme tecnico continuando a acordar gente.
aws cloudwatch describe-alarms --alarm-name-prefix "${PROJETO}-" \
  --query "MetricAlarms[?!contains(AlarmName, 'slo-disponibilidade')].{nome:AlarmName,acoes:AlarmActions}" \
  --output table
# Esperado: nenhuma linha com a ARN do topico de plantao em "acoes".

# ── Prova 4: o incidente realmente abriu, e o contato foi engajado ───────────
aws ssm-incidents list-incident-records \
  --query "incidentRecordSummaries[0].{status:status,inicio:impact,titulo:title}" --output table
aws ssm-contacts list-engagements \
  --query "engagements[0].{contato:contactArn,confirmado:*}" --output table
# Esperado: registro de incidente com o titulo do plano, e um engagement
# associado ao contato de plantao — nao so o alarme em ALARM.

# ── Prova 5: burn rate volta a cair depois que o erro sintetico para ─────────
sleep 900
aws cloudwatch get-metric-data --start-time "$(date -u -v-15M +%FT%TZ)" --end-time "$(date -u +%FT%TZ)" \
  --metric-data-queries '[{"Id":"queima","Expression":"(erros/total*100)/(0.1)","ReturnData":true},
    {"Id":"erros","MetricStat":{"Metric":{"Namespace":"AWS/ApplicationELB","MetricName":"HTTPCode_Target_5XX_Count"},"Period":300,"Stat":"Sum"}},
    {"Id":"total","MetricStat":{"Metric":{"Namespace":"AWS/ApplicationELB","MetricName":"RequestCount"},"Period":300,"Stat":"Sum"}}]' \
  --query "MetricDataResults[0].Values[:3]"
# Esperado: os ultimos valores abaixo de 1 — a prova de que a mitigacao
# funcionou nao e "o alarme mudou de estado", e o numero caindo.

# 1. Derrube o que o Terraform administra.
terraform destroy -auto-approve

# 2. ASSINATURA SNS PENDENTE: se ninguem confirmou o e-mail de visibilidade, a
#    assinatura fica "pendente" indefinidamente — nao cobra, mas polui a lista.
aws sns list-subscriptions-by-topic --topic-arn "$(terraform output -raw topico_plantao_arn)" \
  2>/dev/null || true

# 3. REGISTROS DE INCIDENTE: o Incident Manager mantem historico dos incidentes
#    abertos pelos testes deste laboratorio. O destroy do plano de resposta NAO
#    apaga o historico — e nao deveria: e o registro de auditoria de quem foi
#    chamado e quando.
aws ssm-incidents list-incident-records --query "incidentRecordSummaries[].arn" --output table

# 4. ENGAJAMENTOS DE TESTE: os engagements gerados pelas provas ficam no historico
#    do contato de plantao, mesmo depois de o plano de resposta ser destruido.
aws ssm-contacts list-engagements --query "engagements[].engagementArn" --output table

# 5. ALARMES TECNICOS ORIGINAIS: nao pertencem a este laboratorio — vieram de
#    antes. O destroy deste modulo nao deve apagar os 40; confirme que o estado
#    do Terraform aqui NAO importou esses recursos por engano.
aws cloudwatch describe-alarms --alarm-name-prefix "${PROJETO}-" \
  --query "length(MetricAlarms)" --output text

# 6. Prova final: nada com o prefixo do SLO continua ligado a acao de notificacao.
aws cloudwatch describe-alarms --alarm-name-prefix "${PROJETO}-slo-" \
  --query "MetricAlarms[].AlarmActions" --output table