Testar e depurar as funções do Lambda@Edge

Este tópico inclui seções que descrevem estratégias para testar e depurar funções do Lambda@Edge. É importante testar o código da sua função do Lambda@Edge independentemente para ter certeza de que ele conclui a tarefa pretendida e fazer testes de integração para garantir que a função funcione corretamente com o CloudFront.

Durante o teste de integração ou depois que a função foi implantada, talvez seja necessário depurar erros do CloudFront, como erros HTTP 5xx. Os erros podem ser uma resposta inválida retornada da função do Lambda, erros de execução quando a função é acionada ou erros devido a uma limitação de execução do serviço do Lambda. As seções neste tópico compartilham estratégias para determinar qual tipo de falha é o problema e, em seguida, as etapas que você pode realizar para corrigir o problema.

nota

Ao revisar os arquivos de log ou as métricas do CloudWatch durante a solução de erros, esteja ciente de que eles são exibidos ou armazenados na Região da AWS mais próxima do local em que a função foi executada. Portanto, se você tiver um site ou aplicação web com usuários no Reino Unido e, por exemplo, tiver uma função do Lambda associada à distribuição, deverá alterar a região para visualizar as métricas ou os arquivos de log do CloudWatch para a Região da AWS Londres. Para ter mais informações, consulte Determinar a região do Lambda@Edge.

Testar as funções do Lambda@Edge

Há duas etapas para testar a função do Lambda: teste autônomo e teste de integração.

Testar a funcionalidade autônoma

Antes de adicionar a função do Lambda ao CloudFront, teste a funcionalidade primeiro usando os recursos de teste no console do Lambda ou usando outros métodos. Para obter mais informações sobre testes no console do Lambda, consulte a seção Invocar a função Lambda e verificar os resultados, logs e métricas em Criar uma função Lambda com o console no Guia do desenvolvedor do AWS Lambda.

Testar a operação da função no CloudFront

É importante concluir o teste de integração, quando a função está associada a uma distribuição e é executada com base em um evento do CloudFront. Certifique-se de que a função seja acionada para o evento correto e retorne uma resposta válida e correta para o CloudFront. Por exemplo, verifique se a estrutura do evento está correta, se apenas os cabeçalhos válidos estão incluídos e assim por diante.

Ao iterar os testes de integração com a função no console do Lambda, consulte as etapas do tutorial do Lambda@Edge à medida que você modifica o código ou altera o trigger do CloudFront que chama a função. Por exemplo, verifique se você está trabalhando em uma versão numerada da função, conforme descrito nesta etapa do tutorial: Etapa 4: adicionar um acionador do CloudFront para executar a função.

Ao fazer alterações e implantá-las, lembre-se de que a função e os triggers atualizados do CloudFront levarão vários minutos para serem replicados em todas as regiões. Isso geralmente leva alguns minutos, mas pode demorar até 15 minutos.

Você pode verificar se a replicação foi concluída acessando o console do CloudFront e visualizando a distribuição.

Como verificar se a implantação da replicação foi concluída

1. Abra o console do CloudFront em https://console.aws.amazon.com/cloudfront/v4/home.

2. Escolha o nome da distribuição.

3. Verifique o status de distribuição para mudar de In Progress (Em progresso) para Deployed (Implantado), o que significa que sua função foi replicada. Em seguida, siga as etapas na próxima seção para verificar se a função funciona.

Esteja ciente de que o teste no console valida apenas a lógica da sua função e não aplica cotas de serviço (anteriormente conhecidas como limites) específicas do Lambda@Edge.

Identificar erros de função do Lambda@Edge no CloudFront

Depois de verificar se a lógica da função funciona corretamente, você ainda poderá ver erros HTTP 5xx quando a função for executada no CloudFront. Os erros HTTP 5xx podem ser retornados por vários motivos, que incluem erros ou outros problemas da função do Lambda no CloudFront.

• Ao usar as funções do Lambda@Edge, é possível usar gráficos no console do CloudFront para ajudar a identificar o que está causando o erro e corrigi-lo. Por exemplo, é possível ver se os erros HTTP 5xx são causados pelo CloudFront ou pelas funções do Lambda e, no caso de funções específicas, visualizar os arquivos de log relacionados para investigar o problema.

• Para solucionar a maioria dos erros HTTP do CloudFront, consulte as etapas de solução de problemas no seguinte tópico: Como solucionar problemas de respostas de erro da sua origem.

O que causa erros na função do Lambda@Edge no CloudFront

Existem vários motivos pelos quais uma função do Lambda pode causar um erro HTTP 5xx, e as etapas de solução de problemas que você deve seguir dependem do tipo de erro. Os erros podem ser categorizados assim:

Um erro de execução de função do Lambda

Ocorre um erro de execução quando o CloudFront não obtém uma resposta do Lambda porque existem exceções não tratadas na função ou há um erro no código. Por exemplo, se o código incluir um retorno de chamada (erro). Consulte mais informações em Erros da função do AWS Lambda em Node.js no Guia do desenvolvedor do AWS Lambda.

Uma resposta inválida da função do Lambda é retornada ao CloudFront

Após a execução da função, o CloudFront recebe uma resposta do Lambda. Um erro será retornado se a estrutura do objeto da resposta não estiver em conformidade com o Estrutura de eventos do Lambda@Edge ou se a resposta contiver cabeçalhos inválidos ou outros campos inválidos.

A execução no CloudFront é limitada devido às cotas de serviço do Lambda (anteriormente conhecidas como limites)

O serviço do Lambda limita as execuções em cada região e retornará um erro se você exceder a cota.

Como determinar o tipo de falha

Para ajudar a decidir onde se concentrar na depuração de erros e solucionar os problemas retornados pelo CloudFront, é útil identificar por que o CloudFront está retornando um erro HTTP. Para iniciar a busca, você pode usar os gráficos fornecidos na seção Monitoring (Monitoramento) do console do CloudFront no AWS Management Console. Para obter mais informações sobre como visualizar gráficos na seção Monitoring (Monitoramento) no console do CloudFront, consulte Monitorar métricas do CloudFront com o Amazon CloudWatch.

Os seguintes gráficos podem ser especialmente úteis ao verificar se os erros estão sendo retornados por origens ou por uma função do Lambda, e para restringir o tipo de problema quando se trata de um erro de função do Lambda.

Gráfico de taxas de erro

Um dos gráficos que você pode visualizar na guia Overview (Visão geral) para cada uma das suas distribuições é um gráfico Error rates (Taxas de erro). Esse gráfico exibe a taxa de erros como porcentagem do total de solicitações que chegam à sua distribuição. O gráfico mostra o total de taxa de erros, total de erros 4xx, total de erros 5xx e total de erros 5xx provenientes de funções Lambda. Com base no tipo de erro e volume, você pode executar etapas para investigar e solucionar o problema.

• Se você encontrar erros do Lambda, você poderá investigar mais detalhadamente, observando os tipos específicos de erros retornados pela função. A guia Lambda@Edge errors (Erros do Lambda@Edge) inclui gráficos que categorizam os erros por tipo de função para ajudar a identificar o problema em uma função específica.

• Se encontrar erros do CloudFront, você poderá solucionar e trabalhar para corrigir os erros de origem ou alterar a configuração do CloudFront. Para ter mais informações, consulte Como solucionar problemas de respostas de erro da sua origem.

Gráficos de erros de execução e repostas de funções inválidas

A guia Lambda@Edge errors (Erros do Lambda@Edge) inclui gráficos que categorizam os erros do Lambda@Edge em uma distribuição específica, por tipo. Por exemplo, um grafo mostra todos os erros de execução por Região da AWS.

Para facilitar a solução de problemas, você pode procurar problemas específicos ao abrir e examinar os arquivos de log para funções específicas por região.

Como visualizar os arquivos de log de uma função específica por região

1. Na guia Erros do Lambda@Edge, em Funções associadas do Lambda@Edge, escolha o nome da função e selecione Visualizar métricas.

2. Em seguida, na página com o nome da função, no canto superior direito, selecione Visualizar logs da função e escolha uma região.

   Por exemplo, se você encontrar problemas no grafo Erros para a região Oeste dos EUA (Oregon), escolha essa região na lista suspensa. Isso abrirá o console do Amazon CloudWatch.

3. No console do CloudWatch dessa região, em Fluxos de log, escolha um fluxo de log para visualizar os eventos da função.

Também leia as seguintes seções neste capítulo para obter mais recomendações sobre como solucionar problemas e corrigir erros.

Gráfico de limitações

A guia Lambdga@Edge errors (Erros do Lambda@Edge) também inclui um gráfico de Throttles (Limitações). Ocasionalmente, o serviço Lambda limita as invocações de função por região quando a cota (anteriormente conhecida como limite) de simultaneidade regional é atingida. Se você encontrar um erro limit exceeded (limite excedido), isso significa que a função atingiu uma cota que o serviço Lambda impõe para execuções em uma região. Para obter mais informações, incluindo como solicitar um aumento na cota, consulte Cotas do Lambda@Edge.

Para obter um exemplo de como usar essas informações para solucionar erros HTTP, consulte Quatro etapas para depurar a entrega de conteúdo na AWS.

Solução de problemas de respostas inválidas de funções do Lambda@Edge (erros de validação)

Se você identificar que o problema é um erro de validação do Lambda, a função do Lambda poderá estar retornando uma resposta inválida ao CloudFront. Siga as orientações nesta seção para tomar medidas para analisar a função e garantir que a resposta esteja de acordo com os requisitos do CloudFront.

O CloudFront valida a resposta de uma função do Lambda de duas maneiras:

• A resposta do Lambda deve estar de acordo com a estrutura de objeto necessária. Exemplos de estruturas de objeto inválidas incluem o seguinte: JSON não analisável, campos obrigatórios ausentes e um objeto inválido na resposta. Para obter mais informações, consulte Estrutura de eventos do Lambda@Edge.

• A resposta deve incluir apenas valores de objeto válidos. Um erro ocorrerá se a resposta incluir um objeto válido, mas tiver valores sem suporte. Os exemplos incluem o seguinte: adicionar ou atualizar cabeçalhos permitidos ou somente leitura (consulte Restrições das funções de borda), exceder o tamanho máximo do corpo (consulte Restrições sobre o tamanho da resposta gerada no tópico Erros do Lambda@Edge) e caracteres ou valores inválidos (consulte o Estrutura de eventos do Lambda@Edge).

Quando o Lambda retorna uma resposta inválida ao CloudFront, as mensagens de erro são gravados em arquivos de log que o CloudFront envia por push ao CloudWatch na região em que a função do Lambda foi executada. O comportamento padrão é enviar os arquivos de log ao CloudWatch quando há uma resposta inválida. No entanto, se você tiver associado uma função do Lambda ao CloudFront antes do lançamento dessa funcionalidade, talvez ela não esteja habilitada para a função. Para obter mais informações, consulte Determinar se a conta envia logs por push ao CloudWatch, mais adiante neste tópico.

O CloudFront envia arquivos de log à região correspondente ao local onde a função foi executada, no grupo de logs associado à sua distribuição. Os grupos de log têm o seguinte formato: /aws/cloudfront/LambdaEdge/DistributionId, em que DistributionId é o ID da distribuição. Para determinar a região na qual você pode encontrar os arquivos de log do CloudWatch, consulte Determinar a região do Lambda@Edge mais adiante neste tópico.

Se for possível reproduzir o erro, você poderá criar uma nova solicitação que resulte no erro e encontrar o id da solicitação em uma resposta do CloudFront com falha (cabeçalho X-Amz-Cf-Id) para localizar uma única falha nos arquivos de log. A entrada do arquivo de log inclui informações que podem ajudar a identificar porque o erro está sendo retornado, e também lista o id da solicitação do Lambda correspondente, para que você possa analisar a causa raiz no contexto de uma única solicitação.

Se um erro for intermitente, você poderá usar os logs de acesso do CloudFront para encontrar o id de uma solicitação que falhou e depois pesquisar as mensagens de erro correspondentes nos CloudWatch Logs. Para mais informações, consulte a seção anterior, Determinar o tipo de falha.

Solução de problemas de erros de execução de funções do Lambda@Edge

Se o problema for um erro de execução do Lambda, poderá ser útil criar instruções de registro em log para funções do Lambda, gravar mensagens nos arquivos de log CloudWatch que monitoram a execução da função no CloudFront e determinar se ela está funcionando conforme o esperado. Depois, você pode pesquisar essas instruções nos arquivos de log do CloudWatch para verificar se a sua função está funcionando.

nota

Mesmo que você não tenha alterado a função do Lambda@Edge, as atualizações no ambiente de execução da função do Lambda podem afetá-la e um erro de execução poderá ser retornado. Para obter informações sobre como testar e migrar para uma versão mais recente, consulte Próximas atualizações no AWS Lambda e no ambiente de execução do AWS Lambda@Edge.

Determinar a região do Lambda@Edge

Para ver as regiões em que a função do Lambda@Edge está recebendo tráfego, visualize os gráficos das métricas da função no console do CloudFron no AWS Management Console. As métricas são exibidas para cada região da AWS. Na mesma página, é possível escolher uma região e visualizar os arquivos de log para essa região a fim de investigar problemas. Revise os arquivos de log do CloudWatch na região correta da AWS para ver os arquivos de log criados quando o CloudFront executou a função Lambda.

Para obter mais informações sobre como visualizar gráficos na seção Monitoring (Monitoramento) no console do CloudFront, consulte Monitorar métricas do CloudFront com o Amazon CloudWatch.

Determinar se a sua conta envia logs ao CloudWatch

Por padrão, o CloudFront habilita o registro em log de respostas de função inválidas do Lambda e envia por push os arquivos de log para o CloudWatch usando uma das Funções vinculadas ao serviço para o Lambda@Edge. Se você tiver funções do Lambda@Edge adicionadas ao CloudFront antes do lançamento do recurso de log de respostas de função inválidas do Lambda, o registro em log será habilitado quando você atualizar a configuração do Lambda@Edge, por exemplo, adicionando um trigger do CloudFront.

É possível verificar se o envio por push dos arquivos de log ao CloudWatch está habilitado para a conta, fazendo o seguinte:

• Verifique se os logs aparecem no CloudWatch. Certifique-se de examinar na região em que a função do Lambda@Edge foi executada. Para ter mais informações, consulte Determinar a região do Lambda@Edge.

• Determine se a função vinculada a serviço relacionada existe na sua conta do IAM. Para fazer isso, abra o console do IAM em https://console.aws.amazon.com/iam/ e escolha Roles (Funções) para exibir a lista de funções vinculadas ao serviço da conta. Procure a seguinte função: AWSServiceRoleForCloudFrontLogger.