Capturar registros de invocações assíncronas do Lambda

O Lambda pode enviar os registros de invocações assíncronas a um dos Serviços da AWS a seguir.

• Amazon SQS— Uma fila SQS padrão.

• Amazon SNS: um padrão do tópico SNS.

• AWS Lambda: uma função do Lambda.

• Amazon EventBridge: u barramento de eventos do EventBridge.

O registro de invocação contém detalhes sobre a solicitação e a resposta no formato JSON. É possível configurar destinos separados para eventos que são processados com êxito e eventos em que há falha no processamento de todas as tentativas. Como alternativa, é possível configurar uma fila padrão do Amazon SQS ou um tópico padrão do Amazon SNS como uma fila de mensagens não entregues para os eventos descartados. Para filas de mensagens mortas, o Lambda envia somente o conteúdo do evento, sem detalhes sobre a resposta.

Se o Lambda não conseguir enviar um registro para um destino que você configurou, ele enviará uma métrica DestinationDeliveryFailures para o Amazon CloudWatch. Isso poderá acontecer se sua configuração incluir um tipo de destino incompatível, como uma fila do Amazon SQS FIFO ou um tópico do Amazon SNS FIFO. Os erros de entrega também podem ocorrer devido a erros de permissão e limites de tamanho. Para obter mais informações sobre as métricas de invocação do Lambda, consulte Métricas de invocação.

nota

Para evitar que uma função seja acionada, você pode definir a simultaneidade reservada da função como zero. Quando você define a simultaneidade reservada como zero para uma função invocada de forma assíncrona, o Lambda começa a enviar novos eventos para a fila de mensagens não entregues configurada ou para o destino do evento em caso de falha, sem novas tentativas. Para processar eventos que foram enviados enquanto a simultaneidade reservada estava definida como zero, você precisa consumir os eventos da fila de mensagens não entregues ou do destino do evento em caso de falha.

Configurar destinos para invocação assíncrona

Para reter registros de invocações assíncronas, adicione um destino à função. Você pode optar por enviar invocações com êxito ou com falha para um destino. Cada função pode ter vários destinos para que você possa configurar destinos separados para eventos com êxito e com falha. Cada registro enviado ao destino é um documento JSON com detalhes sobre a invocação. Da mesma forma que as configurações de tratamento de erros, é possível configurar destinos em uma função, em uma versão de função ou em um alias.

nota

Você também pode reter registros de invocações com falha para os seguintes tipos de mapeamento de origem de eventos: Amazon Kinesis, Amazon DynamoDB, Apache Kafka autogerenciado e Amazon MSK.

A tabela a seguir lista os destinos aceitos para registros de invocação assíncrona. Para que o Lambda envie registros com êxito ao destino escolhido, certifique-se de que o perfil de execução da função também contenha as permissões relevantes. A tabela também descreve como cada tipo de destino recebe o registro de invocação JSON.

Tipos de destino	Permissão obrigatória	Formato JSON específico para o destino
Fila do Amazon SQS	sqs:SendMessage	O Lambda passa o registro de invocação como Message para o destino.
Tópico do Amazon SNS	sns:Publish	O Lambda passa o registro de invocação como Message para o destino.
Função do Lambda	InvokeFunction	O Lambda passa o registro de invocação como a carga útil para a função.
EventBridge	events:PutEvents	O Lambda passa o registro de invocação como detail na chamada PutEvents. O valor para o campo do evento source é lambda. O valor para o campo de evento detail-type é “Lambda Function Invocation Result - Success” ou “Lambda Function Invocation Result - Failure”. O campo do evento resource contém nomes do recurso da Amazon (ARN) da função e do destino. Para outros campos de eventos, consulte os eventos do Amazon EventBridge.

O exemplo a seguir mostra um registro de invocação para um evento que teve três falhas de tentativa de processamento devido a um erro de função. O registro de invocação contém detalhes sobre o evento, a resposta e o motivo pelo qual o registro foi enviado.

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

As etapas a seguir descrevem como configurar um destino para uma função usando o console do Lambda.

Configurar um destino para registros de invocação assíncrona

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

2. Escolha uma função.

3. Em Function overview (Visão geral da função), escolha Add destination (Adicionar destino).

4. Em Source (Origem), escolha Asynchronous invocation (Invocação assíncrona).

5. Em Condition (Condição), escolha uma das seguintes opções:

   • On failure (Em caso de falha): envie um registro quando o evento falhar em todas as tentativas de processamento ou exceder a idade máxima.

   • On success (Em caso de êxito): envie um registro quando a função processa com êxito uma invocação assíncrona.

6. Em Destination type (Tipo de destino), escolha o tipo de recurso que recebe o registro da invocação.

7. Em Destination (Destino), escolha um recurso.

8. Escolha Salvar.

Quando uma invocação corresponde à condição, o Lambda envia um documento JSON com detalhes sobre a invocação para o destino.

Formato JSON específico para o destino

• No Amazon SQS e no Amazon SNS (SnsDestination e SqsDestination), o registro de invocação é passado como Message para o destino.

• No Lambda (LambdaDestination), o registro de invocação é passado como carga útil para a função.

• No EventBridge (EventBridgeDestination), o registro de invocação é passado como detailna chamada PutEvents. O valor para o campo do evento source é lambda. O valor para o campo de evento detail-type é Lambda Function Invocation Result – Success (Resultado da invocação da função Lambda: sucesso) ou Lambda Function Invocation Result – Failure (Resultado da invocação da função Lambda: falha). O campo do evento resource contém nomes do recurso da Amazon (ARN) da função e do destino. Para outros campos de eventos, consulte os eventos do Amazon EventBridge.

O exemplo a seguir mostra um registro de invocação para um evento que teve três falhas de tentativa de processamento devido a um erro de função.

exemplo registro de invocação

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

O registro de invocação contém detalhes sobre o evento, a resposta e o motivo pelo qual o registro foi enviado.

Rastreamento de solicitações até destinos

Você pode usar o AWS X-Ray para exibir uma visualização conectada de cada solicitação à medida que ela é adicionada à fila, processada por uma função do Lambda e passada para o serviço de destino. Quando você ativa o rastreamento com X-Ray para uma função ou um serviço que invoca uma função, o Lambda adiciona um cabeçalho X-Ray à solicitação e passa o cabeçalho para o serviço de destino. Os rastreamentos dos serviços de upstream são vinculados automaticamente aos rastreamentos de funções do Lambda e serviços de downstream, o que cria uma visão completa de toda a aplicação. Para obter mais informações sobre rastreamento, consulte Visualizar as invocações da função do Lambda usando o AWS X-Ray.

Filas de mensagens mortas

Como alternativa a um destino em caso de falha, é possível configurar a função com uma fila de mensagens mortas para salvar eventos descartados para processamento adicional. Uma fila de mensagens mortas age da mesma forma que um destino em caso de falha na medida em que é usado quando há falha em todas as tentativas de processamento de um evento ou ele expira sem ser processado. No entanto, uma fila de mensagens mortas faz parte da configuração específica da versão de uma função, portanto ela é bloqueada quando você publica uma versão. Destinos em caso de falha também oferecem suporte a destinos adicionais e incluem detalhes sobre a resposta da função no registro de invocação.

Para reprocessar eventos em uma fila de mensagens mortas, você pode defini-la como uma fonte do evento para a função do Lambda. Você também pode recuperar os eventos manualmente.

É possível escolher uma fila padrão do Amazon SQS ou um tópico padrão do Amazon SNS para a sua fila de mensagens não entregues. As filas FIFO e os tópicos do Amazon SNS FIFO são incompatíveis. Se você não tiver uma fila ou um tópico, crie um. Escolha o tipo de destino que corresponde ao seu caso de uso.

• Fila do Amazon SQS: uma fila suspende os eventos falhos até serem recuperados. Escolha uma fila padrão do Amazon SQS caso espere que uma única entidade, como uma função do Lambda ou um alarme do CloudWatch, processe o evento que falhou. Para ter mais informações, consulte Usar o Lambda com o Amazon SQS.

  Crie uma fila no console do Amazon SQS.

• Tópico do Amazon SNS: um tópico retransmite os eventos com falha para um ou mais destinos. Escolha um tópico padrão do Amazon SNS caso espere que várias entidades atuem em um evento com falha. Por exemplo, você pode configurar um tópico para enviar eventos a um endereço de email, uma função do Lambda e/ou um endpoint HTTP. Para ter mais informações, consulte Invocar funções do Lambda com notificações do Amazon SNS.

  Crie um tópico do SNS usando o console do Amazon SNS.

Sua função precisa de permissões adicionais para enviar eventos a uma fila ou um tópico. Adicione uma política com as permissões necessárias à função de execução de sua função.

• Amazon SQS – sqs:SendMessage

• Amazon SNS – sns:Publish

Se a fila ou o tópico de destino for criptografado com uma chave gerenciada pelo cliente, a função de execução também deverá ser um usuário na política baseada em recursos da chave.

Depois de criar o destino e atualizar a função de execução de sua função, adicione a fila de mensagens mortas à função. Você pode configurar várias funções para enviarem eventos ao mesmo destino.

Como configurar uma fila de mensagens mortas

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

2. Escolha uma função.

3. Escolha Configuration (Configuração) e, em seguida, Asynchronous invocation (Invocação assíncrona).

4. Em Asynchronous invocation (Invocação assíncrona), escolha Edit (Editar).

5. Definarecurso DLQ para Amazon SQS ou Amazon SNS.

6. Escolha a fila ou o tópico de destino.

7. Escolha Salvar.

Para configurar uma fila de mensagens mortas com o AWS CLI, use o comando update-function-configuration.

aws lambda update-function-configuration --function-name my-function \
--dead-letter-config TargetArn=arn:aws:sns:us-east-2:123456789012:my-topic

O Lambda envia o evento para a fila de mensagens mortas no mesmo estado, mais informações adicionais nos atributos. Você pode usar essas informações para identificar o erro retornado pela função, ou correlacionar o evento com logs ou um rastreamento do AWS X-Ray.

Atributos de mensagens da fila de mensagens mortas

• RequestID (String): o ID de invocação da solicitação. Os IDs de solicitação aparecem nos logs de função. O X-Ray SDK também pode ser usado para registrar o ID de solicitação em um atributo no rastreamento. Em seguida, os rastreamentos podem ser procurados por ID de solicitação no console do X-Ray.

• ErrorCode (Número): o código de status HTTP.

• ErrorMessage (String): o primeiro 1 KB da mensagem de erro.

Se o Lambda não puder enviar uma mensagem para a fila de mensagens mortas, ele excluirá o evento e emitirá a métrica DeadLetterErrors. Isso pode acontecer por causa de falta de permissões, ou se o tamanho total da mensagem exceder o limite da fila ou do tópico de destino. Por exemplo, digamos que uma notificação do Amazon SNS com um tamanho de quase 256 KB acione uma função que resulte em erro. Nesse caso, os dados do evento incluídos pelo Amazon SNS, combinados aos atributos adicionados pelo Lambda, podem fazer com que a mensagem exceda o tamanho máximo permitido na fila de mensagens não entregues.

Se você está usando o Amazon SQS como uma fonte de eventos, configure uma fila de mensagens mortas na própria fila do Amazon SQS e não na função do Lambda. Para ter mais informações, consulte Usar o Lambda com o Amazon SQS.