Lab 51 — Os três pilares no .NET com OpenTelemetry

# Rode ANTES de instrumentar nada. O numero daqui e a linha de base.

# Gere uma cobranca conhecida e anote o horario exato.
curl -s -X POST "https://.../api/faturas/8f3a..." | jq .

# Tente achar, no CloudWatch Logs, no console do X-Ray e no grafico de
# metrica customizada, os TRES registros da MESMA requisicao — usando so
# o horario. Cronometre.
# Na Faturamento: entre 20 e 40 minutos, e sem garantia — o resultado e uma
# CRENCA de que os tres registros achados sao da mesma requisicao, nao uma prova.

// Forma SIMPLIFICADA do que o coletor recebe via OTLP — não é o wire format
// exato (que é Protobuf binário), é a estrutura conceitual que o SDK preenche
// UMA vez e anexa aos três sinais. É o que a seção anterior chama de "mesmo
// Resource": nenhum dos três teve de declarar service.name por conta própria.

{
  "resource": {
    "attributes": {
      "service.name": "faturamento",
      "service.version": "a1b2c3d",              // SHA da imagem — o mesmo padrao do L03
      "deployment.environment": "producao",
      "cloud.platform": "aws_ecs_fargate",
      "cloud.region": "us-east-1"
    }
  },
  "trace_id": "5f2c9a1e4b3d8f7601a2c3d4e5f60718",
  "log_record": {
    "severity_text": "INFORMATION",
    "body": "Fatura calculada para {PedidoId}",
    "attributes": { "pedido.id": "8f3a...", "fatura.valor_centavos": 148900 },
    "span_id": "3c7e9b0a1d2f4e56"                 // o mesmo span do cálculo, abaixo
  },
  "span": {
    "name": "calcular-fatura",                    // o span MANUAL da seção "Construir"
    "span_id": "3c7e9b0a1d2f4e56",
    "parent_span_id": "1a2b3c4d5e6f7081",
    "attributes": { "fatura.desconto_aplicado": true }
  },
  "metric_data_point": {
    "name": "http.server.request.duration",
    "attributes": { "http.route": "/api/faturas/{id}", "http.status_code": 200 }
    // repare no que NAO esta aqui: nenhum trace_id no ponto de metrica. Metrica
    // agregada nao carrega identidade de requisicao — e por isso ela e barata
    // em volume e nao serve para achar UMA cobranca especifica.
  }
}

// ObservabilidadeCadencia/Extensoes.cs — o pacote interno que resolve o requisito
// organizacional. Uma equipe nova chama UM metodo; nao decide biblioteca nenhuma.

using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

namespace Cadencia.Observabilidade;

public static class Extensoes
{
    // O ActivitySource compartilhado para spans MANUAIS de logica de negocio.
    // Fica aqui, no pacote interno, para toda equipe registrar o MESMO nome —
    // um ActivitySource com nome diferente do registrado no builder produz span
    // que o SDK descarta silenciosamente, e essa e a causa da Falha 2 adiante.
    public static readonly System.Diagnostics.ActivitySource FonteDeSpansDeNegocio =
        new("Cadencia.Negocio");

    public static IServiceCollection AddObservabilidadeCadencia(
        this IServiceCollection services, IConfiguration config, string nomeServico)
    {
        var recurso = ResourceBuilder.CreateDefault().AddService(
            serviceName: nomeServico,
            serviceVersion: config["SHA_DA_IMAGEM"] ?? "dev");

        services.AddOpenTelemetry()
            .ConfigureResource(r => r.AddAttributes(new Dictionary<string, object>
            {
                ["deployment.environment"] = config["ASPNETCORE_ENVIRONMENT"] ?? "producao",
            }).AddService(nomeServico, serviceVersion: config["SHA_DA_IMAGEM"] ?? "dev"))
            // ── Os TRES sinais saem do MESMO builder — e e essa estrutura, nao
            // convencao entre desenvolvedores, que garante a correlacao. ──────────
            .WithTracing(t => t
                .AddSource(FonteDeSpansDeNegocio.Name)   // registra o span MANUAL
                .AddAspNetCoreInstrumentation(o =>
                    o.Filter = ctx => !ctx.Request.Path.StartsWithSegments("/health"))
                .AddHttpClientInstrumentation()
                .AddNpgsql()
                .AddOtlpExporter())
            .WithMetrics(m => m
                .AddAspNetCoreInstrumentation()
                .AddRuntimeInstrumentation()
                .AddOtlpExporter())
            // ── A peca que o L08 nao tinha: o log nasce do MESMO LoggerProvider,
            // nao de um ILogger nativo costurado por fora com ActivityTrackingOptions.
            .WithLogging(l => l.AddOtlpExporter());

        return services;
    }
}

// Program.cs — Faturamento, depois da migracao. Uma chamada ao pacote interno
// substitui as tres bibliotecas concorrentes da arquitetura minima.

using Cadencia.Observabilidade;
using System.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContextPool<AppDb>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("Padrao")));

// Uma linha. Nao ha Serilog, nao ha AWSXRayRecorder, nao ha MetricsPublisher
// caseiro — os tres foram removidos do .csproj. E o requisito organizacional
// da tabela anterior, em codigo: nenhuma equipe decide sozinha como instrumentar.
builder.Services.AddObservabilidadeCadencia(builder.Configuration, nomeServico: "faturamento");

// Devolve o identificador ao cliente — a mesma pratica do L08. Sem isto, o
// ticket volta a chegar so com um horario aproximado.
var app0 = builder.Build();
app0.Use(async (ctx, next) =>
{
    var trace = Activity.Current?.TraceId.ToString();
    if (trace is not null) ctx.Response.Headers["X-Correlation-Id"] = trace;
    await next();
});
var app = app0;

app.MapPost("/api/faturas/{pedidoId:guid}", async (
    Guid pedidoId, AppDb db, ILogger<Program> log) =>
{
    // Sem TraceId passado a mao: o escopo ambiental do Activity ja garante que
    // este evento sai carregando o contexto corrente — herdado do WithLogging.
    log.LogInformation("Calculando fatura para {PedidoId}", pedidoId);

    var pedido = await db.Pedidos.FindAsync(pedidoId);
    if (pedido is null) return Results.NotFound();

    // ── O SPAN MANUAL: nenhuma instrumentacao automatica cobre "calcular valor
    // com desconto e imposto", porque nao e uma chamada de rede nem de banco —
    // e logica de negocio pura. StartActivity herda o Activity.Current como pai
    // por padrao: o span aparece na MESMA arvore, com o MESMO trace id.
    using var span = Extensoes.FonteDeSpansDeNegocio.StartActivity("calcular-fatura");
    var valor = CalcularValorComDescontoEImposto(pedido);
    span?.SetTag("fatura.valor_centavos", valor);
    span?.SetTag("fatura.desconto_aplicado", pedido.TemDesconto);

    var fatura = new Fatura { PedidoId = pedidoId, ValorCentavos = valor };
    db.Faturas.Add(fatura);
    await db.SaveChangesAsync();

    log.LogInformation("Fatura {FaturaId} criada para {PedidoId}: {ValorCentavos}",
        fatura.Id, pedidoId, valor);

    return Results.Created($"/api/faturas/{fatura.Id}", fatura);
});

app.MapHealthChecks("/health/ready");
app.Run();

static long CalcularValorComDescontoEImposto(Pedido pedido) =>
    (long)(pedido.SubtotalCentavos * (pedido.TemDesconto ? 0.9m : 1m) * 1.08m);

# coletor.yaml — Faturamento. Mesma base do L08, com o exportador de log que
# fecha a lacuna: la, log saia pelo driver awslogs do conteiner, fora do OTLP.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317   # so a propria task alcanca; awsvpc compartilha rede
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch/traces:
    timeout: 5s
    send_batch_size: 128

  # Amostragem por cauda, herdada do L08: decide DEPOIS de o trace terminar.
  # Aqui pesa mais ainda — Faturamento mexe com dinheiro, e "erro raro que a
  # amostra de cabeca perderia" e exatamente o tipo de evento que a auditoria
  # de uma cobranca precisa conseguir encontrar.
  tailsampling:
    decision_wait: 10s
    policies:
      - name: erros-sempre
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: lentas-sempre
        type: latency
        latency: { threshold_ms: 2000 }
      - name: resto-amostrado
        type: probabilistic
        probabilistic: { sampling_percentage: 5 }

  resourcedetection:
    detectors: [env, ecs]

exporters:
  awsxray:
    indexed_annotations: [fatura.desconto_aplicado, deployment.environment]

  awsemf:
    namespace: Faturamento
    log_group_name: /ecs/faturamento/emf
    dimension_rollup_option: NoDimensionRollup
    metric_declarations:
      # Mesma decisao de custo do L08: rota x status, nunca id de cliente ou de
      # requisicao — cada combinacao distinta e uma serie nova.
      - dimensions: [[http.route, http.status_code]]
        metric_name_selectors: ['http.server.request.duration']

  # NOVO em relacao ao L08: log tambem sai pelo coletor, nao pelo driver do
  # conteiner. INCERTEZA DECLARADA: o projeto rotula este exportador como
  # experimental e sujeito a mudanca de campo — confira o README do
  # `awscloudwatchlogsexporter` na versao do ADOT Collector que voce fixar
  # antes de depender dele para auditoria. E por isso que a secao de
  # Seguranca trata perda silenciosa deste exportador como risco nomeado, e
  # a Falha 3 provoca exatamente esse cenario.
  awscloudwatchlogs:
    log_group_name: /otel/faturamento/app
    log_stream_name: faturamento-app

  # Exportador ILUSTRATIVO do diagrama de producao — NAO ativo no pipeline
  # abaixo. Mostra o tamanho real de "trocar de fornecedor": esta secao, e
  # nenhuma linha em Program.cs.
  # otlphttp/terceiro:
  #   endpoint: https://otel.exemplo-de-terceiro.com:4318

service:
  # Telemetria do PROPRIO coletor — e o que a Prova 5 e a Falha 3 consultam
  # para saber se o exportador experimental esta de fato entregando.
  telemetry:
    metrics:
      level: detailed

  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, tailsampling, batch/traces]
      exporters: [awsxray]
    metrics:
      receivers: [otlp]
      processors: [resourcedetection]
      exporters: [awsemf]
    logs:
      receivers: [otlp]
      processors: [resourcedetection]
      exporters: [awscloudwatchlogs]

# observabilidade-faturamento.tf — o DELTA sobre o L08: dois grupos de log
# novos e o IAM que falta para o coletor escrever log via OTLP, nao so metrica
# e trace. O servico ECS, o ALB e o RDS de Faturamento seguem o mesmo padrao
# do L01/L03 e nao sao repetidos aqui.

resource "aws_cloudwatch_log_group" "faturamento_app" {
  name              = "/otel/faturamento/app"
  retention_in_days = 14
  kms_key_id        = aws_kms_key.app.arn
}

resource "aws_cloudwatch_log_group" "faturamento_emf" {
  # Grupo SEPARADO do de log de aplicacao, com retencao mais curta: e metrica
  # derivada, nao evidencia de auditoria — a mesma distincao de dois grupos do L08.
  name              = "/ecs/faturamento/emf"
  retention_in_days = 3
}

data "aws_iam_policy_document" "coletor_faturamento" {
  statement {
    sid     = "Tracos"
    effect  = "Allow"
    actions = ["xray:PutTraceSegments", "xray:PutTelemetryRecords"]
    # X-Ray nao aceita Resource especifico nestas duas acoes — sao de conta,
    # nao de recurso. E o mesmo padrao de justificativa do ecr:GetAuthorizationToken no L03.
    resources = ["*"]
  }

  statement {
    sid    = "MetricaEmbutidaELogEstruturado"
    effect = "Allow"
    actions = [
      "logs:CreateLogStream",
      "logs:PutLogEvents",
      "logs:DescribeLogStreams",
    ]
    # Ao contrario do X-Ray, PutLogEvents ACEITA arn de recurso — entao aqui o
    # "*" nao se justifica. Escopar aos dois grupos e o que impede o coletor de
    # escrever em QUALQUER log group da conta.
    resources = [
      aws_cloudwatch_log_group.faturamento_app.arn,
      "${aws_cloudwatch_log_group.faturamento_app.arn}:*",
      aws_cloudwatch_log_group.faturamento_emf.arn,
      "${aws_cloudwatch_log_group.faturamento_emf.arn}:*",
    ]
  }
}

resource "aws_iam_role_policy" "coletor_faturamento" {
  name   = "coletor-otel-faturamento"
  role   = aws_iam_role.task_faturamento.id  # task role, NAO execution role — quem fala com X-Ray/Logs e a APLICACAO/coletor
  policy = data.aws_iam_policy_document.coletor_faturamento.json
}

# Delta na definicao de task: segundo conteiner nao-essencial, e as variaveis
# que apontam a aplicacao para o coletor local em vez de para um SDK proprietario.
resource "aws_ecs_task_definition" "faturamento" {
  family                   = "faturamento"
  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = 512
  memory                   = 1024
  execution_role_arn       = aws_iam_role.execucao_faturamento.arn
  task_role_arn            = aws_iam_role.task_faturamento.arn

  container_definitions = jsonencode([
    {
      name      = "api"
      image     = "${aws_ecr_repository.faturamento.repository_url}:${var.sha_da_imagem}"
      essential = true
      portMappings = [{ containerPort = 8080, protocol = "tcp" }]
      environment = [
        { name = "OTEL_EXPORTER_OTLP_ENDPOINT", value = "http://localhost:4317" },
        { name = "OTEL_SERVICE_NAME", value = "faturamento" },
        { name = "SHA_DA_IMAGEM", value = var.sha_da_imagem },
      ]
      secrets = [{
        name      = "ConnectionStrings__Padrao"
        valueFrom = aws_secretsmanager_secret.banco.arn
      }]
      # SEM logConfiguration apontando para o driver awslogs: o log sai pelo
      # coletor agora. Repare no que isso significa — se o coletor cair, o log
      # da aplicacao para de sair tambem, e e por isso que o proximo bloco
      # marca o coletor como nao-essencial em vez de deixar o log em silencio.
      dependsOn = [{ containerName = "coletor", condition = "START" }]
    },
    {
      name      = "coletor"
      image     = "public.ecr.aws/aws-observability/aws-otel-collector:latest"
      essential = false  # falha do coletor NAO derruba a API que processa cobranca
      command   = ["--config=/etc/coletor.yaml"]
      logConfiguration = {
        logDriver = "awslogs"
        options = {
          "awslogs-group"         = aws_cloudwatch_log_group.faturamento_emf.name
          "awslogs-region"        = var.regiao
          "awslogs-stream-prefix" = "coletor"
        }
      }
    },
  ])
}

# provas.sh — cinco medicoes; nenhuma conclusao vem de "os tres pilares existem"

PROJETO=faturamento; REGIAO=us-east-1

# ── Prova 1: UM trace id aparece no log, no span e no atributo de negocio ────
TID=$(curl -s -o /dev/null -D - -X POST "https://$(terraform output -raw dominio)/api/faturas/8f3a..." \
  | grep -i x-correlation-id | tr -d '\r' | cut -d' ' -f2)
echo "trace id devolvido ao cliente: $TID"

aws logs start-query --log-group-name /otel/faturamento/app \
  --start-time $(($(date +%s)-120)) --end-time $(date +%s) \
  --query-string "fields @message | filter TraceId = \"$TID\" | stats count() as achados" \
  --query queryId --output text
# Esperado: achados >= 1. Zero significa que WithLogging nao esta ligado ao
# mesmo Resource — e a Falha 1 desta secao.

aws xray get-trace-summaries --time-range-type TraceId --trace-ids "$TID" \
  --query 'TraceSummaries[0].Id' --output text
# Esperado: o MESMO id do log. IDs diferentes e a Falha 2: uma segunda
# biblioteca abriu segmento proprio.

# ── Prova 2: o span manual esta na arvore, nao e um trace a parte ───────────
aws xray batch-get-traces --trace-ids "$TID" \
  --query 'Traces[0].Segments[].Document' --output text | grep -c "calcular-fatura"
# Esperado: 1. Zero significa ActivitySource nao registrado no AddSource() do
# builder — o span existe no processo e o SDK descarta antes de exportar.

# ── Prova 3: falha do coletor nao derruba a API que processa cobranca ───────
aws ecs stop-task --cluster $PROJETO \
  --task "$(aws ecs list-tasks --cluster $PROJETO --service-name $PROJETO \
             --query 'taskArns[0]' --output text)" --reason "prova de essential=false"
sleep 5
for i in 1 2 3 4 5; do
  curl -s -o /dev/null -w '%{http_code} ' "https://$(terraform output -raw dominio)/health/ready"
done
echo
# Esperado: cinco 200. Qualquer coisa diferente de 200 significa que o
# coletor foi marcado essential=true por engano.

# ── Prova 4: a cardinalidade da metrica continua baixa em 40 mil req/dia ────
aws cloudwatch list-metrics --namespace Faturamento \
  --query 'length(Metrics)' --output text
# Esperado: dezenas, nao milhares. Se subir na casa de milhares, alguma
# dimensao de alta cardinalidade entrou no metric_declarations — e o
# Anti-padrao 5 desta secao.

# ── Prova 5: o exportador de log esta de fato entregando (self-telemetry) ───
aws logs filter-log-events --log-group-name /ecs/faturamento/emf \
  --filter-pattern '"otelcol_exporter_send_failed_log_records"' \
  --start-time $(( ($(date +%s) - 300) * 1000 )) \
  --query 'events[].message' --output text
# Esperado: vazio. Qualquer linha aqui significa que o exportador
# experimental esta descartando log silenciosamente — e a Falha 3.

#!/usr/bin/env bash
# limpar.sh — o delta deste laboratorio sobre o que o L08 ja limpava.
set -euo pipefail

# 1. Derrube o que o Terraform administra (task definition, IAM, os dois grupos novos).
terraform destroy -auto-approve

# 2. GRUPOS DE LOG NOVOS: se `skip_destroy` estiver ligado em algum deles —
#    pratica comum para nao perder log de incidente por engano — o destroy
#    NAO os remove. Confira os dois.
aws logs describe-log-groups --log-group-name-prefix /otel/faturamento \
  --query "logGroups[].{grupo:logGroupName,bytes:storedBytes}" --output table
aws logs describe-log-groups --log-group-name-prefix /ecs/faturamento/emf \
  --query "logGroups[].{grupo:logGroupName,bytes:storedBytes}" --output table
aws logs delete-log-group --log-group-name /otel/faturamento/app 2>/dev/null || true
aws logs delete-log-group --log-group-name /ecs/faturamento/emf 2>/dev/null || true

# 3. Repositorio ECR de Faturamento, se este laboratorio foi seu primeiro
#    contato com o servico (nao vinha do L08).
aws ecr describe-repositories --repository-names faturamento \
  --query "repositories[0].repositoryName" --output text 2>/dev/null && \
  aws ecr delete-repository --repository-name faturamento --force

# 4. O que o L01/L03 ja cobravam por hora continua cobrando: ALB, RDS, NAT
#    Gateway. Se voce nao segue para o L52, rode a limpeza deles tambem.

# 5. Prova final: nada com o nome do servico de pe.
aws resourcegroupstaggingapi get-resources \
  --tag-filters Key=Servico,Values=faturamento \
  --query "ResourceTagMappingList[].ResourceARN" --output table