DEV Community: Diego Broetto

Event-driven com EventBridge + SQS: quando cada um entra e como evitar os erros mais comuns

Diego Broetto — Tue, 13 Oct 2026 23:06:03 +0000

Ouço muito a pergunta "EventBridge ou SQS?". Quase sempre ela está mal formulada.

Na maioria dos fluxos com mais de um consumidor, os dois trabalham juntos: o EventBridge decide para onde o evento vai, e o SQS segura esse evento até alguém poder processar. Roteamento e durabilidade são problemas diferentes, então um não substitui o outro.

Este artigo mostra onde cada peça entra, o que cada uma resolve sozinha e quais erros aparecem quando alguém usa as duas sem saber por quê.

1.0 O que cada serviço realmente resolve

Os dois aparecem juntos em quase toda discussão porque ambos recebem mensagens. Mas o trabalho de cada um é diferente: o EventBridge decide para onde a informação vai, e o SQS guarda a informação até alguém processá-la.

1.1 EventBridge

O EventBridge é um barramento de eventos. Você publica um evento uma vez, e ele avalia as regras contra o conteúdo desse evento para decidir quais alvos recebem. O produtor não sabe quantos consumidores existem nem quem são. Para incluir um consumidor novo, basta criar uma regra. O código de quem publica não muda.

O que ele faz bem:

Entregar o mesmo evento a vários alvos
Filtrar por conteúdo com event patterns, usando campos como source, detail-type ou valores dentro de detail
Receber eventos de serviços AWS e de parceiros SaaS sem código de integração
Arquivar eventos e reenviá-los depois (archive e replay)

O que ele não faz:

Garantir ordem entre eventos
Segurar um evento por tempo indeterminado. Por padrão, ele tenta entregar ao alvo por até 24 horas e até 185 vezes. Esgotadas as tentativas, se o alvo não tem DLQ, o evento é descartado.
Controlar o ritmo do consumidor. Ele empurra o evento para o alvo, então quem precisa aguentar o volume é o alvo.

1.2 SQS

O SQS é uma fila. A mensagem fica guardada até um consumidor processá-la e apagá-la de forma explícita. Se o consumidor cair no meio do processamento, a mensagem volta a ficar visível depois do visibility timeout, e outro consumidor pode pegá-la.

O que ele faz bem:

Absorver picos. A fila cresce durante o pico, e o consumidor processa no ritmo que aguenta.
Limitar a concorrência do consumidor (no Lambda, com MaximumConcurrency)
Reter mensagens por até 14 dias (o padrão é 4)
Mover para uma DLQ as mensagens que falham de forma persistente, depois de maxReceiveCount tentativas
Manter a ordem das mensagens, quando você usa FIFO

O que ele não faz:

Rotear. Quem publica escolhe a fila de destino.
Entregar a mesma mensagem a vários consumidores. Consumidores na mesma fila competem pelas mensagens. Para broadcast, o caminho é uma fila por assinante, com SNS ou EventBridge na frente.
Garantir entrega única na fila padrão. Ela é at-least-once, então o consumidor precisa ser idempotente. A FIFO tem deduplicação, mas só dentro de uma janela de tempo.

Falando em FIFO, estou pensando em fazer uma série de artigos voltados a fundamentos da computação, coisas como Filas, Pilhas, Listas, Programação Orientada a Objetos, entre outros... O que vocês acham?

1.3 Quando usar cada um

Vale reparar nos sentidos do fluxo: a regra do EventBridge empurra o evento para a fila, mas quem lê a fila é o Lambda, que faz polling pelo event source mapping.

Para decidir, pergunte duas coisas: quem precisa receber esse evento? E quem precisa segurá-lo até estar pronto para processar?

Necessidade	Use	Por quê
Um evento para vários consumidores que não se conhecem	EventBridge	O produtor só publica. Cada consumidor cria a própria regra.
Absorver picos antes do processamento	SQS	A fila segura o excesso, e o consumidor anda no próprio ritmo.
Processar em ordem estrita	SQS FIFO	Só a FIFO garante ordem dentro de um grupo de mensagens.
Rotear pelo conteúdo do evento	EventBridge	Event patterns decidem o alvo sem código.
Reprocessar se o consumidor cair no meio	SQS	A mensagem permanece na fila até ser apagada.
Consumidor rápido, de baixo volume, sem necessidade de controlar o ritmo	EventBridge direto para a Lambda	O Lambda já guarda o evento numa fila interna e tenta de novo. Uma fila SQS na frente seria mais uma peça sem ganho.
Um único consumidor, sem roteamento	SQS	O EventBridge seria mais uma peça para manter, sem trazer ganho.

A maioria dos fluxos que precisam de mais de um consumidor acaba usando as duas peças: o EventBridge decide quem recebe, e o SQS segura o evento até o consumidor estar pronto. É o padrão da seção 2.0.

2.0 O padrão mais comum: EventBridge → SQS → Lambda

Por que não colocar a Lambda como alvo direto da regra do EventBridge? Funciona, e é mais protegido do que parece. O EventBridge invoca o Lambda de forma assíncrona: o evento entra numa fila interna do Lambda, que continua tentando por até 6 horas quando a função sofre throttling. Se a função der erro, são mais duas tentativas.

O que essa fila interna não oferece é controle. Você não enxerga quantos eventos estão esperando, não escolhe quantos são processados ao mesmo tempo (a não ser reservando concorrência para a função inteira) e não processa em lote. Com o SQS no meio, o backlog vira métrica (ApproximateNumberOfMessagesVisible e ApproximateAgeOfOldestMessage), a concorrência do consumidor fica no MaximumConcurrency do event source mapping, e a mensagem pode esperar até 14 dias.

O desenho é simples. O que costuma dar errado é a configuração de cada peça: visibility timeout, permissões entre EventBridge e SQS, comportamento de lote na Lambda. O resto do artigo cobre isso com um projeto que reproduz cada erro de propósito.

3.0 O cenário: um evento, quatro destinos

O PedidoCriado do projeto de pedidos agora é roteado (fan-out) para três filas, uma por domínio, e direto para a Lambda que classifica o pedido, sem fila no meio:

                     ┌─→ SQS Estoque     → Lambda (baixa)
PedidoCriado         ├─→ SQS Notificação → Lambda (e-mail)
  → EventBridge ─────┼─→ SQS Financeiro  → Lambda (cobrança)
                     └─→ Lambda processar_pedido (sem fila)

Um fluxo linear, com uma fila e um consumidor, prova pouco. Dá para fazer isso só com SQS e ninguém notaria a diferença. O fan-out é o argumento a favor do EventBridge: o mesmo evento alimenta estoque, notificação e faturamento, e nenhum desses consumidores sabe que os outros existem. Se amanhã surgir um quinto consumidor, como um serviço de detecção de fraude, ele assina o evento e pronto. O código que cria o pedido não muda uma linha.

Cada fila do projeto reproduz de propósito um erro comum.

4.0 Visibility timeout: a fila reentregando antes da hora

A fila de Estoque simula uma chamada a um sistema legado, com latência entre 3 e 15 segundos por mensagem.

# Simula latência de um sistema de estoque legado
latencia = random.uniform(LATENCIA_MIN_SEGUNDOS, LATENCIA_MAX_SEGUNDOS)
time.sleep(latencia)

O visibility timeout da fila é de 180 segundos, para uma função com timeout de 30. São as 6x que a documentação do Lambda recomenda para filas que alimentam uma função.

EstoqueQueue:
  Type: AWS::SQS::Queue
  Properties:
    VisibilityTimeout: 180

Validando o projeto, apareceu um detalhe que eu não tinha previsto. A primeira versão lia lotes de 5 mensagens. Com cada baixa levando até 15 segundos, o pior caso de um lote chegava a 75 segundos, bem acima do timeout de 30 da função. Troquei para BatchSize: 1. Quando cada mensagem é lenta, o tamanho do lote também entra na conta do timeout.

O que acontece se você reduzir o visibility timeout para 10 segundos? O SQS entrega a mensagem ao consumidor e começa a contar. Se a mensagem não for apagada dentro desses 10 segundos, ela volta a ficar visível e pode ser entregue de novo, possivelmente enquanto o primeiro consumidor ainda está no meio do time.sleep(). Com isso, dois consumidores processam o mesmo pedido e o estoque é debitado duas vezes.

No projeto dá para reproduzir: troque o VisibilityTimeout de 180 para 10 no template, faça o deploy e compare a métrica EstoqueBaixado com o número de pedidos criados.

5.0 Lote com falhas: o que volta para a fila e o que some

A fila de Notificação processa lotes de até 10 mensagens por invocação. O problema aparece quando uma mensagem do lote falha.

Sem tratamento especial, o comportamento é tudo ou nada. Se uma exceção sobe do handler, o lote inteiro é considerado falho e as 10 mensagens voltam a ficar visíveis, inclusive as 9 que já tinham mandado o e-mail de confirmação ao cliente.

# Versão ingênua, evite
def lambda_handler(event, context):
    for record in event["Records"]:
        enviar_notificacao(record)  # se UMA lançar exceção, TODAS voltam

A correção é a resposta parcial de lote, com o utilitário de batch do Powertools:

from aws_lambda_powertools.utilities.batch import (
    BatchProcessor, EventType, process_partial_response,
)

processor = BatchProcessor(event_type=EventType.SQS)

def lambda_handler(event, context):
    return process_partial_response(
        event=event,
        record_handler=processar_registro,
        processor=processor,
        context=context,
    )

O BatchProcessor processa cada mensagem isoladamente, captura as falhas por item e devolve a lista batchItemFailures com os IDs que falharam. Só essas voltam para a fila. Se todas as mensagens do lote falharem, ele lança BatchProcessingError, e aí o lote inteiro volta.

Além do código, o event source mapping precisa da flag:

Events:
  SQSEvent:
    Type: SQS
    Properties:
      Queue: !GetAtt NotificacaoQueue.Arn
      BatchSize: 10
      FunctionResponseTypes: [ReportBatchItemFailures]

Sem a flag, o cenário é pior que o da versão ingênua. O handler captura as falhas e termina sem erro, e a documentação do Lambda diz que, quando a função processa o lote com sucesso, o Lambda apaga as mensagens da fila. A lista de falhas vira um valor de retorno qualquer, e as mensagens que falharam somem sem passar pela DLQ.

É um erro fácil de cometer porque o código parece certo, e a outra metade da correção está no template. No projeto, o consumer de notificação simula 25% de falha aleatória, o suficiente para gerar lotes mistos com frequência.

6.0 DLQ: separando erro passageiro de erro permanente

A fila de Financeiro simula outro tipo de falha: um erro de negócio permanente, como um valor de cobrança inválido, que nenhum retry corrige.

if random.random() < TAXA_ERRO_PERMANENTE:
    raise InvalidOperation(
        f"Valor de cobrança inválido para pedido {pedido_id}: {valor}"
    )

A diferença importa. Para falha passageira (timeout de rede, serviço fora do ar por alguns segundos), retry é o comportamento certo. Para falha permanente, retry só atrasa o inevitável e gasta concorrência. A fila tenta 3 vezes antes de desistir:

FinanceiroQueue:
  Type: AWS::SQS::Queue
  Properties:
    VisibilityTimeout: 90   # 6x o timeout de 15s da função
    RedrivePolicy:
      deadLetterTargetArn: !GetAtt FinanceiroDLQ.Arn
      maxReceiveCount: 3

Depois da terceira entrega sem sucesso, o SQS move a mensagem para a DLQ sozinho. Não precisa de código.

Nessa fila, o erro mais comum é esquecer o alarme na própria DLQ:

FinanceiroDLQAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    Namespace: AWS/SQS
    MetricName: ApproximateNumberOfMessagesVisible
    Dimensions:
      - Name: QueueName
        Value: !GetAtt FinanceiroDLQ.QueueName
    Statistic: Maximum
    Period: 300
    EvaluationPeriods: 1
    Threshold: 0
    ComparisonOperator: GreaterThanThreshold

Sem o alarme, as mensagens se acumulam na DLQ sem ninguém ser avisado, e o problema só aparece quando alguém nota que uma parte dos pedidos nunca gerou cobrança. Até lá, podem ser semanas de mensagens para investigar uma por uma.

7.0 Quando o EventBridge sozinho basta

Nem todo consumidor precisa de fila no meio. O processar_pedido, que classifica o pedido por faixa de valor, é rápido, tem volume baixo e não precisa de controle de ritmo. Para ele, a fila interna do Lambda dá conta, e uma fila SQS na frente seria só mais uma peça para manter.

No projeto, a quarta rota leva o PedidoCriado direto para essa função:

ProcessarPedidoFunction:
  Type: AWS::Serverless::Function
  Properties:
    Events:
      PedidoCriado:
        Type: EventBridgeRule
        Properties:
          EventBusName: !Ref PedidosEventBus
          Pattern:
            source: [observability-demo.pedidos]
            detail-type: [PedidoCriado]
          DeadLetterConfig:
            Arn: !GetAtt RuleDLQ.Arn
    EventInvokeConfig:
      MaximumRetryAttempts: 2
      DestinationConfig:
        OnFailure:
          Type: SQS
          Destination: !GetAtt ProcessarFalhasQueue.Arn

Sem fila no meio, essa rota precisa de duas redes de segurança, uma de cada lado da entrega.

A primeira é o DeadLetterConfig na regra, que pega falha de entrega. O EventBridge tentou invocar a função por até 24 horas e não conseguiu, por exemplo por causa de uma permissão alterada sem ninguém notar.

A segunda é o destino OnFailure no Lambda. Quando o Lambda aceita o evento na fila interna, a entrega do EventBridge está concluída. Se depois a função errar na primeira tentativa e nas duas seguintes, o Lambda descarta o evento, e a DLQ da regra não fica sabendo de nada. O OnFailure manda esse evento para a ProcessarFalhasQueue em vez de jogá-lo fora. É fácil configurar só a primeira rede e achar que a rota está protegida.

Nas rotas com fila, a divisão é parecida. A RuleDLQ também protege os três alvos SQS contra falha de entrega, e a falha de processamento fica com a DLQ de cada fila, pelo maxReceiveCount da seção 6.0.

8.0 A policy da fila, que só aparece quando falta

O fan-out não funciona sem um passo que é fácil de pular: o EventBridge precisa de permissão explícita para escrever em cada fila.

EstoqueQueuePolicy:
  Type: AWS::SQS::QueuePolicy
  Properties:
    Queues: [!Ref EstoqueQueue]
    PolicyDocument:
      Statement:
        - Effect: Allow
          Principal: { Service: events.amazonaws.com }
          Action: sqs:SendMessage
          Resource: !GetAtt EstoqueQueue.Arn
          Condition:
            ArnEquals: { "aws:SourceArn": !GetAtt EstoqueRule.Arn }

Sem essa policy, a regra é criada, o alvo aparece configurado, e os eventos não chegam. O produtor não vê erro nenhum, porque o PutEvents deu certo: a falha acontece depois, na entrega. É o tipo de falha que a RuleDLQ da seção 7.0 captura. Sem ela, você só descobre quando o time de um domínio reclama que não recebe nada.

A condição ArnEquals limita a permissão àquela regra. Em bus customizado, o ARN da regra inclui o nome do bus (rule/pedidos-bus-dev/nome-da-regra), então usar !GetAtt EstoqueRule.Arn evita montar esse ARN à mão e errar o formato.

9.0 Checklist antes de ir para produção

Use esta lista como revisão do template antes do primeiro deploy em produção. Cada item é uma falha que aparece nos cenários deste artigo.

9.1 Filas SQS

Visibility timeout de pelo menos 6x o timeout da função consumidora, em cada fila
BatchSize compatível com o timeout: lote vezes o tempo de cada mensagem cabe na função
DLQ configurada em toda fila que alimenta um consumidor crítico
maxReceiveCount calibrado: baixo o bastante para não represar retry inútil, alto o bastante para sobreviver a uma falha passageira
Resource policy da fila liberando sqs:SendMessage só para a regra específica, com aws:SourceArn

9.2 Consumidor Lambda

ReportBatchItemFailures ligado no event source mapping, e não só no código
Handler com BatchProcessor (ou lógica equivalente) devolvendo batchItemFailures
Consumidor idempotente, porque a fila padrão entrega pelo menos uma vez
MaximumConcurrency definido onde o sistema downstream não aguenta o pico

9.3 EventBridge

DeadLetterConfig em cada alvo da regra, principalmente quando não há fila no meio
Destino OnFailure (ou DLQ da função) quando a regra invoca a Lambda direto

9.4 Alarmes

Alarme em ApproximateNumberOfMessagesVisible de cada DLQ, incluindo a da regra
Alarme em ApproximateAgeOfOldestMessage das filas principais, para detectar consumidor atrasado

10.0 Projeto de exemplo

O repositório estende o observability-demo dos artigos anteriores com o fan-out completo: três filas com seus consumidores, a rota direta para a Lambda de classificação, as policies e os alarmes descritos acima. Cada consumer tem um comentário no código explicando a lição daquela fila.

diegobroetto / observability-demo

Demo serverless de observabilidade com CloudWatch + X-Ray (logs, metricas EMF, traces) - AWS SAM

observability-demo

Exemplo completo de observabilidade serverless com CloudWatch + X-Ray para o artigo:

"Observabilidade serverless sem surpresa no bolso: logs, métricas e traces com CloudWatch + X-Ray do jeito certo"

O que este projeto demonstra

Pilar	Ferramenta	Onde ver no código
Logs estruturados	Powertools Logger + JSON nativo do Lambda	`observability.py`, todos os handlers
Retenção de logs	AWS::Logs::LogGroup com RetentionInDays	`template.yaml` → LogGroups
Log level por ambiente	Mappings no SAM + LOG_EVENT flag	`template.yaml` → Mappings
Métricas sem custo extra	Embedded Metric Format (EMF)	`criar_pedido/handler.py`
Métricas com dimensão de negócio	Powertools Metrics + add_dimension	`processar_pedido/handler.py`
Traces por subsegmento	Powertools Tracer + @capture_method	Todos os handlers
Anotações no X-Ray	tracer.put_annotation	`consultar_pedido/handler.py`
Alarmes em p99	AWS::CloudWatch::Alarm + ExtendedStatistic	`template.yaml` → Alarmes
Dashboard consolidado	AWS::CloudWatch::Dashboard	`template.yaml` → Dashboard
Queries prontas	CloudWatch Logs Insights	`monitoring/insights-queries.md`

Endpoints

Método	Path	Função	Descrição
POST	`/pedidos`	CriarPedidoFunction	Cria o pedido e publica `PedidoCriado` no EventBridge
GET	`/pedidos/{id}`

…

View on GitHub

Para rodar:

sam build --use-container
sam deploy --config-env dev

O README traz o passo a passo para reproduzir os três erros de propósito: reduzir o visibility timeout, remover a flag de resposta parcial e ver a DLQ recebendo mensagem.

O projeto tem limitações que vale deixar claras. Não há testes automatizados, os alarmes cobrem só a fila de Estoque e as DLQs de Financeiro, da regra e do processar_pedido, e os consumers simulam as integrações (estoque, e-mail, cobrança) em vez de chamar sistemas reais.

11.0 Conclusão

A pergunta "EventBridge ou SQS?" parte de uma premissa errada. O que importa é o que cada ponto do fluxo precisa: roteamento ou durabilidade. Às vezes é só um dos dois. No projeto de pedidos, com quatro consumidores, precisou dos dois.

Configure DLQ no alvo da regra do EventBridge e em cada fila SQS desde o primeiro deploy, não depois que algo já sumiu. E antes de copiar um BatchSize: 10 de algum exemplo, faça duas contas: quanto tempo o lote leva no pior caso, e o que acontece quando a nona mensagem dá certo e a décima falha.

Diego Broetto é Tech Lead na Darede e escreve sobre AWS, serverless e infraestrutura como código.

Já passou por alguma dessas pegadinhas de um jeito diferente? Comenta aqui embaixo.

AWS Lambda MicroVMs: Sandboxes Isolados com Controle Total do Ciclo de Vida

Diego Broetto — Tue, 18 Aug 2026 15:55:37 +0000

No dia 22/07/2026 a AWS anunciou o AWS Lambda MicroVMs, um recurso novo dentro do Lambda, com API própria, separado das Functions que a gente já conhece. E não é só mais uma opção de runtime. É um primitivo de computação novo, pensado pra um problema que vinha incomodando bastante gente: como dar a cada usuário (ou sessão, ou agente de IA) um ambiente isolado de verdade, que suba rápido e mantenha estado, sem você ter que construir sua própria camada de virtualização do zero.

Antes de ir pro exemplo prático vale entender por que isso existe. Se você constrói algo como um assistente de código com IA, um ambiente de execução interativo, uma plataforma de análise de dados ou um scanner de vulnerabilidades, você provavelmente já bateu de frente com esse trilema: VM tradicional isola bem mas demora minutos pra subir, container sobe rápido mas compartilha kernel com o host (o que exige um trabalho de hardening considerável pra rodar código não confiável), e Function as a Service é ótimo pra evento-resposta mas não guarda estado entre interações de uma sessão longa. O MicroVMs foi desenhado exatamente pra esse buraco no meio.

Um aviso rápido antes de continuar: nos últimos artigos eu vim criando todos os templates utilizando o AWS SAM. Desta vez troquei pra Terraform, e vale explicar o porquê. SAM/CloudFormation continuam cobrindo bem o pedaço nativo de MicroVM Image e Network Connector. Isso não mudou. Mas o resto do laboratório (VPC, buckets, S3 Files, IAM) é onde eu realmente vivo no dia a dia, e o provider hashicorp/aws (a partir da v6.40.0) já tem recursos nativos pra Amazon S3 Files (aws_s3files_*). Pra imagem e o network connector, enquanto o provider não tem recurso nativo pra isso (issue #48526 ainda aberta), uso null_resource + local-exec como ponte pro AWS CLI.

1.0 O que muda em relação ao Lambda que você já usa

O motor por baixo é o mesmo Firecracker que já roda as Functions, então o isolamento de VM (kernel próprio, sem recurso compartilhado entre sessões) é a mesma garantia de sempre. A diferença está no modelo de uso: em vez de deploy-then-invoke, aqui é imagem-então-lançamento. Você empacota uma aplicação com Dockerfile, a AWS builda essa imagem, inicializa a aplicação dentro dela e tira um snapshot Firecracker da memória e do disco naquele estado pronto. Todo MicroVM lançado a partir dessa imagem depois disso não faz boot frio: ele resume direto do snapshot.

Na prática isso significa que sua API já está de pé no instante em que o lançamento termina. E tem outra coisa que o Lambda tradicional não te dá: controle explícito de ciclo de vida. Você define uma política de idle (quanto tempo sem tráfego até suspender, quanto tempo suspenso antes de encerrar de vez, se retoma automaticamente ou não), e o MicroVM pode ficar suspenso com estado intacto por até 8 horas de runtime total. Por padrão, o container roda com um conjunto restrito de capabilities do Linux, e é isso que vai importar no exemplo a seguir.

2.0 Colocando isso pra rodar

Montei uma API de workspace de arquivos com FastAPI, com o objetivo de: provar que o estado sobrevive não só a uma suspensão, mas ao fim completo do MicroVM. O disco não é local, que é parte do snapshot e some quando o MicroVM é terminado. É o Amazon S3 Files montado dentro da imagem, um sistema de arquivos que expõe objetos do S3 como se fossem arquivos comuns, via NFS, no mesmo caminho local. O workspace passa a viver fora do ciclo de vida de qualquer MicroVM individual, e cada arquivo escrito vira um objeto de verdade no bucket por trás.

O repositório completo está em lambda-microvms-workspace-demo.

2.1 A API: app.py

import time
from pathlib import Path

from aws_lambda_powertools import Logger
from fastapi import FastAPI, HTTPException, UploadFile
from fastapi.responses import FileResponse

app = FastAPI()

# Sem inject_lambda_context aqui: esse decorator injeta cold_start,
# function_request_id etc. a partir do objeto context de uma invocação
# Lambda, e esse FastAPI roda como servidor de longa duração dentro do
# MicroVM, sem um context por request. O que eu ganho de graça mesmo
# assim é o log em JSON estruturado, sem escrever formatter na mão.
logger = Logger(service="workspace-microvm")

# Esse caminho é o ponto de montagem do Amazon S3 Files, não disco
# local do MicroVM. Cada arquivo aqui é, por baixo, um objeto no S3,
# então sobrevive à suspensão E à terminação do MicroVM.
WORKSPACE_DIR = Path("/mnt/workspace")


@app.get("/health")
def health():
    mounted = WORKSPACE_DIR.exists() and WORKSPACE_DIR.is_mount()
    return {"status": "ok", "workspace_mounted": mounted}


@app.post("/files")
async def upload_file(file: UploadFile):
    destination = WORKSPACE_DIR / file.filename
    content = await file.read()
    destination.write_bytes(content)
    logger.info("Arquivo salvo via S3 Files", filename=file.filename, size_bytes=len(content))
    return {"filename": file.filename, "size_bytes": len(content), "stored_at": str(destination)}


@app.get("/files")
def list_files():
    files = [
        {
            "filename": f.name,
            "size_bytes": f.stat().st_size,
            "modified_at": time.ctime(f.stat().st_mtime),
        }
        for f in WORKSPACE_DIR.iterdir()
        if f.is_file()
    ]
    logger.info("Listagem de workspace solicitada", total_arquivos=len(files))
    return {"workspace_dir": str(WORKSPACE_DIR), "files": files}


@app.get("/files/{filename}")
def download_file(filename: str):
    file_path = WORKSPACE_DIR / filename
    if not file_path.exists():
        logger.warning("Download solicitado para arquivo inexistente", filename=filename)
        raise HTTPException(status_code=404, detail="Arquivo não encontrado no workspace")
    return FileResponse(file_path)

2.2 Montando o S3 Files: entrypoint.sh

#!/bin/sh
set -e

mkdir -p /mnt/workspace

if [ -z "${S3FILES_MOUNT_TARGET}" ]; then
  echo "ERRO: variável S3FILES_MOUNT_TARGET não definida." >&2
  exit 1
fi

# S3FILES_MOUNT_TARGET chega aqui como variável de ambiente definida
# na CRIAÇÃO DA IMAGEM, não no lançamento. Mais sobre esse detalhe
# na seção 2.4.
mount -t nfs4 -o nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2 \
  "${S3FILES_MOUNT_TARGET}:/lambda" /mnt/workspace

exec uvicorn app:app --host 0.0.0.0 --port 5000

2.3 Estrutura do repositório: da imagem ao Terraform

lambda-microvms-workspace-demo/
├── app/                    # FastAPI + entrypoint.sh + Dockerfile
├── infra/                  # Terraform "flat": vpc, s3, s3files, iam, microvm, outputs
├── scripts/                # só helpers chamados pelo apply/destroy (create_*, delete_*)
├── docs/
│   └── MANUAL.md           # guia manual passo a passo pra lançar, testar e provar durabilidade
└── Makefile                # só init / plan / apply / destroy

Reparem numa coisa, o repositório não tem make run, make test nem make proof. Isso é proposital. O Makefile só cobre init, plan, apply e destroy: tudo que é infraestrutura versionada. Lançar um MicroVM, gerar token, testar com curl e reproduzir a prova de durabilidade viraram uma sequência de comandos documentada em docs/MANUAL.md, não um script automatizado. O motivo é o mesmo que já defendi antes: imagem é infraestrutura versionada, MicroVM em execução é sessão efêmera, e sessão efêmera não deveria ter um make escondendo o que está de fato acontecendo, e muito menos ir parar no state do Terraform.

"Sempre que trabalho com Makefiles, me vem a memória do tempo da graduação, quando criava os arquivos de build para rodar meus programas em C."

2.4 Provisionando com Terraform

infra/ fica flat de propósito: vpc.tf, s3.tf, s3files.tf, iam.tf, microvm.tf, outputs.tf. A VPC é mínima, sem NAT gateway: nem o MicroVM nem os mount targets do S3 Files precisam de saída pra internet, só de rota entre si na porta 2049.

Uma peça de IAM que não tinha aparecido antes: o S3 Files usa um papel próprio pra sincronizar o que é escrito via NFS de volta pro bucket, e esse papel assume o principal elasticfilesystem.amazonaws.com. O S3 Files compartilha parte da arquitetura de serviço com o EFS por baixo, o que explica o principal emprestado. Esse papel de sync precisa de s3:GetObject, s3:PutObject, s3:ListBucket e s3:DeleteObject no bucket do workspace, e o bucket precisa ter versionamento habilitado. Sem isso a sincronização não funciona.

# infra/iam.tf (trecho)
resource "aws_iam_role" "s3files_sync" {
  name = "${var.project_name}-s3files-sync-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "elasticfilesystem.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}

resource "aws_iam_role_policy" "s3files_sync_bucket_access" {
  name = "${var.project_name}-s3files-sync-bucket-access"
  role = aws_iam_role.s3files_sync.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Sid      = "SyncWorkspaceBucket"
      Effect   = "Allow"
      Action   = ["s3:GetObject", "s3:PutObject", "s3:ListBucket", "s3:DeleteObject"]
      Resource = [aws_s3_bucket.workspace.arn, "${aws_s3_bucket.workspace.arn}/*"]
    }]
  })
}

microvm.tf é onde fica a ponte via CLI, porque o provider ainda não tem aws_lambda_microvm_image nem equivalente pro network connector. O detalhe que mudou desde a última vez: o S3FILES_MOUNT_TARGET entra como variável de ambiente na criação da imagem, não no lançamento. Variáveis de ambiente do MicroVM são resolvidas em build time e congelam no snapshot. Se eu passasse isso no run-microvm, o entrypoint.sh simplesmente não veria o valor, porque ele já rodou antes de qualquer parâmetro de lançamento existir.

Outro ajuste: o provider do Terraform não expõe o DNS do mount target do S3 Files (diferente do EFS, que tem um DNS previsível por AZ). O jeito que encontrei foi ler o IP privado da ENI do mount target direto do Terraform e passar esse IP como valor da variável de ambiente:

# infra/microvm.tf (trecho)
data "aws_network_interface" "s3files_mount_target" {
  filter {
    name   = "description"
    values = ["EFS mount target for fs-*"] # o S3 Files reaproveita o padrão de descrição do EFS na ENI
  }
  filter {
    name   = "subnet-id"
    values = [aws_subnet.private[0].id]
  }
}

resource "null_resource" "microvm_image" {
  triggers = {
    artifact_etag = aws_s3_object.app_artifact.etag
    mount_ip      = data.aws_network_interface.s3files_mount_target.private_ip
  }

  provisioner "local-exec" {
    command = "${path.module}/../scripts/create_microvm_image.sh"
    environment = {
      IMAGE_NAME        = var.project_name
      BASE_IMAGE_ARN    = "arn:aws:lambda:${var.aws_region}:aws:microvm-image:al2023-1"
      BUILD_ROLE_ARN    = aws_iam_role.microvm_build.arn
      ARTIFACT_URI      = "s3://${aws_s3_bucket.artifact.id}/${aws_s3_object.app_artifact.key}"
      MOUNT_TARGET_IP   = data.aws_network_interface.s3files_mount_target.private_ip
      MIN_MEMORY_MIB    = var.microvm_memory_mb
      AWS_REGION        = var.aws_region
      OUTPUT_FILE       = "${path.module}/../.build/image_arn.txt"
    }
  }
}

O scripts/create_microvm_image.sh monta o comando de fato:

aws lambda-microvms create-microvm-image \
  --name "${IMAGE_NAME}" \
  --base-image-arn "${BASE_IMAGE_ARN}" \
  --build-role-arn "${BUILD_ROLE_ARN}" \
  --code-artifact "{\"uri\":\"${ARTIFACT_URI}\"}" \
  --additional-os-capabilities '["ALL"]' \
  --environment-variables "{\"S3FILES_MOUNT_TARGET\":\"${MOUNT_TARGET_IP}\"}" \
  --resources "{\"minimumMemoryInMiB\":${MIN_MEMORY_MIB}}"

Reparei que a memória se divide em dois lugares diferentes do ciclo de vida: minimumMemoryInMiB na criação da imagem define o piso (o mesmo piso de 512 MB que o S3 Files exige pra habilitar leitura direta do S3), e a política de idle, que é por lançamento, só aparece depois, no run-microvm. Faz sentido: memória é característica da imagem (do jeito que a aplicação foi construída e testada), idle é característica de cada sessão.

scripts/ ficou só com os helpers que o Terraform chama (create_microvm_image.sh, create_network_connector.sh) e os de limpeza (delete_microvm_image.sh, delete_network_connector.sh, chamados no terraform destroy). Nada de script de teste ali. Isso é o próximo passo, na mão.

Pra provisionar tudo:

make init && make apply
# equivalente a:
# cd infra && terraform init && terraform apply

2.5 Rodando na mão: do lançamento ao teste

O docs/MANUAL.md documenta essa sequência inteira. Primeiro, pego os outputs do Terraform e lanço o MicroVM:

cd infra
IMAGE_ARN=$(terraform output -raw microvm_image_arn)
EXECUTION_ROLE_ARN=$(terraform output -raw microvm_execution_role_arn)
CONNECTOR_ARN=$(terraform output -raw network_connector_arn)

aws lambda-microvms run-microvm \
  --image-identifier "${IMAGE_ARN}" \
  --image-version "1.0" \
  --execution-role-arn "${EXECUTION_ROLE_ARN}" \
  --egress-network-connectors "[\"${CONNECTOR_ARN}\"]" \
  --idle-policy '{"maxIdleDurationSeconds":300,"suspendedDurationSeconds":1800,"autoResumeEnabled":true}'

Sem variável de ambiente aqui: ela já foi resolvida lá atrás, na imagem. O comando devolve microvmId e endpointUrl. Com isso, gero um token de curta duração:

TOKEN=$(aws lambda-microvms create-microvm-auth-token \
  --microvm-identifier <microvmId> \
  --expiration-in-minutes 30 \
  --allowed-ports '[{"port":5000}]' \
  --query 'authToken."X-aws-proxy-auth"' --output text)

E testo o fluxo básico:

curl "<endpointUrl>/health" -H "X-aws-proxy-auth: ${TOKEN}"

curl -X POST "<endpointUrl>/files" -H "X-aws-proxy-auth: ${TOKEN}" -F "file=@notas.txt"

curl "<endpointUrl>/files" -H "X-aws-proxy-auth: ${TOKEN}"

2.6 Provando a durabilidade: terminate e relança

Até aqui, nada muito diferente do disco local. A prova de verdade vem agora: em vez de deixar o MicroVM só suspender, eu termino ele por completo e lanço um MicroVM novo, do zero, a partir da mesma imagem.

aws lambda-microvms terminate-microvm --microvm-identifier <microvmId-original>

# lança um MicroVM completamente novo, com um microvmId diferente
aws lambda-microvms run-microvm \
  --image-identifier "${IMAGE_ARN}" \
  --image-version "1.0" \
  --execution-role-arn "${EXECUTION_ROLE_ARN}" \
  --egress-network-connectors "[\"${CONNECTOR_ARN}\"]" \
  --idle-policy '{"maxIdleDurationSeconds":300,"suspendedDurationSeconds":1800,"autoResumeEnabled":true}'

Gero um token novo pro microvmId novo, e chamo GET /files de novo:

notas.txt aparece no GET /files do MicroVM novo, com um microvmId que nunca existiu antes. O snapshot desse MicroVM não tinha nenhuma referência a esse arquivo, porque o arquivo nunca esteve no disco local pra começo de conversa. Ele sempre foi um objeto no bucket S3 por trás, só sendo lido através do mount do S3 Files.

2.7 Limpando

Antes do terraform destroy, preciso terminar qualquer MicroVM ativo na mão:

aws lambda-microvms terminate-microvm --microvm-identifier <microvmId-atual>

O motivo é de rede, não de custo: um MicroVM em execução mantém uma interface de rede anexada às subnets privadas via egress network connector, e o destroy da VPC falha enquanto essa ENI ainda existir. Só depois disso:

make destroy
# equivalente a:
# cd infra && terraform destroy

3.0 O que eu levo em conta ao usar isso

3.1 Durabilidade e estado

S3 Files resolve um problema que nem suspensão longa nem export manual resolvem bem sozinhos. Disco local sobrevive suspensão mas está preso ao teto de 8 horas e ao ciclo de vida daquele MicroVM específico. Escrever direto no bucket via boto3 funciona, mas exige um passo explícito de upload que é fácil de esquecer. Montar S3 Files tira essa escolha do meio: a escrita já cai como objeto no bucket, sem passo extra, e ainda por cima falando com o S3, que é o storage que eu já confio.

512 MB de memória é o corte pra leitura direta do S3, e agora isso vive na imagem, não no lançamento. Abaixo desse valor o mount ainda funciona, mas sem o caminho otimizado de leitura direta do S3 Files. Definir minimumMemoryInMiB na criação da imagem em vez de deixar solto no run-microvm evita que alguém lance um MicroVM subdimensionado sem perceber.

3.2 Segurança e acesso

A capability de montagem é opt-in por um motivo, e eu penso duas vezes antes de habilitar. --additional-os-capabilities '["ALL"]' amplia bastante o que o container consegue fazer dentro do MicroVM, não é só liberação pontual pra mount. Vale pesar isso contra o quanto de isolamento eu realmente preciso pro caso de uso. Pra rodar código gerado por IA de origem desconhecida, por exemplo, eu penso duas vezes antes de dar essa capability extra.

Permissão de S3 Files é separada de permissão de S3 comum, e agora percebi que são três papéis, não dois. s3files:ClientMount e s3files:ClientWrite na role de execução do MicroVM cobrem o acesso via NFS. Mas o próprio S3 Files também precisa de uma role de sync (assumindo elasticfilesystem.amazonaws.com) pra escrever de volta no bucket, com versionamento obrigatório. Três papéis diferentes fazendo três coisas diferentes, fácil de confundir se você já tem uma policy de S3 pronta e assume que ela cobre tudo.

Rede não é implícita, é uma peça que eu declaro. Sem o egress network connector apontando pra minha VPC, o MicroVM simplesmente não alcança o mount target do S3 Files. Isso é bom: rede que só existe porque eu declarei explicitamente é mais fácil de auditar do que rede que "só funciona" por padrão.

3.3 Padrões de implementação

Variável de ambiente pro mount vai na imagem, não no lançamento, e isso é fácil de errar uma vez. Da primeira vez que tentei passar S3FILES_MOUNT_TARGET no run-microvm, o entrypoint.sh simplesmente não via o valor. Variáveis de ambiente do MicroVM são resolvidas em build time, junto com o resto do snapshot. Isso é consistente com a lição do post anterior sobre estado congelado, só que na direção contrária: aqui eu preciso que congele, porque é informação de infraestrutura, não de sessão.

O provider do Terraform não expõe DNS do mount target do S3 Files, só a ENI. Diferente do EFS, que tem um endpoint DNS previsível, tive que resolver o IP privado da interface de rede via data "aws_network_interface" filtrando pela descrição e pela subnet. Funciona, mas é um detalhe frágil: se a AWS mudar o padrão de descrição da ENI, esse filtro quebra.

Montar em runtime (dentro do container), não em build time (na instrução RUN do Dockerfile), continua valendo. O mount em si ainda acontece no entrypoint.sh quando o container sobe, porque o mount target só é alcançável quando a rede da imagem já está configurada. A variável de ambiente pode congelar no build, a chamada de mount não pode.

Múltiplos MicroVMs podem montar o mesmo file system ao mesmo tempo, e isso muda o desenho. Diferente do disco local, que é exclusivo daquele MicroVM, o S3 Files permite compartilhar workspace entre sessões diferentes se fizer sentido pro seu caso. Vale filtrar por sessão dentro da aplicação (um prefixo de diretório por usuário, por exemplo) pra não misturar dado de gente diferente sem querer.

NFS tem custo de latência que disco local não tem. Toda leitura e escrita passa pela rede até o mount target. Pra arquivo pequeno e acesso frequente isso raramente é perceptível, mas pra workload de I/O intenso vale medir antes de assumir que dá na mesma.

3.4 Observabilidade

Powertools funciona em MicroVMs, mas nem todo pedaço faz sentido do mesmo jeito. O Logger estruturado em JSON é ganho direto, sem precisar escrever formatter na mão. Mas inject_lambda_context, que injeta cold_start e function_request_id automaticamente, foi desenhado pra um lambda_handler(event, context) que roda uma vez por invocação. Aqui é um servidor FastAPI de longa duração, sem um context novo a cada request, então esse pedaço específico eu deixei de fora. Vale essa checagem sempre que trouxer uma lib pensada pra Function pra dentro de um MicroVM: parte do contrato pode não existir mais.

3.5 Arquitetura e deploy

Terraform e SAM/CloudFormation não competem aqui, cada um cobre uma parte diferente do mesmo problema. SAM tem recurso nativo pra AWS::Lambda::MicrovmImage desde o lançamento, o provider Terraform da AWS, não. Daí o null_resource + local-exec como ponte enquanto o issue #48526 não fecha. Em compensação, o Terraform já tem recursos nativos pra S3 Files (aws_s3files_*) desde a v6.40.0, o que deixa o resto do laboratório mais direto de escrever do que ficaria em CloudFormation puro. Escolher a stack de IaC também é escolher onde você aceita workaround (palavra chique para gambiarra).

Imagem entra no pipeline de IaC, lançamento não, e isso ficou ainda mais explícito nessa versão do repositório. O Makefile só tem init, plan, apply e destroy, de propósito, sem run, sem test. Lançar um MicroVM é decisão de runtime, documentada em docs/MANUAL.md como sequência manual de comandos, não escondida atrás de um alvo de Makefile que faria parecer parte do provisionamento.

MicroVMs e Functions não competem, se complementam. O próprio anúncio da AWS deixa isso explícito: Functions seguem sendo a escolha certa pro backbone evento-resposta da aplicação, e MicroVMs entra especificamente na etapa que precisa rodar código não confiável (gerado por usuário ou por IA) isolado, com estado que precisa sobreviver além de uma única execução.

3.6 Limites honestos deste laboratório

Não tem CI rodando isso. Os nomes de alguns parâmetros de CLI e os principals de trust policy (elasticfilesystem.amazonaws.com pro papel de sync, por exemplo) eu confirmei o suficiente pra funcionar no meu teste, mas não bati contra a referência oficial linha por linha. Vale conferir antes de replicar em produção. A criação de imagem não é totalmente idempotente: rodar create_microvm_image.sh duas vezes cria uma versão nova em vez de atualizar in-place. E a ponte via null_resource + local-exec pro image/connector é workaround assumido, não o caminho idiomático. Se seu time prioriza Terraform 100% nativo pra esse pedaço específico, SAM ainda é a opção mais direta hoje.

4.0 Conclusão

O que mais me chamou atenção nesse anúncio foi perceber que a AWS não criou uma tecnologia nova, ela deu acesso direto a uma peça que já sustentava o Lambda por trás dos panos há anos. Isso é coerente quando se entende a forma que o Firecracker funciona: entender a engenharia por baixo ajuda a prever pra onde o produto vai. E o Powertools que usei aqui pro Logger é o mesmo que detalhei naquele post sobre observabilidade serverless. O Logger continua valendo em MicroVM, só o contrato de invocação que muda. Trocar SAM por Terraform pra montar esse laboratório não mudou a história que o artigo conta, só me obrigou a ser mais explícito sobre o que cada stack cobre nativamente e onde ainda falta peça. Pensei em testar isso e ver até onde dá pra empurrar: rodar um agente de IA gerando e executando código de verdade dentro de um MicroVM com esse mesmo workspace compartilhado via S3 Files, e medir o custo real de manter várias sessões vivas ao mesmo tempo, isso pode gerar um novo artigo pra compartilhar.

Observabilidade serverless sem surpresa no bolso: logs, métricas e traces com CloudWatch + X-Ray do jeito certo

Diego Broetto — Thu, 16 Jul 2026 19:50:43 +0000

Tem uma fatura de CloudWatch que eu nunca vou esquecer.

Uma função Lambda simples, rodando há algumas semanas em produção. Sem grande volume. Sem nada de especial. Só que alguém tinha esquecido de configurar retenção de log, o X-Ray estava com sampling em 100%, e o log level estava em DEBUG porque "vou ajustar depois". A conta veio quase três vezes o esperado.

O pior não foi o valor. Foi saber que meu cliente tinha pagado para guardar lixo. Stack trace de erro que já estava resolvido. Trace de requisição que durou 12ms e nunca mais ninguém ia abrir. Log de evento completo com payload de cliente em texto plano num log group que ia existir pra sempre.

Observabilidade serverless não é caro por natureza. Fica caro quando você liga tudo no máximo e esquece. Este artigo é sobre não esquecer.

1.0 O problema específico do serverless

Em servidores tradicionais, você tem SSH. Tem processo rodando. Tem top, htop, journalctl. Quando algo dá errado, você entra na máquina e olha.

No Lambda, não tem nada disso. A função executa em milissegundos, o container some, e você ficou com o que colocou no log. Se não colocou nada útil, ou colocou tudo de forma errada, você está debugando no escuro.

Aí vem o impulso natural: loga tudo. Ativa X-Ray em todas as funções. Cria métrica para cada coisa que se move. Funciona. Mas o preço aparece no fim do mês.

A questão não é observar menos. É observar o que importa.

2.0 Os três pilares e o que cada um custa de verdade

Antes de falar de implementação, vale entender a tabela de preços do que você está usando.

CloudWatch Logs cobra em três momentos distintos: ingestão ($0,50/GB), armazenamento ($0,03/GB/mês) e consultas no Logs Insights ($0,005/GB escaneado). O armazenamento parece barato até você calcular que o padrão de retenção é "nunca expirar". Um log group de função Lambda com volume médio, sem retenção configurada, acumula sem parar.

CloudWatch Metrics tem métricas padrão do Lambda gratuitas. São muitas e cobrem bem o essencial: Duration, Errors, Throttles, ConcurrentExecutions, IteratorAge para Streams. O custo começa quando você cria métricas customizadas: $0,30 por métrica por mês. Soa pouco. Mas se você criar uma métrica por tenant_id com 500 tenants, são $150/mês só de métricas, sem incluir as chamadas de API para publicá-las.

X-Ray cobra $5,00 por 1 milhão de traces registrados e $0,50 por 1 milhão consultados. O sampling padrão da AWS é 1 requisição por segundo mais 5% do restante. Para a maioria das cargas, está OK. Para uma função processando 10 mil req/seg, 5% são 500 traces por segundo, 43 milhões por mês, $215 só de traces.

Esses números não são argumentos contra usar essas ferramentas. São argumentos para configurá-las de forma intencional.

3.0 Logs: estrutura antes de volume

O problema mais comum que vejo não é o volume de logs. É o formato.

Log em texto livre não serve em escala. Você não consegue filtrar, não consegue agregar, não consegue criar métricas a partir dele. Funciona para debug manual no console, mas quebra quando você precisa entender o que aconteceu às 3h da manhã em 200 invocações simultâneas.

JSON é o formato certo. O Lambda suporta nativamente desde 2023:

Globals:
  Function:
    LoggingConfig:
      LogFormat: JSON
      ApplicationLogLevel: INFO
      SystemLogLevel: WARN

Com isso, cada log já sai estruturado com timestamp, level, requestId e a mensagem. Você ainda precisa estruturar o que coloca no log, mas o envelope já está pronto.

3.1 Powertools Logger: o que ele faz que você não quer fazer na mão

O AWS Lambda Powertools tem um Logger que, além de JSON, injeta contexto da invocação automaticamente:

from aws_lambda_powertools import Logger

logger = Logger(service="pedidos")

@logger.inject_lambda_context(log_event=False)
def lambda_handler(event, context):
    logger.info("Pedido recebido", pedido_id=event["id"], valor=event["valor"])

O que aparece no log:

{
  "level": "INFO",
  "message": "Pedido recebido",
  "pedido_id": "abc-123",
  "valor": 179.80,
  "cold_start": true,
  "function_name": "pedidos-criar-prod",
  "function_memory_size": 512,
  "function_arn": "arn:aws:lambda:...",
  "function_request_id": "...",
  "timestamp": "2025-07-14T10:23:41.123Z",
  "service": "pedidos"
}

Exemplo no console:

cold_start está lá de graça. function_request_id está lá. Tudo que você precisaria escrever na mão já vem junto.

Um detalhe importante: log_event=False. Com True, o payload completo do evento vai para o log. Útil em desenvolvimento. Em produção, isso significa que dados do cliente vão para o CloudWatch em texto plano, e você vai pagar para armazenar informação que provavelmente não deveria estar lá. Controle isso por variável de ambiente:

@logger.inject_lambda_context(log_event=os.environ.get("LOG_EVENT") == "true")

No template SAM:

Environment:
  Variables:
    LOG_EVENT: !If [IsDev, "true", "false"]

3.2 append_keys: propagando contexto sem repetição

Dentro do handler, você frequentemente quer que o pedido_id apareça em todos os logs daquela invocação, não só no primeiro. O append_keys faz isso:

def lambda_handler(event, context):
    pedido_id = event["pathParameters"]["pedido_id"]
    logger.append_keys(pedido_id=pedido_id)

    # Daqui pra frente, todo log inclui pedido_id automaticamente
    pedido = buscar_pedido(pedido_id)
    logger.info("Pedido encontrado", status=pedido["status"])

3.3 Retenção: configure no primeiro deploy, não depois

O padrão do Lambda é criar o log group automaticamente com retenção "Nunca expirar". Isso parece inofensivo até você perceber que é um bug, não uma feature.

Configure via CloudFormation/SAM para não depender de lembrar:

PedidosLogGroup:
  Type: AWS::Logs::LogGroup
  Properties:
    LogGroupName: !Sub "/aws/lambda/pedidos-criar-${Environment}"
    RetentionInDays: !Ref LogRetentionDays

Com um parâmetro LogRetentionDays que varia por ambiente: 7 dias em dev, 30 em staging, 90 em prod. Ou o que compliance exigir, desde que não seja infinito.

3.4 Log level por ambiente

DEBUG em produção é a forma mais eficiente de dobrar sua conta de logs. Controle via Mappings no SAM:

Mappings:
  EnvConfig:
    dev:
      LogLevel: DEBUG
    staging:
      LogLevel: INFO
    prod:
      LogLevel: INFO

4.0 Um debug real: dois bugs atrás de uma mensagem genérica

Isso aconteceu comigo enquanto preparava o projeto de exemplo deste artigo. Deixo aqui porque é um caso melhor do que qualquer exemplo que eu inventaria.

Depois do primeiro deploy bem-sucedido, testei o POST /pedidos e recebi:

{"error": "Internal Erro. Try again."}

Sem mais detalhes. E propositalmente sem mais detalhes o handler captura qualquer exceção genérica e devolve essa mensagem amigável de propósito, porque uma API não deveria vazar stack trace para quem está do outro lado. Isso é certo do ponto de vista de segurança. Também significa que, sem observabilidade decente no backend, você fica cego.

Fui direto para o CloudWatch Logs Insights:

filter level = "ERROR"
| stats count() as ocorrencias by tipo_erro, operacao
| sort ocorrencias desc

E o log estruturado entregou na hora:

{
  "level": "ERROR",
  "operacao": "criar_pedido",
  "tipo_erro": "TypeError",
  "mensagem_erro": "Float types are not supported. Use Decimal types instead.",
  "pedido_id": null
}

O DynamoDB, via boto3, não aceita float nativo do Python, só Decimal. O handler estava salvando valor (179.80) direto como veio do JSON. A função processar_pedido já fazia essa conversão certinho, só a criar_pedido tinha escapado. Corrigi convertendo para Decimal(str(valor)) apenas no item que vai para o DynamoDB, mantendo float no dict usado para log, métrica e resposta HTTP, não queria efeito colateral na serialização JSON por causa de um tipo que só o DynamoDB exige.

Testei de novo. Erro genérico de novo. Voltei no Insights, mesma query, e apareceu um segundo erro, completamente diferente do primeiro:

{
  "level": "ERROR",
  "operacao": "criar_pedido",
  "tipo_erro": "ClientError",
  "mensagem_erro": "User: .../pedidos-criar-dev is not authorized to perform: events:PutEvents on resource: arn:aws:events:us-east-1:...:event-bus/default",
  "pedido_id": "..."
}

Esse foi mais sutil. O código tinha os.environ.get("EVENT_BUS_NAME", "default"), um fallback razoável à primeira vista. O problema é que a variável EVENT_BUS_NAME nunca tinha sido definida no template, então o fallback sempre disparava, e o código tentava publicar no event bus padrão da conta. A IAM policy, corretamente, só liberava PutEvents no bus customizado que o projeto realmente usa. Fallback silencioso mascarando uma variável de ambiente esquecida o tipo de bug que passa no code review porque parece defensivo.

O que faz esse caso valer a pena contar não é nenhum dos dois bugs isoladamente. É que sem tipo_erro e mensagem_erro como campos estruturados e pesquisáveis, eu estaria lendo texto corrido no console tentando adivinhar onde, entre duas invocações, a causa mudou completamente. Com log estruturado, foram duas queries idênticas, dois resultados diferentes, dois fixes de dez minutos cada.

É fácil ler a seção anterior sobre Powertools Logger e achar que pedido_id e cold_start automáticos são só conveniência. Na prática é a diferença entre filtrar por campo e grep em prosa.

5.0 Métricas: use o que é de graça antes de criar o que custa

Tem muita coisa útil antes de você precisar criar uma métrica customizada.

As métricas padrão do Lambda que mais uso no dia a dia:

Errors e ErrorRate: taxa de erro por função. Bom para alarme de SLA.
Duration com estatísticas p50, p90, p99: distribuição de latência. Nunca use só a média, ela esconde outliers. Uma função com p50 de 100ms e p99 de 8000ms está com problema que a média não mostra.
Throttles: qualquer valor acima de zero em produção merece atenção imediata.
ConcurrentExecutions: para detectar burst antes de virar throttle.
IteratorAge: se você tem função consumindo Kinesis ou DynamoDB Streams, isso é o lag do consumer. Subindo significa que você não está acompanhando o volume.

Todas gratuitas. Se essas cobrem o que você precisa, pare aqui.

5.1 Embedded Metric Format: métricas customizadas sem overhead de API

Quando você precisa de métrica customizada, o caminho certo é EMF, não put_metric_data.

O put_metric_data faz uma chamada de API para o CloudWatch a cada invocação. Além do custo das chamadas, é uma dependência extra que pode falhar e adiciona latência.

O EMF funciona diferente: você emite a métrica dentro do log JSON em um formato especial. O CloudWatch processa o log e cria a métrica automaticamente. Sem chamada de API extra, sem latência adicional.

Com o Powertools:

from aws_lambda_powertools import Metrics
from aws_lambda_powertools.metrics import MetricUnit

metrics = Metrics(namespace="MeuApp/Pedidos", service="pedidos")

@metrics.log_metrics(capture_cold_start_metric=True)
def lambda_handler(event, context):
    # Isso vira uma métrica CloudWatch via EMF — sem put_metric_data
    metrics.add_metric(name="PedidoProcessado", unit=MetricUnit.Count, value=1)
    metrics.add_dimension(name="Status", value="aprovado")

capture_cold_start_metric=True emite uma métrica ColdStart automaticamente. De graça, sem código extra.

5.2 A armadilha das dimensões de alta cardinalidade

Métricas customizadas com dimensão de alta cardinalidade são uma das formas mais rápidas de explodir o custo do CloudWatch.

Exemplo: você tem 1000 clientes e quer ver quantos pedidos cada um fez.

# ERRADO — 1000 métricas × $0,30 = $300/mês
metrics.add_dimension(name="ClienteId", value=cliente_id)
metrics.add_metric(name="PedidoCliente", unit=MetricUnit.Count, value=1)

Para esse caso, use Logs Insights:

filter mensagem = "Pedido processado"
| stats count() as total by cliente_id
| sort total desc

A consulta custa por GB escaneado, mas você só roda quando precisa. Dimensões de métrica fazem sentido quando a cardinalidade é baixa: status, tipo, ambiente, região. Não por cliente, não por produto individual, não por request ID.

6.0 X-Ray: o que ele mostra que os logs não mostram

Os logs dizem que uma invocação levou 800ms. O X-Ray diz que desses 800ms, 12ms foram no seu código, 750ms foram esperando o DynamoDB responder, e os outros 38ms foram no cold start.

Essa diferença muda completamente onde você vai olhar para resolver o problema.

6.1 capture_method: subsegmentos sem boilerplate

Com o Powertools Tracer, você adiciona subsegmentos com um decorator:

from aws_lambda_powertools import Tracer

tracer = Tracer(service="pedidos")

@tracer.capture_lambda_handler(capture_response=False)
def lambda_handler(event, context):
    pedido = _parse_body(event)
    _salvar_pedido(pedido)
    _publicar_evento(pedido)

@tracer.capture_method
def _salvar_pedido(pedido):
    # O X-Ray vai mostrar exatamente quanto tempo este método levou
    table.put_item(Item=pedido)

@tracer.capture_method
def _publicar_evento(pedido):
    eventbridge.put_events(...)

capture_response=False evita que o response completo vá para o trace, o que pode incluir dados sensíveis e aumentar custo de armazenamento.

6.2 put_annotation: filtrando traces que importam

Anotações no X-Ray permitem filtrar traces por valor de negócio:

tracer.put_annotation(key="status_pedido", value=status)
tracer.put_annotation(key="valor_acima_limite", value=valor > 500)

No console do X-Ray, você consegue filtrar annotation.status_pedido = "rejeitado" e ver só os traces de pedidos rejeitados. Muito mais útil do que varrer logs para encontrar o mesmo padrão.

6.3 Sampling rules: a configuração que mais gente ignora

O padrão da AWS é 1 req/seg fixo mais 5% do restante. Para a maioria das funções está OK. O problema é quando você tem funções de alto volume.

Configure sampling rules por função ou por padrão de ARN:

{
  "RuleName": "HighVolumeFunction",
  "Priority": 1,
  "FixedRate": 0.01,
  "ReservoirSize": 1,
  "ServiceName": "pedidos-processar-*",
  "ResourceARN": "*"
}

1% para função de alto volume que você já conhece bem é diferente de 5% para uma função nova que pode ter comportamento inesperado. Trate isso por função, não como configuração global.

Tem casos onde faz sentido desligar o X-Ray completamente: função de health check, processamento homogêneo de fila onde todos os traces são idênticos, função de baixa complexidade sem downstream calls. Nesses casos, logs estruturados com Duration no CloudWatch cobrem o que importa.

7.0 Alarmes: o que monitorar de verdade

Um dashboard sem alarme é decoração. Você precisa ser avisado quando algo sai do normal, não descobrir na próxima vez que abrir o console.

Três alarmes que eu considero mínimo obrigatório por função crítica:

Taxa de erro: monitore Errors, não ErrorRate, porque ErrorRate é percentual e pode mascarar volume real. Se você tem 0,1% de erro em 1 milhão de invocações, são 1000 erros. Coloque um alarme absoluto e um relativo.

Latência p99: não p50, não média. O p99 mostra o que seus usuários mais lentos estão experimentando. Um alarme em 80% do timeout configurado dá tempo de agir antes de começar a ter timeouts reais:

CriarPedidoDurationAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    MetricName: Duration
    ExtendedStatistic: p99
    Threshold: 24000  # 80% de 30s = 24000ms
    ComparisonOperator: GreaterThanThreshold

Throttles: qualquer valor acima de zero em produção. Throttle significa que você está descartando tráfego. É uma emergência, não uma métrica para acompanhar.

8.0 Dashboard: visão consolidada, não por função

Um dashboard por função não serve. Quando algo dá errado em produção, você quer ver o sistema inteiro, não abrir 12 dashboards em abas diferentes.

Monte um dashboard por stack ou por domínio de negócio com:

Taxa de erro de todas as funções em um gráfico só
Latência p99 de todas as funções
Invocações totais por função
Throttles
Métricas de negócio via EMF (pedidos criados, processados, rejeitados)

O template SAM do projeto de exemplo gera esse dashboard via CloudFormation. Nada para configurar no console, versionado junto com a infraestrutura.

9.0 Checklist antes de ir para produção

[ ] LogFormat: JSON em todas as funções (template Globals)
[ ] ApplicationLogLevel: INFO em prod (nunca DEBUG)
[ ] log_event=False em prod (controle por variável de ambiente)
[ ] RetentionInDays configurado em todos os log groups
[ ] Métricas de Duration usando p99, não média
[ ] Sampling rule do X-Ray revisada para funções de alto volume
[ ] capture_response=False no Tracer em prod
[ ] Alarme em Errors (absoluto)
[ ] Alarme em Duration p99 (> 80% do timeout)
[ ] Alarme em Throttles (qualquer valor > 0)
[ ] Dashboard consolidado por stack
[ ] Budget Alert no Cost Explorer separando CloudWatch dos outros serviços

O último item parece paranoia até deixar de ser.

10.0 Projeto de exemplo

O repositório que acompanha este artigo tem uma API de pedidos completa com quatro funções Lambda demonstrando cada conceito na prática:

criar_pedido: POST /pedidos com Logger, Tracer e Metrics configurados
consultar_pedido: GET /pedidos/{id} com anotações X-Ray e métricas de hit/miss
processar_pedido: consumidor EventBridge com métricas de negócio por dimensão de status
decidir_pedido: PATCH /pedidos/{id}/aprovar e /rejeitar, aprovação e rejeição manual de pedidos que ficaram em aguardando_aprovacao

A quarta função existe porque a classificação automática por valor deixava um estado sem saída: pedidos na faixa intermediária ficavam parados em aguardando_aprovacao sem nenhum jeito de sair dali. As duas rotas aprovar e rejeitar são atendidas pela mesma Lambda, com a ação derivada do path da requisição. Menos uma função duplicada, menos um cold start a mais para gerenciar.

Regra de negócio (classificação automática por valor):

Valor do pedido	Status resultante
≤ R$ 500,00	`aprovado` (automático)
R$ 500,01 – R$ 5.000,00	`aguardando_aprovacao` (precisa de `/aprovar` ou `/rejeitar`)
> R$ 5.000,00	`rejeitado` (automático)

Endpoints:

Método	Path	Função	Notas
POST	`/pedidos`	`criar_pedido`	Publica `PedidoCriado` no EventBridge
GET	`/pedidos/{id}`	`consultar_pedido`	404 se não existir
PATCH	`/pedidos/{id}/aprovar`	`decidir_pedido`	409 se o pedido não estiver em `aguardando_aprovacao`
PATCH	`/pedidos/{id}/rejeitar`	`decidir_pedido`	409 se o pedido não estiver em `aguardando_aprovacao`

A transição de status usa ConditionExpression no update_item do DynamoDB o mesmo padrão de idempotência do processar_pedido para garantir que a decisão só é aplicada uma vez, mesmo com requisições concorrentes. Quando a condição falha, uma leitura simples desambigua entre "pedido não existe" (404) e "pedido já está em outro status" (409, com o status atual na mensagem).

A observabilidade segue o mesmo padrão das outras funções: métrica EMF PedidoDecididoManualmente com dimensão Decisao (aprovado/rejeitado), anotação X-Ray decisao_manual, e logs estruturados com pedido_id, acao e novo_status. O dashboard ganhou um widget novo para essas decisões, e o widget "Pedidos por Status" foi corrigido para incluir a série aguardando_aprovacao faltava no dashboard original, o que por si só é um bom lembrete de revisar dashboard quando o domínio de negócio ganha um status novo.

O template SAM inclui log groups com retenção, alarmes em p99 e throttles, dashboard CloudWatch e Mappings de configuração por ambiente.

Para rodar:

sam build --use-container
sam deploy --config-env dev

As queries prontas para o Logs Insights estão em monitoring/insights-queries.md no repositório.

O que este exemplo ainda não cobre, para ser honesto: os alarmes de erro e duração hoje existem só para criar_pedido, decidir_pedido e consultar_pedido ainda não têm réplica. Também não há notificação (SNS ou e-mail) quando um pedido entra em aguardando_aprovacao hoje isso só é visível consultando a API ou o dashboard. E não existem testes automatizados. Nenhum desses pontos invalida o que foi demonstrado sobre observabilidade, mas vale deixar claro que é um projeto de exemplo, não um sistema pronto para produção.

🔗 Repositório com os exemplos: https://github.com/diegobroetto/observability-demo

11.0 Conclusão

Observabilidade serverless cara geralmente é observabilidade descuidada. DEBUG em produção, retenção infinita, X-Ray sem sampling rule em função de alto volume, métrica customizada com dimensão de alta cardinalidade qualquer um desses sozinho não parece grande coisa. Junto viram uma fatura que você não esperava.

O Powertools for Lambda resolve 80% do trabalho sem boilerplate. O resto é configuração intencional no template: retenção por ambiente, log level por ambiente, sampling por tipo de função.

E configure os alarmes antes de precisar deles. O dashboard você abre quando quer. O alarme te acorda quando você precisa.

[Boost]

Diego Broetto — Thu, 11 Jun 2026 20:36:29 +0000

Diego Broetto

Jun 11

SAM CLI + Language Extensions: o fim do copy-paste em templates serverless

#aws #serverless #cloudformation #braziliandevs

9 min read

SAM CLI + Language Extensions: o fim do copy-paste em templates serverless

Diego Broetto — Thu, 11 Jun 2026 20:04:33 +0000

1.0 Introdução

Se você já trabalhou com AWS SAM em projetos com múltiplos ambientes, provavelmente já viveu essa cena: precisa adicionar uma nova função Lambda ao projeto, abre o template.yaml, encontra o bloco da função existente, seleciona tudo, cola abaixo, começa a trocar os valores um por um. Nome da função, variável de ambiente, tag, CodeUri. Torcer pra não esquecer nada.

Um tempo depois, alguém aumenta o timeout de uma das funções e esquece de replicar nas outras duas. É um caso bem comum e que já vi se repetir em vários clientes do meu dia a dia.

Esse problema se chama copy-paste em IaC. E no SAM, ele era difícil de resolver.

Quem usa CloudFormation no dia a dia sabe que desde 2023 o AWS::LanguageExtension com Fn::ForEach permite gerar múltiplos recursos a partir de uma única definição. O problema é que o SAM CLI simplesmente não entendia esse bloco. Você tentava rodar um sam local invoke com um template que usava Fn::ForEach e levava um erro. O resultado era uma escolha ingrata: templates DRY ou desenvolvimento local com o SAM. Não dava pra ter os dois.

Em maio de 2026, a AWS resolveu isso. O SAM CLI agora processa Language Extensions em memória durante as operações locais e o template original segue intacto para o deploy no CloudFormation.

Nesse artigo vou mostrar como migrar esses templates repetitivos para uma estrutura gerada com Fn::ForEach, com exemplos que você pode testar agora mesmo no seu ambiente.

2.0 Contexto

Antes de entrar no código, vale entender por que esse problema durou tanto tempo.

O AWS::LanguageExtensions é um transform do CloudFormation lançado em 2023. Ele desbloqueia um conjunto de funções que não estão disponíveis por padrão nos templates, a principal delas sendo o Fn::ForEach: você itera sobre uma lista e gera múltiplos recursos a partir de uma única definição. Parecido com um for em qualquer linguagem de programação.

O problema é que o SAM CLI e o CloudFormation são camadas diferentes. Quando você roda sam local invoke ou sam build, o SAM CLI processa o template localmente, sem passar pelo CloudFormation. E até maio de 2026, esse processamento local não sabia o que fazer com o bloco Fn::ForEach.

O erro é totalmente enganoso, parece problema de indentação no YAML, mas na verdade é o SAM CLI não reconhecendo a sintaxe do Language Extensions. Quem já bateu nesse erro e ficou olhando pro template por meia hora sem achar nada errado sabe o quanto isso frustra.

Isso criava um dilema real no dia a dia. Você tinha três caminhos, e nenhum era bom:

Usar Language Extensions e abrir mão do SAM CLI local: deploy direto no CloudFormation para testar. Ciclo lento, custo de iteração alto, debug difícil.
Usar SAM CLI local e abrir mão do DRY: manter os blocos repetidos no template, aceitar o risco de inconsistência entre ambientes e torcer pra ninguém esquecer de replicar uma mudança.
Manter dois templates: um enxuto com Fn::ForEach para o deploy, outro expandido manualmente para uso local. O pior dos mundos, duplicação do template inteiro, sincronização manual entre os dois, confusão garantida na revisão de código.

Eu ficava sempre na opção 2. O template ficava feio, mas pelo menos o sam local invoke funcionava.

O que a AWS fez em maio de 2026 foi processar as Language Extensions em memória, expandindo os loops antes de qualquer operação local. O template original no disco nunca é tocado, o CloudFormation continua recebendo o template com Fn::ForEach intacto e faz a própria expansão no deploy.

O SAM CLI cuida do desenvolvimento local, o CloudFormation cuida do deploy. Sem interferência entre os dois.

3.0 Testando na prática: antes e depois

Vamos usar um cenário com três funções Lambda, uma por ambiente (DEV, HML e PROD). Cada função vai ter o mesmo código base, mas com variáveis de ambiente e configurações diferentes.

3.1 O modo antigo: copy-paste inevitável

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Runtime: python3.13
    MemorySize: 256
    Timeout: 10

Resources:

  DevFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: hello-world-dev
      CodeUri: ./src/dev/
      Handler: handler.lambda_handler
      Description: "Ambiente DEV"
      Environment:
        Variables:
          ENV: dev
          TIER: free
      Tags:
        Environment: dev
        Project: hello-word-old

  HmlFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: demo-old-hml
      CodeUri: ./src/hml/
      Handler: handler.lambda_handler
      Description: "Ambiente hml"
      Environment:
        Variables:
          ENV: hml
          TIER: standard
      Tags:
        Environment: hml
        Project: hello-word-old

  ProdFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: demo-old-prod
      CodeUri: ./src/prod/
      Handler: handler.lambda_handler
      Description: "Ambiente Prod"
      Environment:
        Variables:
          ENV: prod
          TIER: premium
      Tags:
        Environment: prod
        Project: hello-word-old

Outputs:
  AlphaFunctionArn:
    Value: !GetAtt DevFunction.Arn
  hmlFunctionArn:
    Value: !GetAtt HmlFunction.Arn
  ProdFunctionArn:
    Value: !GetAtt ProdFunction.Arn

São três blocos quase idênticos. Se você precisar mudar o runtime de python3.13 para python3.14, precisa alterar em três lugares, ou no Globals, mas só funciona para propriedades suportadas pelo bloco global. Qualquer propriedade que não vai para Globals vira copy-paste obrigatório.

E se precisar adicionar um quarto ambiente (Staging)? Copiar um dos blocos, renomear, ajustar variáveis, criar o src/stg/, adicionar o Output manualmente. São no mínimo seis pontos de toque para uma mudança que deveria ser trivial.

3.2 O modo novo: uma definição, N funções

AWSTemplateFormatVersion: "2010-09-09"

Transform:
  - AWS::LanguageExtensions
  - AWS::Serverless-2016-10-31

Parameters:
  Environments:
    Type: CommaDelimitedList
    Default: "Dev,Hml,Prod"

Globals:
  Function:
    Runtime: python3.13
    MemorySize: 256
    Timeout: 10

Mappings:
  EnvConfig:
    dev:
      Tier: free
      CodeUri: ./src/dev/
    hml:
      Tier: standard
      CodeUri: ./src/hml/
    prod:
      Tier: premium
      CodeUri: ./src/prod/

Resources:
  Fn::ForEach::CreateFunctions:
    - EnvName
    - !Ref Environments
    - ${EnvName}Function:
        Type: AWS::Serverless::Function
        Properties:
          FunctionName:
            Fn::Sub: "hello-world-${EnvName}"
          CodeUri:
            Fn::FindInMap:
              - EnvConfig
              - Ref: EnvName
              - CodeUri
          Handler: handler.lambda_handler
          Description:
            Fn::Sub: "Funcao do ambiente ${EnvName}"
          Environment:
            Variables:
              ENV:
                Ref: EnvName
              TIER:
                Fn::FindInMap:
                  - EnvConfig
                  - Ref: EnvName
                  - Tier
          Tags:
            Environment:
              Ref: EnvName
            Project: hello-word

Outputs:
  Fn::ForEach::FunctionOutputs:
    - EnvName
    - !Ref Environments
    - ${EnvName}FunctionArn:
        Description:
          Fn::Sub: "ARN da funcao ${EnvName}"
        Value:
          Fn::GetAtt:
            - ${EnvName}Function
            - Arn

O Fn::ForEach::CreateFunctions itera sobre [hml, dev, prod] e gera automaticamente DevFunction, HmlFunction e ProdFunction, cada uma com as configurações corretas vindas do Mappings. Os Outputs também são gerados pelo segundo ForEach, sem nenhum bloco manual.

O handler Python é o mesmo para todos os ambientes, todas as diferenças chegam via variáveis de ambiente:

import os
import json

def lambda_handler(event, context):
    env  = os.environ.get("ENV",  "unknown")
    tier = os.environ.get("TIER", "standard")
    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": f"Oi, eu sou o ambiente de {env}!",
            "tier": tier,
            "env": env
        }, indent=2)
    }

4.0 Testando Localmente

4.1 Pré-requisitos

Faça a atualização do seu AWS SAM:

pip install aws-sam-cli --upgrade
sam --version  # 1.161.1 ou superior

4.2 Estrutura de pastas

Vou disponibilizar no final do artigo um link para o repositório do github onde você pode fazer um clone e realizar os testes.

4.3 Testando o modo antigo

Faça a validação do template:

cd modo-antigo/

sam validate --template template-old.yaml

Após terminar, execute o build:

sam build --template template-old.yaml

Agora vamos testar:

sam local invoke DevFunction --no-event
sam local invoke HmlFunction --no-event
sam local invoke ProdFunction --no-event

4.4 Testando o modo novo

Acesse o repositório e valide o template:

cd modo-novo/
# flag --language-extensions obrigatoria em todos os comandos locais
sam validate --template template.yaml --language-extensions

Novamente, vamos fazer o build:

sam build --template template.yaml --language-extensions

E por fim, testar novamente:

# invocar pelo nome expandido pelo ForEach
sam local invoke DevFunction --language-extensions --no-event
sam local invoke HmlFunction --language-extensions --no-event
sam local invoke ProdFunction --language-extensions --no-event

4.5 E se eu precisar adicionar um novo ambiente?

Esse é o momento que deixa o benefício mais concreto. Para adicionar um ambiente Staging no modo novo, são apenas três mudanças:

4.5.1 Atualizar o parâmetro

Parameters:
  Environments:
    Type: CommaDelimitedList
    Default: "Hml,Dev,Prod,Stg"  # adicionar Staging aqui

4.5.2 Adicionar entrada no Mappings

Mappings:
  EnvConfig:
    # ... entradas existentes ...
    Staging:
      Tier: standard
      CodeUri: ./src/stg/

4.5.3 Criar nova pasta e mover código

mkdir src/stg

cp src/hml/handler.py src/stg/handler.py

4.5.4 Conclusão

O Output StgFunctionArn é gerado automaticamente pelo segundo ForEach. Nenhuma outra alteração necessária.

No modo antigo, a mesma operação exigiria: copiar um bloco inteiro de ~15 linhas, renomear em todos os lugares, ajustar as variáveis, criar o diretório e o handler, e adicionar o Output manualmente. São pelo menos seis pontos de toque, cada um com risco de erro.

5.0 Outras funções que vieram junto

Além do Fn::ForEach, o SAM CLI passou a suportar mais funções do Language Extensions:

Fn::Length retorna o número de itens de uma lista. Útil para definir ReservedConcurrentExecutions ou ProvisionedConcurrencyConfig baseado no tamanho dinâmico de uma lista de parâmetros.
Fn::ToJsonString serializa qualquer valor para string JSON. Prático para passar configurações complexas como variável de ambiente em formato JSON sem ter que escrever o JSON manualmente no template.
Fn::FindInMap com DefaultValue permite definir um valor de fallback quando a chave não existe no mapeamento, sem precisar de um bloco Conditions inteiro para cobrir o caso base. Muito útil para templates multi-região onde algumas regiões têm configurações específicas e as demais usam o padrão.
DeletionPolicy e UpdateReplacePolicy condicionais permitem usar !If nessas políticas, algo que antes não era suportado. Por exemplo, deletar automaticamente em ambientes de dev e reter em produção, tudo no mesmo template.

6.0 Pontos de atenção

Algumas coisas que aprendi testando na prática e que o anúncio oficial não deixa claro:

1. A flag --language-extensions é obrigatória em todos os comandos locais. O suporte é opt-in: sem a flag, o SAM CLI ignora o Language Extensions e retorna aquele erro confuso de "All Resources must be Objects", que parece indentação mas não é. Todos os comandos precisam da flag: sam validate, sam build, sam local invoke, sam local start-api e sam sync.

2. A ordem dos transforms importa. AWS::LanguageExtensions deve vir obrigatoriamente antes de AWS::Serverless-2016-10-31 na lista. Invertido não funciona.

# Correto
Transform:
  - AWS::LanguageExtensions
  - AWS::Serverless-2016-10-31

# Errado
Transform:
  - AWS::Serverless-2016-10-31
  - AWS::LanguageExtensions

3. Dentro do Fn::ForEach, use sempre a forma longa das funções. A short-form YAML (!Sub, !FindInMap, !Ref, !GetAtt) não funciona dentro dos blocos do loop. Use a forma explícita: Fn::Sub, Fn::FindInMap, Ref, Fn::GetAtt.

# Errado: short-form dentro do ForEach
CodeUri: !FindInMap [EnvConfig, !Ref EnvName, CodeUri]

# Correto: forma longa
CodeUri:
  Fn::FindInMap:
    - EnvConfig
    - Ref: EnvName
    - CodeUri

4. Sem comentários inline dentro do bloco Fn::ForEach. O parser YAML perde o fio do template com comentários na mesma linha dos valores do loop. Mantenha os comentários fora do bloco ou remova-os.

5. Não compatível com Lambda Managed Instances. Funções geradas pelo Fn::ForEach não podem usar capacity provider. Se o seu projeto usa Lambda Managed Instances, esse recurso ainda não se aplica.

7.0 Conclusão

Esse lançamento fecha um gap que existia há quase três anos: o CloudFormation suportava Fn::ForEach desde julho de 2023, mas o SAM CLI ficou para trás, e as equipes tinham que escolher entre templates DRY e desenvolvimento local rápido.

A solução foi processar o Language Extensions em memória durante operações locais sem tocar no template original. O CloudFormation faz sua própria expansão no deploy. Cada camada faz o seu trabalho.

O único detalhe que o anúncio oficial não deixa explícito é que o suporte é opt-in via flag --language-extensions. Sem ela, você vai continuar levando aquele erro de indentação que não tem nada a ver com indentação. Agora você sabe.

Se quiser testar, os templates de exemplo desse artigo estão disponíveis no repositório linkado abaixo. Qualquer dúvida ou feedback, comenta aqui.

🔗 Repositório com os exemplos: github.com/diegobroetto/sam-language-extensions-demo