Lambda local: rodar e debugar com AWS SAM CLI e VS Code

Rodar uma função Lambda na sua máquina e parar nela com breakpoint, sem subir código para a AWS, dá para fazer com o AWS SAM CLI e o VS Code. A dúvida "como eu rodo e debugo a Lambda local?" aparece cedo para quem começa em serverless, e a resposta tem duas partes: sam local invoke para rodar e uma configuração de debug no launch.json para parar na linha que você quiser.

O que você usa e por que

Lambda executa funções sem você alocar servidor: a AWS cuida disso e cobra por milissegundo de uso. Quem começa costuma criar a primeira função no console e, na hora de testar, surge a dúvida de como fazer isso sem publicar a cada ajuste.

A resposta é o AWS SAM (Serverless Application Model), o framework da AWS para esse trabalho. Você usa duas peças:

• SAM CLI: a linha de comando que cria o projeto e executa a função localmente.
• AWS Toolkit: a extensão da AWS para o VS Code, que adiciona a criação da configuração de debug de uma função Lambda.

O SAM executa a função dentro de um container, por baixo dos panos. É essa parte que deixa a execução local parecida com a da AWS.

1Tenha a função de referência e instale o SAM

Para ter o que comparar, criei antes uma função simples no console da Lambda, com runtime Node.js, que imprime os valores recebidos pelo evento. Testei com o modelo de evento "hello-world" e o console mostrou memória e duração da execução, além dos parâmetros impressos. Vamos ver o mesmo resultado na sua máquina.

Abra uma pasta nova no VS Code e instale o SAM CLI pelo guia da AWS, que tem o processo para Mac, Linux e Windows (link no aviso acima). Eu uso Linux. Depois confirme a instalação:

sam --version

No meu caso, o comando respondeu SAM CLI, version 1.34.1. Se ele responder com uma versão, o SAM está pronto.

2Crie o projeto com um template

Com o SAM instalado, o comando de início cria a sua primeira função a partir de um template:

sam init

Ele faz algumas perguntas. Na aula, as escolhas foram:

• template de origem: AWS Quick Start Templates, em vez de um template customizado;
• tipo de pacote: Zip, em vez de imagem (imagem é para quem trabalha com container);
• runtime: nodejs14.x, que podia ser qualquer outro da lista;
• nome do projeto: sam-app, o padrão;
• template de início rápido: Hello World Example, entre outros disponíveis.

O resultado é a pasta sam-app com:

• events/event.json: um evento de exemplo;
• hello-world/: a função, com app.js e package.json;
• template.yaml: o template que descreve tudo o que o SAM precisa para rodar a função localmente e também para publicá-la na AWS.

No template.yaml, o recurso da função se chama HelloWorldFunction, com o handler app.lambdaHandler e o runtime nodejs14.x. Guarde esse nome: é por ele que você chama a função. Abri a pasta sam-app em uma nova janela do VS Code para trabalhar só nela.

3Coloque o seu código e rode local

Troque o código de exemplo do app.js pelo código da função que você quer testar. Na aula, copiei o do hello-world do console e acrescentei um console.log("Executando funcao local") para provar que era a execução local:

exports.lambdaHandler = async (event, context) => {
  console.log("Executando funcao local");
  console.log("value1 =", event.key1);
  console.log("value2 =", event.key2);
  console.log("value3 =", event.key3);
  return event.key1;
};

Nada foi para a AWS. Para executar, dentro da pasta sam-app, chame a função pelo nome do recurso que está no template:

sam local invoke HelloWorldFunction

O SAM prepara o container e roda a função. A saída mostra Invoking app.lambdaHandler (nodejs14.x), o que a função imprime e o relatório de execução, com duração, memória configurada e memória máxima usada, bem parecido com o do console da AWS. Como não passei nenhum evento, value1, value2 e value3 saíram undefined.

Para passar um evento, a documentação atual usa -e com um arquivo JSON, como o events/event.json do projeto: sam local invoke HelloWorldFunction -e events/event.json.

4Crie a configuração de debug no VS Code

Rodar já ajuda, mas parar dentro do código ajuda mais. Com o AWS Toolkit instalado, o VS Code mostra o atalho AWS: Add Debug Configuration acima do lambdaHandler no app.js (e acima da função no template.yaml). Ao clicar, ele abre a lista "Create a Debug Configuration from a CloudFormation Template" com três opções:

• template.yaml:HelloWorldFunction, a chamada direta da função;
• template.yaml:HelloWorldFunction (API Event: HelloWorld), a chamada por um evento de API (GET /hello);
• No Template, que executa a função isolada, sem referenciar um template.

Escolhi a primeira, a chamada direta. A configuração é gravada no launch.json do VS Code, e o campo que interessa é o payload: ali você informa os dados do evento que a função vai receber. Como o payload é um JSON, sinalizei isso com "json" e escrevi entre chaves os pares que quis:

"invokeTarget": {
  "target": "template",
  "templatePath": "${workspaceFolder}/template.yaml",
  "logicalId": "HelloWorldFunction"
},
"lambda": {
  "payload": {"json": {
    "key1": "valor 1",
    "key2": "valor 2",
    "key3": "valor 3"
  }},
  "environmentVariables": {}
}

As três chaves são as que a função lê (key1, key2, key3). Use no payload as chaves que a sua função espera.

5Coloque um breakpoint e execute

Com o launch.json configurado, vá à aba de debug, marque um breakpoint na primeira linha da função (console.log("Executando funcao local")) e mande executar. O SAM inicia a execução local e o debugger anexa ("Debugger attached").

Ele para primeiro no início, antes do seu código. Aperte F5 e a execução chega ao breakpoint dentro da lambdaHandler. Abra o event no painel de variáveis ou no Watch: estão lá key1: 'valor 1', key2: 'valor 2' e key3: 'valor 3', exatamente o que está no payload.

Mande continuar a execução e abra o Debug Console: lá aparecem os dados impressos pela função, value1 = valor 1, value2 = valor 2 e value3 = valor 3, mais o relatório de execução, como se a função rodasse na AWS, só que no seu escopo local.

Checklist

• Instale o SAM CLI pelo guia atual da AWS e confirme com sam --version.
• Crie o projeto com sam init e escolha o template, o pacote Zip e o runtime que você usa.
• Coloque o código da sua função no app.js do projeto criado pelo SAM.
• Rode a função com sam local invoke pelo nome do recurso do template.yaml.
• Instale o AWS Toolkit no VS Code e crie a configuração de debug com AWS: Add Debug Configuration.
• Preencha o payload do launch.json com o evento que a sua função espera.
• Marque um breakpoint, execute, aperte F5 e confira no Watch se o evento chegou como você definiu.

Rodar e debugar a Lambda na sua máquina encurta o ciclo entre escrever e descobrir o erro. Se você quer aprender serverless e o resto da AWS na prática, do zero ao uso em produção, esse é o tipo de assunto que trabalhamos na Formação AWS.