View a markdown version of this page

AWS Lambda débogage à distance - AWS Boîte à outils pour VS Code
Comment fonctionne le débogage à distance LambdaDémarrageAccès au débogage à distance LambdaUtilisation du débogage à distance LambdaRésolution des problèmes et cas d'utilisation avancés

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

AWS Lambda débogage à distance

AWS Toolkit for Visual Studio Code Cela vous permet de déboguer vos AWS Lambda fonctions qui s'exécutent dans le cloud, directement dans VS Code. Le débogage à AWS Lambda distance vous permet d'inspecter les fonctions en cours d'exécution, de définir des points d'arrêt, d'examiner des variables et de procéder à un débogage étape par étape sans modifier leur flux de développement existant.

Les sections suivantes décrivent comment utiliser le débogage à distance Lambda dans le. AWS Toolkit for Visual Studio Code

Comment fonctionne le débogage à distance Lambda

Le AWS Toolkit permet le débogage à distance en modifiant temporairement vos fonctions Lambda avec une couche de débogage Lambda supplémentaire et en prolongeant le délai d'invocation Lambda à 900 secondes. Une connexion sécurisée est établie entre votre débogueur local et l'environnement d'exécution Lambda à l'aide AWS IoT du tunneling sécurisé. Cette connexion vous permet d'utiliser les points d'arrêt de votre code local pour parcourir la fonction lorsqu'elle s'exécute à distance. Une fois votre session de débogage terminée, toutes les modifications temporaires sont automatiquement rétablies à leurs paramètres d'origine.

Démarrage

Environnements d'exécution pris en charge

Les environnements d'exécution suivants sont pris en charge par le débogage à distance Lambda.

  • Python (Amazon Linux 2023)

  • Java

  • Typescript/JavaScript/Node.js (Amazon Linux 2023)

Note

Les instances gérées Lambda et les types de fonctions d'image OCI ne sont pas pris en charge par le débogage à distance Lambda.

Conditions préalables

Avant de commencer, les conditions suivantes doivent être remplies.

  • Vous devez disposer d' AWS informations d'identification valides configurées dans le AWS Toolkit. Pour plus de détails sur l'installation du AWS Toolkit et la configuration de vos informations d'identification, consultez la rubrique Démarrage de ce guide de l'utilisateur.

  • Une fonction Lambda a été déployée sur votre AWS compte. Pour plus de détails sur le déploiement d'une fonction Lambda, consultez la rubrique Créer votre première fonction Lambda dans le Guide du AWS Lambda développeur.

  • Vous devez disposer de la politique Gestion des identités et des accès AWS (IAM) et des autorisations appropriées pour déboguer votre fonction. Pour plus de détails sur les autorisations Lambda, consultez la AWS Lambda rubrique consacrée aux politiques AWS gérées dans le Guide du AWS Lambda développeur. Voici un exemple de politique contenant les autorisations minimales requises pour utiliser le débogage à distance Lambda dans le AWS Toolkit.

    Note

    Le débogage à distance est activé via AWS AWS IoT Secure Tunneling. Cela permet à votre débogueur local d'établir une connexion sécurisée à l'environnement d'exécution Lambda.

    
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:ListFunctions",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration",
        "lambda:GetLayerVersion",
        "lambda:UpdateFunctionConfiguration",
        "lambda:InvokeFunction",
        "lambda:PublishVersion",
        "lambda:DeleteFunction",
        "iot:OpenTunnel",
        "iot:RotateTunnelAccessToken",
        "iot:ListTunnels"
      ],
      "Resource": "*"
    }
  ]
}

Accès au débogage à distance Lambda

Il existe deux chemins principaux pour accéder au débogage à distance de Lambda dans le AWS Toolkit : l' AWS explorateur ou l'explorateur Application Builder. Depuis l' AWS explorateur, vous pouvez accéder au débogage à distance de Lambda via vos AWS Lambda nœuds. Depuis l'explorateur Application Builder, vous pouvez accéder au débogage à distance de Lambda via vos projets locaux AWS SAM .

Accès au débogage à distance Lambda depuis AWS explorateur

  1. Dans VS Code, ouvrez l'extension AWS Toolkit.

  2. À partir de la AWS boîte à outils, développez l' AWS explorateur.

  3. Depuis l'explorateur, développez le nœud Lambda.

  4. Accédez à la fonction que vous souhaitez déboguer, puis choisissez l'icône Invoquer à distance dans le menu contextuel pour ouvrir l'écran de configuration de l'appel à distance.

Accès au débogage à distance Lambda depuis l'explorateur Application Builder.

  1. Dans VS Code, ouvrez l'extension AWS Toolkit.

  2. À partir de la AWS boîte à outils, développez l'explorateur du générateur d'applications.

  3. Dans l'explorateur, développez le AWS SAM projet qui contient le projet Lambda que vous souhaitez déboguer.

  4. Développez la Lambda fonction déployée que vous souhaitez déboguer.

  5. Accédez à la fonction télécommande, puis choisissez l'icône Invoquer à distance dans le menu contextuel pour ouvrir l'écran de configuration de l'appel à distance.

Utilisation du débogage à distance Lambda

Les sections suivantes décrivent comment utiliser le débogage à distance Lambda dans le. AWS Toolkit for Visual Studio Code

Note

Les fonctions Lambda ont une limite de 5 couches et une limite combinée de 250 Mo pour le code de fonction et toutes les couches associées. Le débogage à distance de Lambda nécessite au moins une couche libre pour s'exécuter.

Configuration d'une session de débogage

Avant de commencer, configurez votre session de débogage en suivant la procédure suivante.

  1. Ouvrez le menu de configuration de l'appel à distance en effectuant la procédure Accès au débogage à distance Lambda depuis l' AWS explorateur ou la procédure Accès au débogage à distance Lambda depuis l'explorateur Application Builder, située dans la section précédente.

  2. Dans le menu de configuration de l'appel à distance, cochez la case Débogage à distance pour afficher les propriétés du débogage à distance.

  3. Spécifiez le chemin racine local vers votre fichier de gestion local.

    Note

    Le chemin racine local est l'emplacement de votre code source qui correspond à la fonction Lambda déployée. Si vous travaillez à partir d'une fonction déployée dans l'explorateur Application Builder, votre chemin racine local est automatiquement détecté.

    Si le code source n'est pas stocké localement, cliquez sur le bouton Télécharger le code à distance pour récupérer le code source de votre fonction Lambda. Cela vous ouvrira handler file dans l'éditeur VS Code.

  4. Dans la section Charge utile, indiquez où les données de vos événements de test sont obtenues.

Définition des points d'arrêt et débogage

Définissez des points d'arrêt et commencez le débogage en suivant la procédure suivante.

  1. handler fileDans l'éditeur VS Code, cliquez dans la marge de la gouttière pour définir des points d'arrêt aux numéros de ligne où vous souhaitez suspendre le débogage.

  2. Lorsque vous êtes satisfait des points d'arrêt, revenez au menu de configuration de l'invocation à distance pour vérifier que vos paramètres sont correctement configurés, puis cliquez sur le bouton d'invocation à distance pour démarrer le débogage.

  3. Le AWS Toolkit met à jour votre fonction Lambda avec des fonctionnalités de débogage, établit un tunnel sécurisé pour la session de débogage, appelle votre fonction avec la charge utile spécifiée, puis interrompt le processus lorsqu'il atteint un point d'arrêt.

  4. Lors d'une pause, utilisez le volet RUN AND DEBUG pour afficher vos VARIABLES, votre PILE D'APPELS et vos POINTS D'ARRÊT.

Mettre à jour et tester votre fonction

Pour modifier votre code et tester les modifications grâce à un déploiement rapide, effectuez la procédure suivante.

  1. Avec votre session de débogage active, apportez des modifications à la vôtre handler file dans l'éditeur VS Code.

  2. Enregistrez vos modifications (Command+S on macOS,Ctrl+S on Windows)

  3. Lorsque vous y êtes invité, confirmez que vous souhaitez poursuivre le déploiement de vos modifications. Le AWS Toolkit mettra à jour votre fonction Lambda avec le code modifié.

  4. Continuez à déboguer et à tester vos modifications en définissant de nouveaux points d'arrêt et en sélectionnant à nouveau le bouton d'invocation à distance.

    Note

    Vous pouvez également désélectionner l'option Attach Debugger dans les commandes de débogage VS Code et choisir le bouton Remote Invoke pour exécuter votre fonction sans déboguer.

Fin d'une session de débogage

Chacune des options suivantes met fin à votre session de débogage à distance et supprime la couche de débogage de votre projet.

  • Choisissez l'option Supprimer la configuration du débogage dans l'écran de configuration de l'appel à distance.

  • Choisir l'icône de déconnexion dans les commandes de débogage de VS Code.

  • Fermez le handler file dans l'éditeur VS Code.

Note

Notez les informations suivantes :

  • La couche de débogage Lambda est automatiquement supprimée après 60 secondes d'inactivité. Le décompte commence lorsque votre dernier appel est terminé.

  • Si vous avez apporté des modifications de code à vos fonctions gérées par infrastructure en tant que code (IaC) (AWS SAM, AWS CDK, Terraform) pendant le processus de débogage, enregistrez-les dans votre projet local et envisagez de mettre à jour votre référentiel de contrôle des sources. Les modifications non enregistrées sont remplacées lorsque votre fonction IaC est redéployée.

  • Si vous avez apporté des modifications temporaires à des fins de débogage uniquement, vous souhaiterez peut-être redéployer votre fonction depuis votre contrôle de source pour vous assurer qu'elle correspond à votre code de production.

Débogage des fonctions TypeScript Lambda avec des cartes sources

Les sections suivantes décrivent comment déboguer vos fonctions TypeScript Lambda à l'aide de cartes sources.

Conditions préalables

Pour déboguer vos fonctions TypeScript Lambda, les conditions préalables suivantes doivent être remplies.

  • Vous TypeScript devez être compilé avec l'option de carte source activée. Pour plus d'informations, consultez la rubrique relative à la prise en charge de la carte JavaScript source dans la documentation VS Code.

  • In-line les cartes sources ne sont pas prises en charge. Vous devez utiliser un .js.map fichier distinct pour stocker la carte source.

Configuration

Pour configurer le débogage à distance Lambda pour les fonctions TypeScript Lambda dans le AWS Toolkit, procédez comme suit.

  1. À partir de la AWS boîte à outils, développez l' AWS explorateur.

  2. Depuis l'explorateur, développez le nœud Lambda.

  3. Accédez à la fonction pour laquelle vous souhaitez configurer TypeScript, puis choisissez l'icône Invoquer à distance dans le menu contextuel pour ouvrir l'écran de configuration de l'appel à distance.

  4. Activez le débogage à distance en cochant la case Débogage à distance.

  5. Configurez votre chemin racine local en pointant vers le répertoire contenant votreTypeScript handler file.

    Note

    TypeScript handler fileC'est là que vous définissez vos points d'arrêt de débogage.

  6. Développez les paramètres de configuration supplémentaires du débogage à distance.

  7. Activez le mappage des sources en cochant la case Carte des sources.

  8. Définissez le champ Fichiers de sortie sur le répertoire local de votre copie de fonction Lambda.

    Exemple

    Si app.js et app.map sont dedans.aws-sam/build/HelloWorldFunction, définissez l'emplacement des fichiers de sortie/Users/user/project/aws-sam/build/HelloWorldFunction/*.

    Note

    Le chemin du fichier de sortie doit être un chemin absolu.

    Pour les AWS CDK projets AWS SAM et, la AWS boîte à outils prend en charge la détection automatique des cartes sources. Si le champ Fichiers de sortie est laissé vide pour ces projets, la boîte à outils tentera automatiquement de détecter l'emplacement de la carte source.

  9. Lorsque vous êtes satisfait des paramètres, cliquez sur le bouton d'invocation à distance pour commencer à déboguer votre TypeScript fonction.

Résolution des problèmes et cas d'utilisation avancés

Si votre session de débogage échoue, lancez le processus de dépannage en suivant ces étapes.

  1. Mettez à jour la AWS boîte à outils vers la dernière version.

  2. Actualisez la vue Web en fermant la vue Web de configuration de l'invocation à distance et en la rouvrant.

  3. Redémarrez VS Code en le fermant complètement et en le rouvrant.

  4. Ouvrez la palette de commandes VS Code et entrez la commandeAWS: Reset Lambda Remote Debugging Snapshot, sélectionnez-la lorsqu'elle apparaît dans les résultats pour réinitialiser votre instantané de débogage à distance Lambda.

  5. Si vous ne parvenez pas à résoudre le problème, soumettez-le à la section AWS Toolkit for Visual Studio Code GitHub Problèmes.

Cas d'utilisation avancé : configuration de signature de code

Le débogage à distance nécessite d'associer une couche de débogage à votre fonction Lambda. Si la configuration de signature de code est activée et appliquée, le AWS Toolkit ne peut pas automatiquement associer la couche de débogage à votre fonction.

Il existe deux options pour résoudre le problème de configuration de la signature de code.

  • Supprimez temporairement la signature de code.

  • Utilisez une couche de débogage signée.

Suppression temporaire de la signature de code

Mettez à jour la configuration de signature de code en paramétrantUntrustedArtifactOnDeployment : Warn, puis réactivez-la une Enforced fois le processus de débogage terminé.

Pour plus d'informations, consultez la UpdateCodeSigningConfig référence dans la référence de AWS Lambda l'API.

Utilisation d'une couche de débogage signée

  1. Depuis Débogage à distance Lambda dans le AWS Toolkit, développez la section Configuration supplémentaire du débogage à distance.

  2. Dans la section Configuration supplémentaire du débogage à distance, copiez l'ARN de votre couche régionale à partir du champ Layer Override.

  3. À partir de AWS CLI, utilisez la commande suivante pour télécharger la version de la coucheaws lambda get-layer-version-by-arn --arn layer-arn, en remplaçant layer-arn par l'ARN de votre couche. Pour obtenir des instructions détaillées sur le téléchargement de la couche de débogage signée, consultez la référence https://docs.aws.amazon.com/cli/latest/reference/lambda/get-layer-version-by-arn.html get-layer-version-by-arn dans la Référence des commandes. AWS CLI

  4. Signez la couche avec votre configuration de signature de code et publiez-la sur votre compte. Pour obtenir des conseils en matière de signature et de publication, consultez la rubrique Configuration de la signature de code pour votre AWS SAM application dans le Guide du AWS Serverless Application Model développeur.

  5. Une fois la couche signée et publiée sur votre compte, revenez à la section Configuration supplémentaire du débogage à distance du débogage à distance Lambda, puis saisissez l'ARN de la nouvelle couche dans le champ Layer Override. Une fois le processus terminé, le débogage à distance de Lambda utilise votre couche signée au lieu de la couche par défaut.

Cas d'utilisation avancé : fonctions de débogage avec SnapStart ou provisionnement simultané

Pour les fonctions Lambda configurées avec SnapStart ou provisionnées en simultanéité, la publication d'une nouvelle version prend beaucoup plus de temps. Pour accélérer votre flux de travail de débogage, vous pouvez configurer le débogage à distance Lambda pour mettre à jour uniquement la $LATEST version de votre fonction au lieu de publier une nouvelle version.

  1. À partir de l'écran de configuration de l'appel à distance, développez les paramètres de configuration supplémentaires du débogage à distance.

  2. Désélectionnez l'option Publier la version.

  3. Le AWS Toolkit ne fera désormais que mettre à jour la $LATEST version de votre fonction et le déboguer à l'aide de celle-ci.

Note

Comme effet secondaire du débogage avec la $LATEST version, vous devez éviter tout autre trafic susceptible d'invoquer votre $LATEST version afin de garantir un environnement de débogage non perturbé.

Régions prises en charge

L'erreur suivante se produit lorsqu'une région ne prend pas en charge le débogage à distance.

Region ${region} doesn't support remote debugging yet

La liste suivante répertorie les régions prises en charge.

  • ap-east-1

  • ap-northeast-1

  • ap-northeast-2

  • ap-south-1

  • ap-southeast-1

  • ap-southeast-2

  • ca-central-1

  • eu-central-1

  • eu-north-1

  • eu-west-1

  • eu-west-2

  • eu-west-3

  • me-central-1

  • me-south-1

  • sa-east-1

  • us-east-1

  • us-east-2

  • us-west-1

  • us-west-2

Lambda RequestEntityTooLargeException

Les fonctions Lambda ont une limite de 5 couches et une limite combinée de 250 Mo pour le code de fonction et toutes les couches associées. La couche de débogage à distance est d'environ 40 Mo, ce qui peut amener votre fonction à dépasser cette limite si vous disposez d'un package de fonctions volumineux ou de plusieurs couches. Pour plus de détails, consultez la section Lambda : InvalidParameterValueException ou RequestEntityTooLargeException rubrique du Guide du AWS Lambda développeur.

La liste suivante décrit les méthodes permettant de résoudre et de corriger cette erreur.

  • Réduire la taille des fonctions  : optimisez le code de votre fonction et supprimez les dépendances inutiles.

  • Supprimer les couches non utilisées  : Supprimez temporairement les couches non essentielles pendant le débogage.

  • Utiliser des dépendances externes  : déplacez les dépendances importantes vers un stockage externe, tel qu'Amazon S3, et chargez-les lors de l'exécution.

Résolution des problèmes de débogage Java

Pour déboguer une fonction Java Lambda, vous devez avoir installé localement la même version de Java qui correspond à la version d'exécution de votre fonction Lambda.

Par exemple, lors du débogage d'une fonction Java 25, Java 25 doit être installé dans votre environnement local dans lequel le AWS Toolkit est en cours d'exécution. Si vous tentez de déboguer une fonction Java 25 avec Java 21 ou une version antérieure installée localement, le débogage à distance ne pourra pas s'arrêter aux points d'arrêt que vous avez définis.

Assurez-vous que votre version locale de Java correspond à la version d'exécution de votre fonction Lambda avant de démarrer une session de débogage.

Le quota de tunneling sécurisé pour l'IoT a été dépassé

Voici un exemple de l'erreur de dépassement du quota de tunnel qui se produit lorsque vous avez atteint la limite quotidienne de connexions de tunneling AWS IoT sécurisées dans le cadre du débogage à distance Lambda.

Error creating/reusing tunnel: LimitExceededException: Exceeded quota of Lambda debugging tunnels

AWS IoT Les quotas de connexion Secure Tunneling sont les suivants :

  • Free-tier Le tunneling sécurisé IoT est attribué à 10 connexions par jour.

  • Chaque tunnel prend en charge une instance VS Code pendant une durée maximale de 12 heures.

  • Le quota s'applique par AWS compte et par jour.

Si vous rencontrez une erreur de tunneling AWS IoT sécurisé, attendez la réinitialisation quotidienne du quota ou contactez le AWS support pour demander une augmentation de la limite de quota. Pour obtenir les informations de contact de l' AWS assistance, consultez le portail de contact de l'AWS assistance. Pour des informations détaillées sur le tunneling AWS IoT sécurisé, consultez la rubrique sur le tunneling AWS IoT sécurisé dans le Guide du développeur. AWS IoT