Erros da função do AWS Lambda em Java - AWS Lambda

Erros da função do AWS Lambda em Java

Quando sua função gera um erro, o Lambda retorna detalhes sobre o erro para o invocador. O corpo da resposta que o Lambda retorna contém um documento JSON com o nome do erro, o tipo de erro e uma matriz de estruturas de pilha. O cliente ou o serviço que invocou a função pode tratar o erro ou transmiti-lo a um usuário final. É possível usar exceções personalizadas para retornar informações úteis aos usuários em relação a erros de cliente.

exemplo src/main/java/example/HandlerDivide.java – 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 an array 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 tempo de execução Java serializa-o no documento a seguir.

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

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

Neste exemplo, InputLengthException é uma RuntimeException. 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 tempo de execução.

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)"]}

Visualizar saída de erro

É possível invocar sua função com uma carga útil de teste e visualizar a saída de erro no console do Lambda, na linha de comando ou com o AWS SDK. A saída de erro também é capturada nos logs de execução da função e quando o rastreamento está habilitado no AWS X-Ray.

Para visualizar a saída de erro no console do Lambda, invoque-a com um evento de teste.

Como invocar uma função no console do Lambda

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

  2. Escolha uma função.

  3. Escolha Configure test events (Configurar eventos de teste) no menu suspenso ao lado do botão Test (Teste).

    
            Configuração de um evento de teste no console do Lambda.
  4. Escolha um Event template (Modelo de evento) que corresponda aos eventos que sua função processa.

  5. Insira um nome para o evento de teste e modifique a estrutura do evento conforme necessário.

  6. Escolha Create (Criar).

  7. Escolha Test (Teste).

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).

Quando você invoca a função a partir da linha de comando, a AWS CLI divide a resposta em dois documentos. Para indicar que ocorreu um erro de função, a resposta exibida no terminal inclui um campo FunctionError. A resposta ou o erro retornado pela função é gravado no arquivo de saída.

$ aws lambda invoke --function-name my-function out.json { "StatusCode": 200, "FunctionError": "Unhandled", "ExecutedVersion": "$LATEST" }

Visualize o arquivo de saída para ver o documento de erro.

$ cat out.json {"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 visualizar logs quando você invoca a função na linha de comando, use a opção --log-type e decodifique a string base64 na resposta.

$ aws lambda invoke --function-name my-function --payload "[100,0]" out.json --log-type Tail \ --query 'LogResult' --output text | base64 -d START RequestId: 081f7522-xmpl-48e2-8f67-96686904bb4f Version: $LATEST EVENT: [ 100, 0 ]EVENT TYPE: class java.util.ArrayList/ by zero: java.lang.ArithmeticException java.lang.ArithmeticException: / by zero at example.HandlerDivide.handleRequest(HandlerDivide.java:28) at example.HandlerDivide.handleRequest(HandlerDivide.java:13) END RequestId: 081f7522-xmpl-48e2-8f67-96686904bb4f REPORT RequestId: 081f7522-xmpl-48e2-8f67-96686904bb4f Duration: 4.20 ms Billed Duration: 100 ms Memory Size: 512 MB Max Memory Used: 95 MB XRAY TraceId: 1-5e73162b-1919xmpl2592f4549e1c39be SegmentId: 3dadxmpl48126cb8 Sampled: true

Para obter mais informações sobre logs, consulte Registro em log da função do AWS Lambda em Java.

Noções básicas sobre tipos e fontes de erro

Quando você invoca uma função, vários subsistemas processam a solicitação, o evento, a saída e a resposta. Os erros podem vir do serviço do Lambda (erros de invocação) ou de uma instância da sua função. Os erros de função incluem exceções retornadas pelo código do manipulador e exceções retornadas pelo tempo de execução do Lambda.

O serviço do Lambda recebe a solicitação de invocação e a valida. Ele verifica as permissões, se o documento de evento é um documento JSON válido e os valores de parâmetro. Se o serviço do Lambda encontrar um erro, ele retornará o tipo de exceção, uma mensagem e um código de status HTTP que indicam a causa do erro.

nota

Para obter uma lista completa de erros que a operação da API Invoke pode retornar, consulte Erros de invocação na referência da API do Lambda.

Um erro de série 4xx do serviço do Lambda indica um erro que o invocador pode corrigir modificando a solicitação, solicitando permissão ou tentando novamente. Um erro de série 5xx indica um problema com o serviço do Lambda ou um problema com a configuração ou os recursos da função. Esses problemas não podem ser resolvidos pelo invocador, mas o proprietário da função pode ser capaz de corrigi-los.

Se uma solicitação passar na validação, o Lambda a enviará para uma instância da função. O tempo de execução converte o documento do evento em um objeto e o transmite ao código do manipulador. Erros podem ocorrer durante esse processo se, por exemplo, o nome do método do manipulador não corresponder à configuração da função ou se a invocação atingir o tempo limite antes do código do manipulador retornar uma resposta. Os erros de tempo de execução do Lambda são formatados como erros que seu código retorna, mas são retornados pelo tempo de execução.

No exemplo a seguir, o tempo de execução 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 tempo de execução 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)", ... ] } } }

Para erros de tempo de execução do Lambda e outros erros de função, o serviço do Lambda não retorna um código de erro. Um código de status de série 2xx indica que o serviço do Lambda aceitou a solicitação. Em vez de um código de erro, o Lambda indica o erro incluindo o cabeçalho X-Amz-Function-Error na resposta.

Para invocação assíncrona, os eventos são colocados em fila antes de o Lambda enviá-los para sua função. Para solicitações válidas, o Lambda retorna uma resposta bem-sucedida imediatamente e adiciona o evento à fila. O Lambda lê os eventos da fila e invoca a função. Se ocorrer um erro, o Lambda tentará novamente com um comportamento que varia dependendo do tipo de erro. Para obter mais informações, consulte Invocação assíncrona.

Tratamento de erros em clientes

Os clientes que invocam funções do Lambda podem optar por tratar os erros ou transmiti-los ao usuário final. O comportamento correto de tratamento de erros depende do tipo de aplicativo, do público e da origem do erro. Por exemplo, se uma invocação falhar com um código de erro 429 (muitas solicitações), a CLI da AWS tentará novamente até 4 vezes antes de mostrar um erro ao usuário.

$ aws lambda invoke --function-name my-function out.json An error occurred (TooManyRequestsException) when calling the Invoke operation (reached max retries: 4): Rate Exceeded.

Para outros erros de invocação, o comportamento correto depende do código de resposta. Os erros de série 5xx podem indicar uma condição temporária que pode ser resolvida sem qualquer ação do usuário. Uma nova tentativa pode ou não ter êxito. Os erros de série 4xx que não sejam 429 geralmente indicam um erro com a solicitação. Não é provável que uma nova tentativa seja bem-sucedida.

Para erros de função, o cliente pode processar o documento de erro e mostrar a mensagem de erro em um formato simples. Um aplicativo baseado em navegador pode mostrar a mensagem de erro e o tipo, mas omitir o rastreamento de pilha. A CLI da AWS salva o objeto de erro no arquivo de saída e exibe um documento gerado a partir dos cabeçalhos de resposta.

$ aws lambda invoke --function-name my-function --payload '[1000]' out.json { "StatusCode": 200, "FunctionError": "Unhandled", "ExecutedVersion": "$LATEST" }

exemplo out.json

{"errorMessage":"Input must be an array that contains 2 numbers.","errorType":"example.InputLengthException","stackTrace":["example.HandlerDivide.handleRequest(HandlerDivide.java:22)","example.HandlerDivide.handleRequest(HandlerDivide.java:13)"]}

Tratamento de erros em outros serviços da AWS

Quando um serviço da AWS invoca sua função, o serviço escolhe o tipo de chamada e o comportamento de repetição. Os serviços da AWS podem invocar sua função em uma programação, 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.

Para determinar a origem de um erro e sua causa, use o AWS X-Ray. Com o X-Ray, é possível descobrir qual componente encontrou um erro e ver detalhes sobre exceções. O exemplo a seguir mostra um erro de função que resultou em uma resposta 502 do API Gateway.


        Mapa de rastreamento para um erro de função com o API Gateway.

Comece com o X-Ray habilitando o rastreamento ativo em suas funções.

Para obter detalhes sobre outros erros do manipulador de serviços, consulte os tópicos no capítulo Usar o AWS Lambda com outros serviços.

Tratamento de erros em aplicativos de exemplo

O repositório do GitHub para este guia inclui aplicativos de exemplo que demonstram o uso dos erros. Cada aplicativo de exemplo inclui scripts para fácil implantação e limpeza, um modelo do Modelo de aplicativo sem servidor da AWS (AWS SAM) e recursos de suporte.

Aplicativos de exemplo do Lambda em Java

  • blank-java – uma função Java que mostra o uso das bibliotecas Java do Lambda, registro em log, variáveis de ambiente, camadas, rastreamento do AWS X-Ray, testes de unidade e do AWS SDK.

  • java-basic – uma função Java mínima com testes de unidade e configuração de registro em log variável.

  • java-events – uma função Java mínima que usa a biblioteca aws-lambda-java-events com tipos de evento que não exigem o AWS SDK como dependência, como o Amazon API Gateway.

  • java-events-v1sdk – uma função Java que usa a biblioteca aws-lambda-java-events com tipos de evento que exigem o AWS SDK como dependência (Amazon Simple Storage Service, Amazon DynamoDB e Amazon Kinesis).

  • s3-java – uma função 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.

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