AWS Lambda debug remoto

Ti AWS Toolkit for Visual Studio Code consente di eseguire il debug AWS Lambda delle funzioni in esecuzione nel cloud, direttamente in VS Code. Con il debug AWS Lambda remoto puoi ispezionare le funzioni in esecuzione, impostare punti di interruzione, esaminare le variabili e eseguire il debug dettagliato senza modificare il flusso di lavoro di sviluppo esistente.

Le sezioni seguenti descrivono come lavorare con il debug remoto Lambda in. AWS Toolkit for Visual Studio Code

Come funziona il debug remoto Lambda

Il AWS Toolkit consente il debug remoto modificando temporaneamente le funzioni Lambda con un livello di debug Lambda aggiuntivo ed estendendo il limite di timeout di invocazione Lambda a 900 secondi. Viene stabilita una connessione sicura tra il debugger locale e l'ambiente di runtime Lambda utilizzando Secure Tunneling. AWS IoT Questa connessione consente di utilizzare i punti di interruzione del codice locale per esaminare la funzione mentre viene eseguita in remoto. Al termine della sessione di debug, tutte le modifiche temporanee vengono ripristinate automaticamente alle impostazioni originali.

Nozioni di base

Runtime supportati

I seguenti runtime sono supportati dal debug remoto Lambda.

• Python (Amazon Linux 2023)

• Java

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

Nota

Le istanze gestite da Lambda e i tipi di funzione di immagine OCI non sono supportati dal debug remoto Lambda.

Prerequisiti

Prima di iniziare, è necessario soddisfare i seguenti prerequisiti.

• È necessario disporre di AWS credenziali valide configurate nel Toolkit. AWS Per ulteriori dettagli sull'installazione del AWS Toolkit e sulla configurazione delle credenziali, consulta l'argomento Guida introduttiva in questa guida per l'utente.

• Una funzione Lambda è stata implementata nel tuo account. AWS Per dettagli sull'implementazione di una funzione Lambda, consulta l'argomento Crea la tua prima funzione Lambda nella Developer Guide. AWS Lambda

• È necessario disporre di policy e autorizzazioni AWS Identity and Access Management (IAM) appropriate per eseguire il debug della funzione. Per ulteriori dettagli sulle autorizzazioni Lambda, consulta le politiche AWS gestite per l' AWS Lambdaargomento nella Developer Guide. AWS Lambda Di seguito è riportato un esempio di policy che contiene le autorizzazioni minime richieste per lavorare con il debugging remoto Lambda nel Toolkit. AWS

  Nota

  Il debug remoto è abilitato tramite Secure Tunneling. AWS AWS IoT Ciò consente al debugger locale di stabilire una connessione sicura all'ambiente di runtime 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": "*"
      }
    ]
  }
                      

Accesso al debug remoto Lambda

Esistono due percorsi principali per accedere al debug remoto Lambda nel AWS Toolkit: explorer o Application Builder explorer. AWS Dall' AWS explorer, puoi accedere al debug remoto di Lambda tramite i tuoi nodi. AWS Lambda Dall'Application Builder explorer, puoi accedere al debug remoto di Lambda tramite i tuoi progetti locali. AWS SAM

Accesso al debug remoto di Lambda da AWS esploratore

1. Da VS Code, apri l'estensione AWS Toolkit.

2. Dal AWS Toolkit, espandi l' AWS explorer.

3. Dall'explorer, espandi il nodo Lambda.

4. Passa alla funzione di cui desideri eseguire il debug, quindi scegli l'icona Invoke remotely dal menu contestuale per aprire la schermata di configurazione Remote invoke.

Accesso al debug remoto di Lambda dall'Application Builder explorer.

1. Da VS Code, apri l'estensione Toolkit. AWS

2. Dal AWS Toolkit, espandi l'Application Builder Explorer.

3. Dall'explorer espandi il AWS SAM progetto che contiene il progetto Lambda di cui desideri eseguire il debug.

4. Espandi la Lambda funzione distribuita di cui desideri eseguire il debug.

5. Passa alla funzione remota, quindi scegli l'icona Invoke remotely dal menu contestuale per aprire la schermata di configurazione Remote Invoke.

Lavorare con il debug remoto Lambda

Le sezioni seguenti descrivono come utilizzare il debug remoto Lambda in. AWS Toolkit for Visual Studio Code

Nota

Le funzioni Lambda hanno un limite di 5 livelli e un limite combinato di 250 MB per il codice funzione e tutti i livelli collegati. Il debug remoto Lambda richiede almeno 1 livello gratuito per essere eseguito.

Configurare una sessione di debug

Prima di iniziare, configura la sessione di debug completando la seguente procedura.

1. Apri il menu di configurazione Remote invoke completando la procedura Accessing Lambda remote debugging from the AWS explorer o Accessing Lambda remote debugging from the Application Builder explorer, disponibile nella sezione precedente.

2. Dal menu di configurazione Remote invoke, seleziona la casella di controllo Remote Debugging per visualizzare le proprietà di debug remoto.

3. Specificate il percorso principale locale del file del gestore locale.

   Nota

   Il percorso root locale è la posizione del codice sorgente che corrisponde alla funzione Lambda distribuita. Se lavori da una funzione distribuita nell'Application Builder explorer, il tuo percorso root locale viene rilevato automaticamente.

   Se il codice sorgente non è memorizzato localmente, scegli il pulsante Scarica codice remoto per recuperare il codice sorgente della funzione Lambda. Si aprirà l'editor handler file di VS Code.

4. Dalla sezione Payload, specifica dove vengono ottenuti i dati dell'evento di test.

Impostazione dei punti di interruzione e debug

Imposta i punti di interruzione e inizia il debug completando la seguente procedura.

1. handler fileNell'editor di VS Code, fai clic sul margine del bordo per impostare i punti di interruzione in corrispondenza dei numeri di riga in cui desideri sospendere il debug.

2. Quando sei soddisfatto dei punti di interruzione, torna al menu di configurazione Remote invoke per verificare che le impostazioni siano configurate correttamente, quindi scegli il pulsante Remote invoke per avviare il debug.

3. Il AWS Toolkit aggiorna la funzione Lambda con funzionalità di debug, stabilisce un tunnel sicuro per la sessione di debug, richiama la funzione con il payload specificato, quindi sospende il processo quando raggiunge un punto di interruzione.

4. In caso di pausa, usa il riquadro RUN AND DEBUG per visualizzare VARIABLES, CALL STACK e BREAKPOINTS.

Aggiornamento e test della funzione

Per modificare il codice e testare le modifiche con una distribuzione rapida, completa la seguente procedura.

1. Con la sessione di debug attiva, apporta modifiche al tuo editor handler file di codice VS.

2. Salva le modifiche (,) Command+S on macOS Ctrl+S on Windows

3. Quando richiesto, conferma che desideri procedere con l'implementazione delle modifiche. Il AWS Toolkit aggiornerà la funzione Lambda con il codice modificato.

4. Continua a eseguire il debug e a testare le modifiche impostando nuovi punti di interruzione e selezionando nuovamente il pulsante Remote invoke.

   Nota

   In alternativa, puoi deselezionare l'opzione Attach debugger nei controlli di debug di VS Code e scegliere il pulsante Remote invoke per eseguire la funzione senza eseguire il debug.

Termine di una sessione di debug

Ognuna delle seguenti opzioni termina la sessione di debug remota e rimuove il livello di debug dal progetto.

• Scegliendo l'opzione Remove Debug Setup dalla schermata di configurazione Remote invoke.

• Scelta dell'icona di disconnessione dai controlli di debug di VS Code.

• Chiusura dell'editor handler file di VS Code.

Nota

Prendi nota di quanto segue:

• Il livello di debug Lambda viene rimosso automaticamente dopo 60 secondi di inattività. Il conteggio inizia quando l'ultima invocazione è completa.

• Se hai apportato modifiche al codice alle funzioni gestite da infrastructure-as-code (IaC) (,, Terraform) durante il processo di debug AWS SAM AWS CDK, salvale nel tuo progetto locale e valuta la possibilità di aggiornare il tuo repository di controllo del codice sorgente. Le modifiche non salvate vengono sovrascritte quando la funzione IaC viene ridistribuita.

• Se hai apportato modifiche temporanee solo a scopo di debug, potresti voler ridistribuire la funzione dal controllo del codice sorgente per assicurarti che corrisponda al codice di produzione.

Debug delle funzioni TypeScript Lambda con le mappe dei sorgenti

Le sezioni seguenti descrivono come eseguire il debug delle funzioni TypeScript Lambda con le mappe di origine.

Prerequisiti

Per eseguire il debug delle funzioni TypeScript Lambda, devono essere soddisfatti i seguenti prerequisiti.

• Il tuo TypeScript deve essere compilato con l'opzione della mappa sorgente abilitata. Per ulteriori informazioni, consulta l'argomento relativo al supporto delle mappe di JavaScript origine nella documentazione di VS Code.

• In-line le mappe di origine non sono supportate. È necessario utilizzare un .js.map file separato per memorizzare la mappa di origine.

Configurazione

Per configurare il debug remoto Lambda per le funzioni TypeScript Lambda nel AWS Toolkit, completa i seguenti passaggi.

1. Dal AWS Toolkit, espandi l'explorer. AWS

2. Dall'explorer, espandi il nodo Lambda.

3. Vai alla funzione per cui desideri configurare TypeScript, quindi scegli l'icona Invoke remotely dal menu contestuale per aprire la schermata di configurazione Remote Invoke.

4. Abilita il debug remoto selezionando la casella di controllo Debug remoto.

5. Configura il tuo percorso principale locale puntando alla directory contenente il tuo. TypeScript handler file

   Nota

   TypeScript handler fileÈ qui che imposti i punti di interruzione del debug.

6. Espandi le impostazioni di configurazione aggiuntive di debug remoto.

7. Abilita la mappatura del codice sorgente selezionando la casella di controllo Mappa sorgente.

8. Imposta il campo Out files sulla directory locale della copia della funzione Lambda.

   Esempio

   Se app.js e app.map sono presenti.aws-sam/build/HelloWorldFunction, crea la posizione /Users/user/project/aws-sam/build/HelloWorldFunction/* dei file Out.

   Nota

   Il percorso del file Out deve essere un percorso assoluto.

   Per tutti AWS SAM i AWS CDK progetti, il AWS Toolkit supporta il rilevamento automatico delle mappe di origine. Se il campo Out files viene lasciato vuoto per questi progetti, il toolkit tenterà automaticamente di rilevare la posizione della mappa di origine.

9. Quando sei soddisfatto delle impostazioni, scegli il pulsante Remote invoke per iniziare il debug della funzione. TypeScript

Risoluzione dei problemi e casi d'uso avanzati

Se la sessione di debug non riesce, avvia il processo di risoluzione dei problemi completando questi passaggi.

1. Aggiorna il AWS Toolkit alla versione più recente.

2. Aggiorna la visualizzazione Web chiudendo la vista web di configurazione Remote Invoke e riaprendola.

3. Riavvia VS Code chiudendolo completamente e riaprendolo.

4. Apri la palette dei comandi di VS Code e inserisci il comandoAWS: Reset Lambda Remote Debugging Snapshot, selezionalo quando compila i risultati per reimpostare l'istantanea di debug remoto Lambda.

5. Se non riesci a risolvere il problema, invia un problema a Problemi. AWS Toolkit for Visual Studio Code GitHub

Caso d'uso avanzato: configurazione con firma del codice

Il debug remoto richiede l'aggiunta di un livello di debug alla funzione Lambda. Se la configurazione della firma del codice nella tua funzione è abilitata e applicata, il AWS Toolkit non può collegare automaticamente il livello di debug alla tua funzione.

Esistono due opzioni per risolvere il problema di configurazione della firma del codice.

• Rimuovere temporaneamente la firma del codice.

• Usa un livello di debug firmato.

Rimozione temporanea della firma del codice

Aggiorna la configurazione della firma del codice impostandolaUntrustedArtifactOnDeployment : Warn, quindi riattivala al Enforced termine del processo di debug.

Per ulteriori informazioni, consulta il UpdateCodeSigningConfig riferimento nell'API Reference. AWS Lambda

Utilizzo di un livello di debug firmato

1. Dal debug remoto Lambda nel AWS Toolkit, espandi la sezione di configurazione aggiuntiva per il debug remoto.

2. Dalla sezione di configurazione aggiuntiva per il debug remoto, copia l'ARN del livello regionale dal campo Layer override.

3. Da AWS CLI, usa il seguente comando per scaricare la versione del layeraws lambda get-layer-version-by-arn --arn layer-arn, sostituendo layer-arn con il tuo layer ARN. Per istruzioni dettagliate su come scaricare il layer di debug firmato, vedete il riferimento https://docs.aws.amazon.com/cli/latest/reference/lambda/get-layer-version-by-arn.html get-layer-version-by-arn nel Command Reference. AWS CLI

4. Firma il layer con la tua configurazione per la firma del codice e pubblicalo sul tuo account. Per indicazioni sulla firma e sulla pubblicazione, consulta l'argomento Configurazione della firma del codice per la tua AWS SAM applicazione nella Guida per gli AWS Serverless Application Model sviluppatori.

5. Dopo che il layer è stato firmato e pubblicato sul tuo account, torna alla sezione di configurazione aggiuntiva di Remote Debug di Lambda remote debugging, quindi inserisci il nuovo livello ARN nel campo Layer override. Una volta completato il processo, il debug remoto Lambda utilizza il livello firmato anziché il livello predefinito.

Caso d'uso avanzato: funzioni di debug con o con provisioning simultaneo SnapStart

Per le funzioni Lambda configurate SnapStart o su cui è stato eseguito il provisioning della concorrenza, la pubblicazione di una nuova versione richiede molto più tempo. Per velocizzare il flusso di lavoro di debug, puoi configurare il debug remoto Lambda per aggiornare solo la $LATEST versione della tua funzione invece di pubblicarne una nuova.

1. Dalla schermata di configurazione Remote invoke, espandi le impostazioni di configurazione aggiuntive di Remote debug.

2. Deseleziona l'opzione Pubblica versione.

3. Il AWS Toolkit ora aggiornerà solo la $LATEST versione della funzione ed eseguirà il debug utilizzandola.

Nota

Come effetto collaterale del debug con la $LATEST versione, dovresti evitare altro traffico che potrebbe richiamare la tua $LATEST versione per garantire un ambiente di debug indisturbato.

Regioni supportate

L'errore seguente si verifica quando una regione non supporta il debug remoto.

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

Di seguito è riportato un elenco delle regioni supportate.

• 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

Le funzioni Lambda hanno un limite di 5 livelli e un limite combinato di 250 MB per il codice funzione e tutti i livelli collegati. Il livello di debug remoto è di circa 40 MB, il che può far sì che la funzione superi questo limite se si dispone di un pacchetto di funzioni di grandi dimensioni o più livelli. Per ulteriori dettagli, consulta la sezione Lambda: InvalidParameterValueException or RequestEntityTooLargeException topic nella Developer Guide. AWS Lambda

L'elenco seguente descrive i modi per risolvere e correggere questo errore.

• Riduci le dimensioni della funzione: ottimizza il codice della funzione ed elimina le dipendenze non necessarie.

• Rimuovi i livelli inutilizzati: rimuovi temporaneamente i livelli non essenziali durante il debug.

• Usa dipendenze esterne: sposta dipendenze di grandi dimensioni su uno storage esterno, come Amazon S3, e caricale in fase di esecuzione.

Risoluzione dei problemi relativi al debug in Java

Per eseguire il debug di una funzione Java Lambda, è necessario che sia installata localmente la stessa versione di Java corrispondente alla versione di runtime della funzione Lambda.

Ad esempio, quando si esegue il debug di una funzione Java 25, è necessario che Java 25 sia installato nell'ambiente locale in cui è in esecuzione il Toolkit. AWS Se si tenta di eseguire il debug di una funzione Java 25 con Java 21 o una versione precedente installata localmente, il debug remoto non potrà arrestarsi nei punti di interruzione impostati.

Assicurati che la versione Java locale corrisponda alla versione di runtime della funzione Lambda prima di iniziare una sessione di debug.

È stata superata la quota di tunneling sicuro dell'IoT

Di seguito è riportato un esempio dell'errore di superamento della quota del tunnel che si verifica quando si raggiunge il limite giornaliero per le connessioni di tunneling AWS IoT sicure nel debug remoto Lambda.

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

AWS IoT Le connessioni Secure Tunneling hanno le seguenti quote:

• Free-tier Al tunneling sicuro IoT sono assegnate 10 connessioni al giorno.

• Ogni tunnel supporta un'istanza VS Code per un massimo di 12 ore.

• La quota si applica per AWS account, al giorno.

Se riscontri l'errore di AWS IoT secure tunneling, attendi il ripristino della quota giornaliera o contatta l' AWS assistenza per richiedere un aumento del limite di quota. Per informazioni di contatto dell' AWS assistenza, consulta il portale di contatto dell'AWS assistenza. Per informazioni dettagliate sul tunneling AWS IoT sicuro, consulta l'argomento sul tunneling AWS IoT sicuro nella Guida per gli sviluppatori. AWS IoT