Observabilidade Lambda AWS: guia em 5 passos

Observabilidade em funções Lambda AWS é o que separa um ambiente que "funciona" de um que você consegue diagnosticar quando algo falha. O objetivo deste guia é sair do básico, que é só olhar o CloudWatch quando dá erro, para uma configuração que responda a pergunta: qual decisão esse número me permite tomar? Você vai precisar de uma função Lambda existente, permissão para criar roles IAM e acesso ao console da AWS. Nada de ferramentas externas, apenas os serviços nativos.

Passo 1: Estruture seus logs em JSON

O primeiro passo é mudar a forma como sua função escreve logs. Em vez de texto livre, use JSON estruturado. Isso permite filtrar por campo, correlacionar requisições e criar alertas precisos. Inclua um requestId, o nome da função e o nível de severidade. Um erro comum é esquecer de capturar o context da Lambda, que contém o request ID que o X-Ray usa depois.

Dica: use o logger da própria AWS (powertools) ou uma lib de logging que serialize JSON. Teste localmente antes de subir.

Passo 2: Crie métricas customizadas com dimensões

O CloudWatch já entrega métricas padrão (invocações, erros, duração). Mas elas não contam a história do seu negócio. Crie métricas customizadas para o que importa: número de itens processados, tempo de integração com um banco, taxa de falha de uma dependência específica. Use dimensões, como nome da função e ambiente, para segmentar.

Erro comum: publicar métrica em toda execução, o que custa caro. Agregue em lote ou publique apenas para eventos relevantes.

Passo 3: Ative o AWS X-Ray para tracing distribuído

Lambda faz parte de um fluxo maior. Ative o X-Ray na função e use o SDK para capturar segmentos para cada chamada downstream (DynamoDB, SQS, HTTP). Assim, quando uma requisição demora, você vê exatamente onde o tempo foi gasto. Sem isso, você só vê o sintoma, não a causa.

Dica: habilite o tracing na configuração da função e adicione o pacote aws-xray-sdk no seu código. Não esqueça de dar permissão na role IAM para escrever no X-Ray.

Passo 4: Configure alarmes em percentis, não em médias

Média de duração esconde picos. Configure alarmes no CloudWatch com base em percentis (p95, p99) de duração e taxa de erro. Um alarme em p95 dispara quando 5% das execuções estão lentas, o que indica degradação antes de virar falha generalizada.

Erro comum: alarme em média que fica mudo até tudo cair. Use estatística de percentil e período de 1 minuto para Lambda.

Passo 5: Crie um dashboard que responda a uma pergunta

Dashboard não é para enfeitar. Monte um que responda: "minha função está saudável agora?" Inclua invocações, erros, duração p95 e alarmes ativos. Se o dashboard não permite tomar uma decisão, ele é só ruído. Um contraexemplo: gráfico de invocações sem contexto de erro não ajuda ninguém.

Dica: use o CloudWatch Dashboards com uma linha por ambiente (dev, prod) para comparação rápida.

Checklist do que foi feito

Você configurou logs JSON estruturados, criou métricas customizadas com dimensões, ativou o X-Ray, definiu alarmes em percentis e montou um dashboard de decisão. Antes de encerrar, revise: cada métrica e alarme está ligado a uma ação concreta? Se não, remova ou ajuste.

FAQ

Qual a diferença entre monitoramento e observabilidade em Lambda?

Monitoramento diz se algo está fora do limite (ex.: taxa de erro > 1%). Observabilidade permite descobrir por que está fora, correlacionando logs, métricas e traces. Em Lambda, monitoramento é o CloudWatch básico; observabilidade exige logs estruturados e X-Ray.

Preciso de uma ferramenta externa (Datadog, New Relic) para observabilidade?

Não. CloudWatch, X-Ray e Logs Insights resolvem a maioria dos casos. Ferramentas externas agregam valor quando você tem múltiplas contas ou precisa de correlação com infraestrutura não-AWS, mas começam a custar caro em volume alto.

Como lidar com cold starts na observabilidade?

Métricas padrão não separam cold start de execução normal. Crie uma métrica customizada que capture o tempo de inicialização (via log ou contexto) e alerte se p95 de cold start passar de um limite (ex.: 800 ms). Isso ajuda a decidir se você precisa de provisioned concurrency.

O que é Logs Insights e como usar?

É uma ferramenta do CloudWatch para consultar logs com SQL-like. Útil para filtrar erros por requestId ou agrupar por mensagem. Exemplo: filter @message like /ERROR/ | stats count(*) by @timestamp. Sem logs estruturados, as consultas perdem precisão.

Como testar se minha observabilidade está funcionando?

Force um erro (ex.: divida por zero ou chame um endpoint inválido) e veja se o log JSON aparece, a métrica de erro incrementa e o alarme dispara. Depois, use o X-Ray para ver o trace da execução. Se qualquer elo falhar, revise a configuração.