Erreurs de fonction AWS Lambda dans Node.js

Lorsque votre code lève une erreur, Lambda génère une représentation JSON de celle-ci. Cette erreur est documentée dans le journal des invocations et, pour les invocations synchrones, dans la sortie.

Cette page explique comment afficher les erreurs d’invocation des fonctions Lambda pour l’exécution Node.js à l’aide de la console Lambda et de l’AWS CLI.

Syntaxe

Exemple Fichier index.js – Erreur de référence

exports.handler = async function() {
    return x + 10
  }

Ce code génère une erreur de référence. Lambda détecte l’erreur et génère un document JSON avec des champs pour le message d’erreur, le type et la trace de la pile.

{
    "errorType": "ReferenceError",
    "errorMessage": "x is not defined",
    "trace": [
      "ReferenceError: x is not defined",
      "    at Runtime.exports.handler (/var/task/index.js:2:3)",
      "    at Runtime.handleOnce (/var/runtime/Runtime.js:63:25)",
      "    at process._tickCallback (internal/process/next_tick.js:68:7)"
    ]
  }

Fonctionnement

Lorsque vous invoquez une fonction Lambda, Lambda reçoit la demande d’invocation et valide les autorisations dans votre rôle d’exécution, vérifie que le document d’événement est un document JSON valide et contrôle les valeurs des paramètres.

Si la demande est validée, Lambda l’envoie à une instance de fonction. L’environnement d’exécution Lambda convertit le document d’événement en objet et le transmet à votre gestionnaire de fonctions.

Si Lambda rencontre une erreur, il renvoie un type d’exception et un message, ainsi qu’un code d’état HTTP qui indique la cause de l’erreur. Le client ou le service qui a invoqué la fonction Lambda peut gérer l’erreur par programmation ou la transmettre à un utilisateur final. Le comportement correct de gestion des erreurs dépend du type d’application, de l’audience et de la source de l’erreur.

La liste suivante décrit la plage de codes d’état que vous pouvez recevoir de Lambda.

2xx

Une erreur de série 2xx avec un en-tête X-Amz-Function-Error dans la réponse indique une erreur de runtime ou de fonction Lambda. Un code d’état de série 2xx indique que Lambda a accepté la demande, mais au lieu d’un code d’erreur, Lambda indique l’erreur en incluant l’en-tête X-Amz-Function-Error dans la réponse.

4xx

Une erreur de série 4xx indique une erreur que le client ou le service invoquant peut corriger en modifiant la demande, en demandant l’autorisation ou en réessayant la demande. Les erreurs de série 4xx autres que 429 indiquent généralement une erreur avec la demande.

5xx

Une erreur de série 5xx indique un problème avec Lambda ou un problème avec la configuration ou les ressources de la fonction. Les erreurs de série 5xx peuvent indiquer une condition temporaire qui peut être résolue sans aucune action de la part de l’utilisateur. Ces problèmes ne peuvent pas être résolus par le client ou le service invoquant, mais le propriétaire d’une fonction Lambda peut être en mesure de résoudre le problème.

Pour une liste complète des erreurs d'invocation, consultez la section InvokeFunction Erreurs.

Utilisation de la console Lambda

Vous pouvez invoquer votre fonction sur la console Lambda en configurant un événement de test et en affichant la sortie. La sortie est capturée dans les journaux d’exécution de la fonction et lorsque le suivi est activé, dans AWS X-Ray.

Pour invoquer une fonction sur la console Lambda

1. Ouvrez la page Functions (Fonctions) de la console Lambda.

2. Sélectionnez la fonction à tester, puis choisissez Test.

3. Sous Evénement de test, sélectionnez Nouvel événement.

4. Sélectionnez un modèle.

5. Pour Nom, saisissez un nom pour le test. Dans la zone de saisie de texte, entrez l’événement de test JSON.

6. Choisissez Save changes (Enregistrer les modifications).

7. Sélectionnez Tester).

La console Lambda invoque votre fonction de manière synchrone et affiche le résultat. Pour afficher la réponse, les journaux et d’autres informations, développez la section Détails.

Utilisation de AWS Command Line Interface (AWS CLI)

La AWS CLI est un outil open-source qui vous permet d’interagir avec des services AWS à l’aide des commandes de votre shell de ligne de commande. Pour exécuter la procédure indiquée dans cette section, vous devez satisfaire aux exigences suivantes :

• AWS Command Line Interface (AWS CLI) version 2

• AWS CLI – Configuration rapide avec aws configure

Lorsque vous invoquez une fonction Lambda dans la AWS CLI, la AWS CLI divise la réponse en deux documents. La réponse AWS CLI s’affiche dans votre invite de commande. Si une erreur s’est produite, la réponse contient un champ FunctionError. La réponse d’invocation ou l’erreur renvoyés par la fonction est écrite sur un fichier de sortie. Par exemple, output.json ou output.txt.

L’exemple de commande d’invocation suivant montre comment invoquer une fonction et écrire la réponse d’invocation dans un fichier 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

L’option cli-binary-format est obligatoire si vous utilisez AWS CLI version 2. Pour faire de ce paramètre le paramètre par défaut, exécutez aws configure set cli-binary-format raw-in-base64-out. Pour plus d’informations, consultez les options de ligne de commande globales prises en charge par l’AWS CLI dans le Guide de l’utilisateur AWS Command Line Interface version 2.

Vous devriez voir la réponse AWS CLI dans votre invite de commande :

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

Vous devriez voir la réponse d’invocation de fonction dans le fichier output.txt. Dans la même invite de commande, vous pouvez également voir la sortie dans votre invite de commande en utilisant :

cat output.txt

Vous devriez voir la réponse d’invocation dans votre invite de commande.

{"errorType":"ReferenceError","errorMessage":"x is not defined","trace":["ReferenceError: x is not defined"," at Runtime.exports.handler (/var/task/index.js:2:3)"," at Runtime.handleOnce (/var/runtime/Runtime.js:63:25)"," at process._tickCallback (internal/process/next_tick.js:68:7)"]}

Lambda enregistre également jusqu’à 256 Ko de l’objet d’erreur dans les journaux de la fonction. Pour de plus amples informations, veuillez consulter Journalisation des fonctions AWS Lambda dans Node.js.

Gestion des erreurs dans d’autres services AWS

Lorsqu’un autre service AWS invoque votre fonction, celui-ci choisit le type d’invocation et le comportement de la nouvelle tentative. Les services AWS peuvent invoquer votre fonction selon un planificateur, en réponse à un événement de cycle de vie sur une ressource ou à une demande d’un utilisateur. Certains services invoquent des fonctions de manière asynchrone et permettent à Lambda de gérer les erreurs, tandis que d’autres réessaient ou retransmettent les erreurs à l’utilisateur.

Par exemple, API Gateway traite toutes les erreurs d’invocation et de fonction comme des erreurs internes. Si l’API Lambda rejette la demande d’invocation, API Gateway renvoie un code d’erreur 500. Si la fonction s’exécute mais renvoie une erreur ou renvoie une réponse dans le mauvais format, API Gateway renvoie un code d’erreur 502. Pour personnaliser la réponse d’erreur, vous devez attraper les erreurs dans votre code et formater une réponse dans le format requis.

Nous recommandons d’utiliser AWS X-Ray pour déterminer la source d’une erreur et sa cause. X-Ray vous permet de déterminer quel composant a rencontré une erreur et de voir les détails de celle-ci. L’exemple suivant montre une erreur de fonction qui a entraîné une réponse 502 de la part d’API Gateway.

Pour de plus amples informations, veuillez consulter Instrumentation du code Node.js dans AWS Lambda.

Quelle est la prochaine étape ?

• Découvrez comment afficher les événements de journalisation pour votre fonction Lambda sur la page Journalisation des fonctions AWS Lambda dans Node.js.