Erros da função do AWS Lambda em Java

Quando o código gera um erro, o Lambda gera uma representação JSON do erro. Esse documento de erro aparece no log de invocação e, para invocações síncronas, na saída.

Esta página descreve como exibir erros de invocação de função do Lambda para o runtime do Java usando o console do Lambda e a AWS CLI.

Sintaxe

No exemplo a seguir, o runtime não consegue desserializar o evento em um objeto. A entrada é um tipo JSON válido, mas não corresponde ao tipo esperado pelo método do manipulador.

exemplo Erro de runtime do Lambda

{
  "errorMessage": "An error occurred during JSON parsing",
  "errorType": "java.lang.RuntimeException",
  "stackTrace": [],
  "cause": {
    "errorMessage": "com.fasterxml.jackson.databind.exc.InvalidFormatException: Can not construct instance of java.lang.Integer from String value '1000,10': not a valid Integer value\n at [Source: lambdainternal.util.NativeMemoryAsInputStream@35fc6dc4; line: 1, column: 1] (through reference chain: java.lang.Object[0])",
    "errorType": "java.io.UncheckedIOException",
    "stackTrace": [],
    "cause": {
      "errorMessage": "Can not construct instance of java.lang.Integer from String value '1000,10': not a valid Integer value\n at [Source: lambdainternal.util.NativeMemoryAsInputStream@35fc6dc4; line: 1, column: 1] (through reference chain: java.lang.Object[0])",
      "errorType": "com.fasterxml.jackson.databind.exc.InvalidFormatException",
      "stackTrace": [
        "com.fasterxml.jackson.databind.exc.InvalidFormatException.from(InvalidFormatException.java:55)",
        "com.fasterxml.jackson.databind.DeserializationContext.weirdStringException(DeserializationContext.java:907)",
        ...
      ]
    }
  }
}

Como funciona

Ao invocar uma função do Lambda, o Lambda recebe a solicitação de invocação e valida as permissões de sua função de execução, verifica se o documento do evento é um documento JSON válido e verifica valores de parâmetros.

Se a solicitação for validada, o Lambda a envia para uma instância da função. O ambiente de runtime do Lambda converte o documento do evento em um objeto e o transmite ao handler da função.

Se o Lambda encontra um erro, ele retorna um tipo de exceção, uma mensagem e o código HTTP do status que indica a causa do erro. O cliente ou o serviço que invocou a função do Lambda pode processar o erro de maneira programática ou transmiti-lo a um usuário final. O comportamento correto de tratamento de erros depende do tipo de aplicativo, do público e da origem do erro.

A lista a seguir descreve o intervalo de códigos de status que você pode receber do Lambda.

2xx

Um erro da série 2xx com um cabeçalho X-Amz-Function-Error na resposta indica um erro de runtime ou de função do Lambda. Um código de status da série 2xx indica que o Lambda aceitou a solicitação, mas em vez de um código de erro, o Lambda indica o erro incluindo o cabeçalho X-Amz-Function-Error na resposta.

4xx

Um erro da série 4xx indica um erro que o cliente ou serviço que fez a invocação pode corrigir modificando a solicitação, solicitando permissão ou tentando a solicitação novamente. Os erros da série 4xx diferentes de 429 geralmente indicam um erro na solicitação.

5xx

Um erro da série 5xx indica um problema com o Lambda ou com a configuração/recursos da função. Os erros da série 5xx podem indicar uma condição temporária que pode ser resolvida sem nenhuma ação do usuário. O cliente ou serviço que fez a invocação não podem solucionar esses problemas, mas o proprietário de uma função do Lambda pode ser capaz de corrigi-los.

Para obter uma lista completa dos erros de invocação, consulte InvokeFunction erros.

Criar uma função que retorna exceções

Você pode criar uma função do Lambda que exiba mensagens de erro legíveis para os usuários.

nota

Para testar esse código, você precisa incluir InputLengthException.java na pasta src do seu projeto.

exemplo src/main/java/example/ .java HandlerDivide — Exceção de tempo de execução

import java.util.List;

  // Handler value: example.HandlerDivide
  public class HandlerDivide implements RequestHandler<List<Integer>, Integer>{
    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    @Override
    public Integer handleRequest(List<Integer> event, Context context)
    {
      LambdaLogger logger = context.getLogger();
      // process event
      if ( event.size() != 2 )
      {
        throw new InputLengthException("Input must be a list that contains 2 numbers.");
      }
      int numerator = event.get(0);
      int denominator = event.get(1);
      logger.log("EVENT: " + gson.toJson(event));
      logger.log("EVENT TYPE: " + event.getClass().toString());
      return numerator/denominator;
    }
  }

Quando a função gera InputLengthException, o runtime Java serializa-o no documento a seguir.

exemplo documento de erro (espaço em branco adicionado)

{
    "errorMessage":"Input must be a list that contains 2 numbers.",
    "errorType":"java.lang.InputLengthException",
    "stackTrace": [
      "example.HandlerDivide.handleRequest(HandlerDivide.java:23)",
      "example.HandlerDivide.handleRequest(HandlerDivide.java:14)"
    ]
  }

Neste exemplo, InputLengthExceptioné umRuntimeException. A RequestHandler interface não permite exceções verificadas. A interface RequestStreamHandler oferece suporte à geração de erros IOException.

A instrução de retorno no exemplo anterior também pode gerar uma exceção de runtime.

    return numerator/denominator;

Este código pode retornar um erro aritmético.

{"errorMessage":"/ by zero","errorType":"java.lang.ArithmeticException","stackTrace":["example.HandlerDivide.handleRequest(HandlerDivide.java:28)","example.HandlerDivide.handleRequest(HandlerDivide.java:13)"]}

Usar o console do Lambda

Você pode invocar sua função no console do Lambda configurando um evento de teste e visualizando a saída. A saída é capturada pelos logs de execução da função e, quando o rastreamento ativo está habilitado, pelo AWS X-Ray.

Para invocar uma função no console do Lambda

1. Abra a página Funções do console do Lambda.

2. Escolha a função a ser testada e escolhaTeste.

3. UnderEvento de teste, selecioneNovo evento.

4. Selecione um Template (Modelo).

5. Em Name (Nome), insira um nome para o teste. Na caixa de entrada de texto, insira o evento de teste JSON.

6. Escolha Salvar alterações.

7. Escolha Testar.

O console do Lambda invoca sua função de forma síncrona e exibe o resultado. Para ver a resposta, os logs e outras informações, expanda a seção Details (Detalhes).

Usar a AWS Command Line Interface (AWS CLI)

O AWS CLI é uma ferramenta de código aberto que permite interagir com os serviços do AWS usando comandos no shell da linha de comando. Para executar as etapas desta seção, você deve ter o seguinte:

• AWS Command Line Interface (AWS CLI) versão 2

• AWS CLI – Configuração rápida com aws configure

Quando você invoca uma função do Lambda na AWS CLI, a AWS CLI divide a resposta em dois documentos. A resposta da AWS CLI é exibida no prompt de comando. Se ocorreu um erro, a resposta contem um campo FunctionError. A resposta ou o erro de invocação retornado pela função é gravado no arquivo de saída. Por exemplo, o output.json ou o output.txt.

O exemplo de comando invoke a seguir demonstra como invocar uma função e escrever a resposta de invocação em um arquivo output.txt.

aws lambda invoke   \
  --function-name my-function   \
      --cli-binary-format raw-in-base64-out  \
          --payload '{"key1": "value1", "key2": "value2", "key3": "value3"}' output.txt

A opção cli-binary-format será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute aws configure set cli-binary-format raw-in-base64-out. Para obter mais informações, consulte A AWS CLI comporta opções de linha de comando globais no Guia do usuário da AWS Command Line Interface versão 2.

Você deve ver a resposta da AWS CLI em seu prompt de comando:

{
    "StatusCode": 200,
    "FunctionError": "Unhandled",
    "ExecutedVersion": "$LATEST"
}

Você deve ver a resposta de invocação de função no arquivo output.txt. Também é possível visualizar a saída no mesmo prompt de comando usando:

cat output.txt

Você deve ver a resposta de invocação no prompt de comando.

{"errorMessage":"Input must contain 2 numbers.","errorType":"java.lang.InputLengthException","stackTrace": ["example.HandlerDivide.handleRequest(HandlerDivide.java:23)","example.HandlerDivide.handleRequest(HandlerDivide.java:14)"]}

O Lambda também grava até 256 KB do objeto de erro nos logs de função. Para ter mais informações, consulte Registro em log da função do AWS Lambda em Java.

Tratamento de erros em outros serviços da AWS

Quando outro serviço da AWS invoca sua função, o serviço escolhe o tipo de invocação e o comportamento de repetição. Os serviços da AWS podem invocar sua função em um agendamento, em resposta a um evento de ciclo de vida em um recurso ou para atender a uma solicitação de um usuário. Alguns serviços invocam funções de forma assíncrona e permitem que o Lambda trate erros, enquanto outros fazem novas tentativas ou transmitem os erros de volta ao usuário.

Por exemplo, o API Gateway trata todos os erros de invocação e função como erros internos. Se a API do Lambda rejeitar a solicitação de invocação, o API Gateway retornará um código de erro 500. Se a função é executada, mas retorna um erro ou retorna uma resposta no formato errado, o API Gateway retorna um código de erro 502. Para personalizar a resposta de erro, é necessário detectar erros no código e formatar uma resposta no formato necessário.

Recomendamos usar AWS X-Ray para determinar a fonte de um erro e a respectiva causa. O X-Ray permite localizar qual componente encontrou um erro e ver detalhes sobre os erros. O exemplo a seguir mostra um erro de função que resultou em uma resposta 502 do API Gateway.

Para ter mais informações, consulte Instrumentação do código Java no AWS Lambda.

Aplicações de exemplo

O GitHub repositório deste guia inclui exemplos de aplicativos que demonstram o uso dos erros. Cada aplicativo de exemplo inclui scripts para fácil implantação e limpeza, um modelo do AWS Serverless Application Model (AWS SAM) e recursos de suporte.

Aplicações de exemplo do Lambda em Java

• java17-examples: uma função em Java que demonstra como usar um registro Java para representar um objeto de dados de evento de entrada.

• java-basic: uma coleção de funções Java mínimas com testes de unidade e configuração de registro em log variável.

• java-events: uma coleção de funções do Java contendo código básico sobre como lidar com eventos de vários serviços, como o Amazon API Gateway, o Amazon SQS e o Amazon Kinesis. Essas funções usam a versão mais recente da aws-lambda-java-eventsbiblioteca (3.0.0 e mais recente). Estes exemplos não exigem oAWS SDK como dependência.

• s3-java: uma função em Java que processa eventos de notificação do Amazon S3 e usa a Java Class Library (JCL) para criar miniaturas de arquivos de imagem enviados por upload.

• Use API Gateway to invoke a Lambda function (Usar o API Gateway para invocar uma função do Lambda): uma função Java que verifica uma tabela do Amazon DynamoDB contendo informações de funcionários. Em seguida, usa o Amazon Simple Notification Service para enviar uma mensagem de texto aos funcionários comemorando seus aniversários de empresa. Este exemplo usa o API Gateway para invocar a função.

A função java-basic inclui um manipulador (HandlerDivide) que retorna uma exceção de runtime personalizada. O manipulador HandlerStream implementa o RequestStreamHandler e pode gerar uma exceção IOException marcada.

Próximas etapas

• Saiba como mostrar eventos de registro em log para sua função do Lambda na página Registro em log da função do AWS Lambda em Java.