View a markdown version of this page

AWS Lambda Remote-Debugging - AWS Toolkit für VS Code
Wie funktioniert Lambda-Remote-DebuggingErste SchritteZugriff auf Lambda-Remote-DebuggingArbeiten mit Lambda-Remote-DebuggingProblembehandlung und Anwendungsfälle für Fortgeschrittene

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

AWS Lambda Remote-Debugging

AWS Toolkit for Visual Studio Code Mit dem können Sie Ihre AWS Lambda Funktionen, die in der Cloud ausgeführt werden, direkt in VS Code debuggen. Mit dem AWS Lambda Remote-Debugging können Sie laufende Funktionen überprüfen, Breakpoints setzen, Variablen untersuchen und schrittweise debuggen, ohne den bestehenden Entwicklungsworkflow zu ändern.

In den folgenden Abschnitten wird beschrieben, wie Sie mit Lambda-Remote-Debugging in der arbeiten. AWS Toolkit for Visual Studio Code

Wie funktioniert Lambda-Remote-Debugging

Das AWS Toolkit ermöglicht das Remote-Debugging, indem es Ihre Lambda-Funktionen vorübergehend mit einer zusätzlichen Lambda-Debugging-Ebene ändert und das Timeout-Limit für Lambda-Aufrufe auf 900 Sekunden erweitert. Mithilfe von Secure Tunneling wird eine sichere Verbindung zwischen Ihrem lokalen Debugger und der Lambda-Laufzeitumgebung hergestellt. AWS IoT Diese Verbindung ermöglicht es Ihnen, Ihre lokalen Code-Breakpoints zu verwenden, um die Funktion Schritt für Schritt zu durchlaufen, während sie remote ausgeführt wird. Nach Abschluss Ihrer Debugging-Sitzung werden alle temporären Änderungen automatisch auf ihre ursprünglichen Einstellungen zurückgesetzt.

Erste Schritte

Unterstützte Laufzeiten

Die folgenden Laufzeiten werden vom Lambda-Remote-Debugging unterstützt.

  • Python (Amazon Linux 2023)

  • Java

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

Anmerkung

Von Lambda verwaltete Instances und OCI-Image-Funktionstypen werden vom Lambda-Remote-Debugging nicht unterstützt.

Voraussetzungen

Bevor Sie beginnen, müssen die folgenden Voraussetzungen erfüllt sein.

  • Sie müssen gültige AWS Anmeldeinformationen im AWS Toolkit konfiguriert haben. Weitere Informationen zur Installation des AWS Toolkits und zur Konfiguration Ihrer Anmeldeinformationen finden Sie im Thema Erste Schritte in diesem Benutzerhandbuch.

  • Eine Lambda-Funktion wurde für Ihr AWS Konto bereitgestellt. Einzelheiten zur Bereitstellung einer Lambda-Funktion finden Sie im Thema Erstellen Sie Ihre erste Lambda-Funktion im AWS Lambda Entwicklerhandbuch.

  • Sie müssen über die entsprechenden AWS Identity and Access Management (IAM-) Richtlinien und Berechtigungen verfügen, um Ihre Funktion zu debuggen. Weitere Informationen zu Lambda-Berechtigungen finden Sie im entsprechenden AWS Lambda Thema „AWS Verwaltete Richtlinien“ im AWS Lambda Entwicklerhandbuch. Im Folgenden finden Sie ein Beispiel für eine Richtlinie, die die mindestens erforderlichen Berechtigungen für die Arbeit mit Lambda-Remote-Debugging im Toolkit enthält. AWS

    Anmerkung

    Das Remote-Debugging wird über Secure Tunneling aktiviert. AWS AWS IoT Dadurch kann Ihr lokaler Debugger eine sichere Verbindung zur Lambda-Laufzeitumgebung herstellen.

    
{
  "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": "*"
    }
  ]
}

Zugriff auf Lambda-Remote-Debugging

Es gibt zwei Hauptpfade für den Zugriff auf das Lambda-Remote-Debugging im AWS Toolkit: den AWS Explorer oder den Application Builder-Explorer. Vom AWS Explorer aus können Sie über Ihre Knoten auf das Lambda-Remote-Debugging zugreifen. AWS Lambda Vom Application Builder Explorer aus können Sie über Ihre lokalen Projekte auf das Lambda-Remote-Debugging zugreifen. AWS SAM

Der Zugriff auf Lambda-Remote-Debugging erfolgt über AWS Entdecker

  1. Öffnen Sie in VS Code die AWS Toolkit-Erweiterung.

  2. Erweitern Sie im AWS Toolkit den AWS Explorer.

  3. Erweitern Sie im Explorer den Lambda-Knoten.

  4. Navigieren Sie zu der Funktion, die Sie debuggen möchten, und wählen Sie dann im Kontextmenü das Symbol „Per Fernzugriff aufrufen“, um den Konfigurationsbildschirm für den Fernaufruf zu öffnen.

Zugriff auf das Lambda-Remote-Debugging über den Application Builder-Explorer.

  1. Öffnen Sie in VS Code die AWS Toolkit-Erweiterung.

  2. Erweitern Sie im AWS Toolkit den Application Builder Explorer.

  3. Erweitern Sie im Explorer das AWS SAM Projekt, das das Lambda-Projekt enthält, das Sie debuggen möchten.

  4. Erweitern Sie die bereitgestellte Lambda Funktion, die Sie debuggen möchten.

  5. Navigieren Sie zur Funktionsfernbedienung und wählen Sie dann im Kontextmenü das Symbol „Ferngesteuert aufrufen“, um den Konfigurationsbildschirm für den Fernaufruf zu öffnen.

Arbeiten mit Lambda-Remote-Debugging

In den folgenden Abschnitten wird beschrieben, wie Sie mit Lambda-Remote-Debugging in der arbeiten. AWS Toolkit for Visual Studio Code

Anmerkung

Lambda-Funktionen haben ein Limit von 5 Ebenen und ein kombiniertes Limit von 250 MB für den Funktionscode und alle angehängten Ebenen. Für das Lambda-Remote-Debugging ist mindestens eine freie Ebene erforderlich, um ausgeführt zu werden.

Eine Debugging-Sitzung einrichten

Bevor Sie beginnen, konfigurieren Sie Ihre Debugging-Sitzung, indem Sie das folgende Verfahren ausführen.

  1. Öffnen Sie das Konfigurationsmenü zum Remote-Aufrufen, indem Sie das Verfahren Zugreifen auf Lambda-Remote-Debugging vom AWS Explorer aus oder das Verfahren Zugreifen auf Lambda-Remote-Debugging aus dem Application Builder-Explorer abschließen, das sich im vorherigen Abschnitt befindet.

  2. Wählen Sie im Konfigurationsmenü für Fernaufruf das Kontrollkästchen Remote-Debugging aus, um die Eigenschaften des Remote-Debuggings anzuzeigen.

  3. Geben Sie den lokalen Stammpfad zu Ihrer lokalen Handler-Datei an.

    Anmerkung

    Der lokale Stammpfad ist der Speicherort Ihres Quellcodes, der der bereitgestellten Lambda-Funktion entspricht. Wenn Sie mit einer bereitgestellten Funktion im Application Builder Explorer arbeiten, wird Ihr lokaler Stammpfad automatisch erkannt.

    Wenn Sie den Quellcode nicht lokal gespeichert haben, wählen Sie die Schaltfläche Remote-Code herunterladen, um den Quellcode Ihrer Lambda-Funktion abzurufen. Dadurch wird Ihr handler file im VS Code-Editor geöffnet.

  4. Geben Sie im Abschnitt Payload an, wo Ihre Testereignisdaten abgerufen werden.

Breakpoints setzen und debuggen

Setzen Sie Haltepunkte und beginnen Sie mit dem Debuggen, indem Sie das folgende Verfahren ausführen.

  1. Klicken Sie handler file im VS Code-Editor auf den Zwischenraum, um Breakpoints an den Zeilennummern festzulegen, an denen Sie das Debuggen unterbrechen möchten.

  2. Wenn Sie mit den Breakpoints zufrieden sind, kehren Sie zum Konfigurationsmenü für Fernaufruf zurück, um zu überprüfen, ob Ihre Einstellungen korrekt konfiguriert sind, und wählen Sie dann die Schaltfläche Fernaufruf, um das Debuggen zu starten.

  3. Das AWS Toolkit aktualisiert Ihre Lambda-Funktion mit Debugging-Funktionen, richtet einen sicheren Tunnel für die Debugging-Sitzung ein, ruft Ihre Funktion mit der angegebenen Nutzlast auf und unterbricht dann den Prozess, wenn er einen Breakpoint erreicht.

  4. Verwenden Sie bei einer Breakpoint-Pause den Bereich RUN AND DEBUG, um Ihre VARIABLES, CALL STACK und BREAKPOINTS anzuzeigen.

Aktualisieren und testen Sie Ihre Funktion

Gehen Sie wie folgt vor, um Ihren Code zu ändern und Änderungen mit einer schnellen Bereitstellung zu testen.

  1. Wenn Ihre Debugging-Sitzung aktiv ist, nehmen Sie handler file im VS Code-Editor Änderungen an Ihrem vor.

  2. Speichern Sie Ihre Änderungen (Command+S on macOS,Ctrl+S on Windows)

  3. Bestätigen Sie, dass Sie mit der Bereitstellung Ihrer Änderungen fortfahren möchten, wenn Sie dazu aufgefordert werden. Das AWS Toolkit aktualisiert Ihre Lambda-Funktion mit dem geänderten Code.

  4. Fahren Sie mit dem Debuggen und Testen Ihrer Änderungen fort, indem Sie neue Breakpoints setzen und erneut auf die Schaltfläche Remote Invoke klicken.

    Anmerkung

    Alternativ können Sie die Option Debugger anhängen in den VS Code-Debugging-Steuerelementen deaktivieren und die Schaltfläche Fernaufruf wählen, um Ihre Funktion ohne Debugging auszuführen.

Beenden einer Debugging-Sitzung

Jede der folgenden Optionen beendet Ihre Remote-Debugging-Sitzung und entfernt die Debug-Ebene aus Ihrem Projekt.

  • Wählen Sie im Konfigurationsbildschirm für den Fernaufruf die Option Debug-Setup entfernen.

  • Wählen Sie das Symbol zum Trennen der Verbindung aus den VS Code-Debugging-Steuerelementen.

  • Schließen des handler file im VS Code-Editor.

Anmerkung

Beachten Sie die folgenden Punkte:

  • Die Lambda-Debug-Ebene wird nach 60 Sekunden Inaktivität automatisch entfernt. Die Zählung beginnt, wenn Ihr letzter Aufruf abgeschlossen ist.

  • Wenn Sie während des Debugging-Vorgangs Codeänderungen an Ihren von der Infrastruktur als Code (IaC) verwalteten Funktionen (AWS SAM,, Terraform) vorgenommen haben AWS CDK, speichern Sie diese in Ihrem lokalen Projekt und erwägen Sie, Ihr Quellcodeverwaltungs-Repository zu aktualisieren. Ungespeicherte Änderungen werden überschrieben, wenn Ihre IaC-Funktion erneut bereitgestellt wird.

  • Wenn Sie temporäre Änderungen nur zu Debugging-Zwecken vorgenommen haben, möchten Sie Ihre Funktion möglicherweise von Ihrer Quellcodeverwaltung aus erneut bereitstellen, um sicherzustellen, dass sie mit Ihrem Produktionscode übereinstimmt.

Debuggen von TypeScript Lambda-Funktionen mit Quellzuordnungen

In den folgenden Abschnitten wird beschrieben, wie Sie Ihre TypeScript Lambda-Funktionen mit Quellzuordnungen debuggen.

Voraussetzungen

Um Ihre TypeScript Lambda-Funktionen zu debuggen, müssen die folgenden Voraussetzungen erfüllt sein.

  • Sie TypeScript müssen mit aktivierter Quellzuordnungsoption kompiliert werden. Weitere Informationen finden Sie im Thema zur Unterstützung der JavaScript Quellkarte in der VS Code-Dokumentation.

  • In-line Quellzuordnungen werden nicht unterstützt. Sie müssen eine separate .js.map Datei verwenden, um die Quellkarte zu speichern.

Konfiguration

Gehen Sie wie folgt vor, um das Lambda-Remote-Debugging für TypeScript Lambda-Funktionen im AWS Toolkit zu konfigurieren.

  1. Erweitern Sie im AWS Toolkit den Explorer. AWS

  2. Erweitern Sie im Explorer den Lambda-Knoten.

  3. Navigieren Sie zu der Funktion TypeScript, für die Sie konfigurieren möchten, und wählen Sie dann im Kontextmenü das Symbol Fernzugriff aufrufen, um den Konfigurationsbildschirm für Fernaufruf zu öffnen.

  4. Aktivieren Sie das Remote-Debugging, indem Sie das Kontrollkästchen Remote-Debugging aktivieren.

  5. Konfigurieren Sie Ihren lokalen Stammpfad, indem Sie auf das Verzeichnis verweisen, das Ihren enthält. TypeScript handler file

    Anmerkung

    TypeScript handler fileHier legen Sie Ihre Debugging-Haltepunkte fest.

  6. Erweitern Sie die zusätzlichen Konfigurationseinstellungen für Remote-Debugging.

  7. Aktivieren Sie die Quellzuordnung, indem Sie das Kontrollkästchen Quellzuordnung aktivieren.

  8. Stellen Sie das Feld Out-Dateien auf das lokale Verzeichnis Ihrer Lambda-Funktionskopie ein.

    Beispiel

    Wenn app.js und drin app.map sind.aws-sam/build/HelloWorldFunction, legen Sie den Speicherort /Users/user/project/aws-sam/build/HelloWorldFunction/* für die Out-Dateien fest.

    Anmerkung

    Der Pfad zur Ausgabedatei sollte ein absoluter Pfad sein.

    Für AWS CDK Projekte AWS SAM und Projekte unterstützt das AWS Toolkit die automatische Erkennung von Quellzuordnungen. Wenn das Feld Ausgangsdateien für diese Projekte leer gelassen wird, versucht das Toolkit automatisch, den Standort der Quellkarte zu ermitteln.

  9. Wenn Sie mit den Einstellungen zufrieden sind, wählen Sie die Schaltfläche Fernaufruf, um mit dem Debuggen Ihrer Funktion zu beginnen. TypeScript

Problembehandlung und Anwendungsfälle für Fortgeschrittene

Wenn Ihre Debug-Sitzung fehlschlägt, starten Sie den Fehlerbehebungsprozess, indem Sie diese Schritte ausführen.

  1. Aktualisieren Sie das AWS Toolkit auf die neueste Version.

  2. Aktualisieren Sie die Webansicht, indem Sie die Webansicht für die Konfiguration per Fernzugriff schließen und erneut öffnen.

  3. Starten Sie VS Code neu, indem Sie es vollständig schließen und erneut öffnen.

  4. Öffnen Sie die VS Code-Befehlspalette und geben Sie den Befehl ein. Wählen Sie ihn ausAWS: Reset Lambda Remote Debugging Snapshot, wenn die Ergebnisse angezeigt werden, um Ihren Lambda-Remote-Debugging-Snapshot zurückzusetzen.

  5. Wenn Sie das Problem nicht beheben können, senden Sie ein Problem an Issues. AWS Toolkit for Visual Studio Code GitHub

Erweiterter Anwendungsfall: Konfiguration der Codesignatur

Für das Remote-Debugging muss Ihrer Lambda-Funktion eine Debug-Ebene angehängt werden. Wenn für Ihre Funktion die Codesignaturkonfiguration aktiviert und erzwungen ist, kann das AWS Toolkit die Debug-Ebene nicht automatisch an Ihre Funktion anhängen.

Es gibt zwei Möglichkeiten, das Problem mit der Codesignaturkonfiguration zu lösen.

  • Entfernen Sie vorübergehend die Codesignatur.

  • Verwenden Sie eine signierte Debug-Ebene.

Vorübergehendes Entfernen der Codesignatur

Aktualisieren Sie die Codesignaturkonfiguration, indem Sie sie einstellenUntrustedArtifactOnDeployment : Warn, und aktivieren Sie sie Enforced nach Abschluss des Debugging-Vorgangs wieder auf.

Weitere Informationen finden Sie in der UpdateCodeSigningConfig Referenz in der API-Referenz. AWS Lambda

Verwenden einer signierten Debug-Ebene

  1. Erweitern Sie im AWS Toolkit unter Lambda-Remote-Debugging den Abschnitt Zusätzliche Konfiguration für Remote-Debugging.

  2. Kopieren Sie im Abschnitt zur zusätzlichen Konfiguration für das Remote-Debuggen Ihren Region-Layer-ARN aus dem Feld Layer-Override.

  3. Verwenden Sie von dort aus den folgenden Befehl AWS CLI, um die Layer-Version herunterzuladenaws lambda get-layer-version-by-arn --arn layer-arn, und ersetzen Sie layer-arn durch Ihren Layer-ARN. Eine ausführliche Anleitung zum Herunterladen des signierten Debug-Layers finden Sie in der Referenz https://docs.aws.amazon.com/cli/latest/reference/lambda/get-layer-version-by-arn.html get-layer-version-by-arn in der Befehlsreferenz. AWS CLI

  4. Signieren Sie den Layer mit Ihrer Code-Signing-Konfiguration und veröffentlichen Sie ihn in Ihrem Konto. Anleitungen zum Signieren und Veröffentlichen finden Sie im Thema „Codesignatur für Ihre AWS SAM Anwendung einrichten“ im AWS Serverless Application Model Entwicklerhandbuch.

  5. Nachdem der Layer signiert und in Ihrem Konto veröffentlicht wurde, kehren Sie im Lambda-Remote-Debugging zum Abschnitt Zusätzliche Konfiguration für Remote-Debugging zurück und geben Sie dann den neuen Layer-ARN in das Feld Layer-Override ein. Wenn der Vorgang abgeschlossen ist, verwendet das Lambda-Remote-Debugging Ihre signierte Ebene anstelle der Standard-Ebene.

Erweiterter Anwendungsfall: Debugging-Funktionen mit SnapStart oder bereitgestellter Parallelität

Bei Lambda-Funktionen, die mit Parallelität konfiguriert SnapStart oder bereitgestellt wurden, nimmt die Veröffentlichung einer neuen Version deutlich mehr Zeit in Anspruch. Um Ihren Debugging-Workflow zu beschleunigen, können Sie das Lambda-Remote-Debugging so konfigurieren, dass nur die $LATEST Version Ihrer Funktion aktualisiert wird, anstatt eine neue Version zu veröffentlichen.

  1. Erweitern Sie auf dem Konfigurationsbildschirm für den Remote-Aufruf die zusätzlichen Konfigurationseinstellungen für das Remote-Debuggen.

  2. Deaktivieren Sie die Option Version veröffentlichen.

  3. Das AWS Toolkit aktualisiert jetzt nur noch die $LATEST Version Ihrer Funktion und debuggt sie damit.

Anmerkung

Als Nebeneffekt des Debuggens mit der $LATEST Version sollten Sie anderen Datenverkehr vermeiden, der Ihre $LATEST Version aufrufen könnte, um eine ungestörte Debugging-Umgebung zu gewährleisten.

Unterstützte -Regionen

Der folgende Fehler tritt auf, wenn eine Region das Remote-Debugging nicht unterstützt.

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

Im Folgenden finden Sie eine Liste der unterstützten Regionen.

  • 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

Lambda-Funktionen haben ein Limit von 5 Ebenen und ein kombiniertes Limit von 250 MB für den Funktionscode und alle angehängten Ebenen. Die Remote-Debugging-Ebene ist ungefähr 40 MB groß, was dazu führen kann, dass Ihre Funktion diese Grenze überschreitet, wenn Sie ein großes Funktionspaket oder mehrere Ebenen haben. Weitere Informationen finden Sie im RequestEntityTooLargeException Abschnitt Lambda: InvalidParameterValueException or im Developer Guide. AWS Lambda

In der folgenden Liste werden Möglichkeiten zur Behebung und Behebung dieses Fehlers beschrieben.

  • Funktionsgröße reduzieren: Optimieren Sie Ihren Funktionscode und entfernen Sie unnötige Abhängigkeiten.

  • Unbenutzte Ebenen entfernen: Entfernen Sie beim Debuggen vorübergehend unwichtige Ebenen.

  • Verwenden Sie externe Abhängigkeiten: Verschieben Sie große Abhängigkeiten in einen externen Speicher wie Amazon S3 und laden Sie sie zur Laufzeit.

Fehlerbehebung beim Java-Debugging

Um eine Java-Lambda-Funktion zu debuggen, muss dieselbe Java-Version lokal installiert sein, die der Laufzeitversion Ihrer Lambda-Funktion entspricht.

Wenn Sie beispielsweise eine Java 25-Funktion debuggen, müssen Sie Java 25 in Ihrer lokalen Umgebung installiert haben, in der das AWS Toolkit ausgeführt wird. Wenn Sie versuchen, eine Java 2.5-Funktion zu debuggen, während Java 21 oder eine frühere Version lokal installiert ist, kann das Remote-Debugging nicht an den von Ihnen festgelegten Breakpoints beendet werden.

Stellen Sie sicher, dass Ihre lokale Java-Version mit der Laufzeitversion Ihrer Lambda-Funktion übereinstimmt, bevor Sie eine Debugging-Sitzung starten.

Das Kontingent für sicheres IoT-Tunneling wurde überschritten

Im Folgenden finden Sie ein Beispiel für den Fehler „Tunnelquote überschritten“, der auftritt, wenn Sie das Tageslimit für AWS IoT sichere Tunnelverbindungen im Lambda-Remote-Debugging erreicht haben.

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

AWS IoT Sichere Tunneling-Verbindungen haben die folgenden Kontingente:

  • Free-tier Für sicheres IoT-Tunneling sind 10 Verbindungen pro Tag vorgesehen.

  • Jeder Tunnel unterstützt eine VS Code-Instanz für bis zu 12 Stunden.

  • Das Kontingent gilt pro AWS Konto und Tag.

Wenn der AWS IoT Secure Tunneling-Fehler auftritt, warten Sie, bis das tägliche Kontingent zurückgesetzt wird, oder wenden Sie sich an den AWS Support, um eine Erhöhung des Kontingentlimits anzufordern. Kontaktinformationen für den AWS Support finden Sie im Support-Kontaktportal. AWS Ausführliche Informationen zu AWS IoT sicherem Tunneling finden Sie im Thema AWS IoT sicheres Tunneling im Entwicklerhandbuch. AWS IoT