Test e debug delle funzioni Lambda@Edge - Amazon CloudFront
Test delle funzioni Lambda@EdgeIdentificazione degli errori di funzione Lambda@Edge in CloudFrontRisoluzione dei problemi relativi alle risposte non valide della funzione Lambda@Edge (errori di convalida)Risoluzione dei problemi relativi agli errori di esecuzione della funzione Lambda@Edge Determinazione della regione Lambda@EdgeDeterminare se l’account invia i log a CloudWatch

Test e debug delle funzioni Lambda@Edge

È importante verificare il codice di una funzione Lambda@Edge autonoma per assicurarsi che venga completata l'attività, ed eseguire i test di integrazione, per fare in modo che la funzione lavori correttamente con CloudFront.

Durante i test di integrazione o dopo che la tua funzione è stata distribuita, potrebbe essere necessario eseguire il debug degli errori di CloudFront, ad esempio gli errori HTTP 5xx. Gli errori possono essere una risposta non valida restituita dalla funzione Lambda, gli errori di esecuzione quando la funzione è attivata, oppure gli errori dovuti al throttling di esecuzione da parte del servizio Lambda. Le sezioni in questo argomento condividono le strategie per determinare quale tipo di errore è il problema, e quindi quale procedura adottare per risolvere il problema.

Nota

Quando si esaminano i file di log o le metriche di CloudWatch durante la risoluzione dei problemi, tieni presente che questi vengono visualizzati o memorizzati nella Regione AWS più vicina alla posizione in cui la funzione è stata eseguita. Pertanto, se, ad esempio, disponi di un sito o di un’applicazione web con utenti nel Regno Unito e disponi di una funzione Lambda associata alla distribuzione, devi modificare la Regione per visualizzare le metriche CloudWatch o i file di log per la Regione AWS di Londra. Per ulteriori informazioni, consulta Determinazione della regione Lambda@Edge.

Test delle funzioni Lambda@Edge

Sono disponibili due fasi per il test della funzione Lambda: test autonomo e test di integrazione.

Test di funzionalità autonoma

Prima di aggiungere la funzione Lambda a CloudFront, assicurati di verificare prima la funzionalità, utilizzando la funzionalità di test nella console Lambda o utilizzando altri metodi. Per ulteriori informazioni sul test nella console Lambda, consulta Invocare una funzione Lambda utilizzando la console nella Guida per gli sviluppatori di AWS Lambda.

Testa le attività della tua funzione in CloudFront

È importante per completare i test di integrazione, dove la tua funzione è associata a una distribuzione e viene eseguita in base a un evento CloudFront. Verifica che la funzione sia attivata per l'evento corretto e restituisca una risposta valida e corretta per CloudFront. Ad esempio, verifica che la struttura dell’evento sia corretta, che siano incluse solo le intestazioni valide e così via.

Quando effettui le iterazioni sul test di integrazione con la tua funzione nella console Lambda, fai riferimento alle fasi nel tutorial Lambda@Edge per modificare il codice o il trigger CloudFront che chiama la tua funzione. Ad esempio, assicurati che si stia utilizzando una versione numerata della tua funzione, come descritto in questa fase del tutorial: Fase 4: aggiungere un trigger CloudFront per eseguire la funzione.

Quando esegui delle modifiche e le distribuisci, ricorda che saranno necessari alcuni minuti per fare in modo che la tua funzione aggiornata e i trigger CloudFront vengano replicati in tutte le regioni. Questa operazione di solito richiede alcuni minuti, in alcuni casi fino a 15.

È possibile controllare se la replica è terminata accedendo alla console CloudFront e visualizzando la distribuzione:

Come verificare se l’implementazione della replica è terminata

  1. Aprire la console CloudFront all'indirizzo https://console.aws.amazon.com/cloudfront/v4/home.

  2. Scegli il nome della distribuzione.

  3. Controlla che lo stato della distribuzione torni da In Progress (In corso) a Deployed (Implementato), il che significa che la funzione è stata replicata. Quindi segui la procedura nella sezione successiva per verificare che la funzione sia attiva.

Tieni presente che il test nella console convalida solo la logica della funzione e non applica quote di servizio (precedentemente note come limiti) specifiche di Lambda@Edge.

Identificazione degli errori di funzione Lambda@Edge in CloudFront

Dopo aver verificato che la logica della funzione opera correttamente, è possibile comunque visualizzare gli errori HTTP 5xx quando la funzione viene eseguita in CloudFront. Gli errori HTTP 5xx possono essere restituiti per diversi motivi, che possono includere errori della funzione Lambda o altri problemi in CloudFront.

  • Se utilizzi funzioni Lambda@Edge, puoi utilizzare i grafici nella console di CloudFront per individuare la causa dell'errore e quindi correggerlo. Ad esempio, puoi vedere se gli errori HTTP 5xx sono causati da CloudFront o da funzioni Lambda e quindi, per funzioni specifiche, visualizzare i file di log correlati per analizzare il problema.

  • Per risolvere gli errori HTTP in generale in CloudFront, consulta la procedura di risoluzione dei problemi nell'argomento seguente: Risoluzione dei problemi relativi ai codici di stato di risposta di errore in CloudFront.

Quali sono le cause degli errori di funzione Lambda@Edge in CloudFront

Ci sono vari motivi per cui una funzione Lambda potrebbe causare un errore HTTP 5xx e i passaggi di risoluzione dei problemi da eseguire variano a seconda del tipo di errore. Gli errori possono essere classificati come riportato di seguito:

Un errore di esecuzione della funzione Lambda

Un errore di esecuzione si verifica quando CloudFront non riceve una risposta da Lambda perché ci sono eccezioni non gestite nella funzione o si verifica un errore nel codice. Ad esempio, se il codice include callback (Error).

Una risposta della funzione Lambda non valida viene restituita a CloudFront

Dopo l'esecuzione della funzione, CloudFront riceve una risposta da Lambda. Si verifica un errore nel caso in cui la struttura dell'oggetto della risposta non è conforme a Struttura dell'evento Lambda@Edge, oppure la risposta contiene le intestazioni non valide o altri campi non validi.

L'esecuzione in CloudFront è limitata a causa delle quote di servizio Lambda (precedentemente note come limiti)

Il servizio Lambda limita le esecuzioni in ciascuna regione e restituisce un errore se si supera la quota. Per ulteriori informazioni, consulta Quote di Lambda@Edge.

Come stabilire il tipo di errore

Scoprire perché CloudFront restituisce un errore HTTP può aiutarti a decidere dove concentrarti per eseguire il debug e risolvere gli errori restituiti da CloudFront. Per iniziare, puoi utilizzare i grafici forniti nella sezione Monitoraggio della console CloudFront nella Console di gestione AWS. Per ulteriori informazioni sulla visualizzazione di grafici nella sezione Monitoraggio della console CloudFront, consulta Monitoraggio delle metriche CloudFront con Amazon CloudWatch.

I seguenti grafici possono essere particolarmente utili quando desideri stabilire se gli errori vengono restituiti da origini o da una funzione Lambda e limitare il tipo di problema quando si tratta di un errore di una funzione Lambda.

Grafico delle percentuali di errore

Uno dei grafici che puoi visualizzare nella scheda Overview (Panoramica) per ciascuna delle distribuzioni è un grafico Error rates (Percentuali di errore). Questo grafico visualizza la percentuale di errori come una percentuale di richieste totali pervenute alla distribuzione. Il grafico mostra la percentuale di errori totale, gli errori 4xx totali, gli errori 5xx totali e gli errori 5xx totali da funzioni Lambda. In base al tipo di errore e al volume, puoi eseguire fasi per individuare e risolvere la causa.

Grafico della percentuale di errori per una distribuzione CloudFront

  • Se sono visibili errori Lambda, puoi indagare ulteriormente osservando i tipi di errori specifici restituiti dalla funzione. La scheda Lambda@Edge errors (Errori Lambda@Edge) include grafici che classificano errori di funzioni in base al tipo per individuare il problema per una funzione specifica.

  • Se sono presenti errori CloudFront, puoi risolvere i problemi e lavorare per risolvere gli errori di origine o modificare la configurazione CloudFront. Per ulteriori informazioni, consulta Risoluzione dei problemi relativi ai codici di stato di risposta di errore in CloudFront.

Errori di esecuzione e grafici delle rispose di funzione non validi

La scheda Lambda@Edge errors (Errori Lambda@Edge) include grafici che classificano gli errori Lambda@Edge per una distribuzione specifica, in base al tipo. Ad esempio, un grafico mostra tutti gli errori di esecuzione in base alla Regione AWS.

Per semplificare la risoluzione dei problemi, puoi cercare problemi specifici aprendo ed esaminando i file di log per funzioni specifiche in base alla regione.

Come visualizzare i file di log per una funzione specifica in base alla regione

  1. Nella scheda Errori Lambda@Edge, in Funzioni Lambda@Edge associate, scegli il nome della funzione, quindi seleziona Visualizza metriche.

  2. Nella pagina con il nome della funzione, nell’angolo in alto a destra, scegli Visualizza log delle funzioni, quindi seleziona una regione.

    Ad esempio, se visualizzi problemi nel grafico Errori per la regione Stati Uniti occidentali (Oregon), scegli tale regione dall’elenco a discesa. Viene aperta la console Amazon CloudWatch.

  3. Nella console CloudWatch per tale Regione, in Flussi di log, scegli un flusso di log per visualizzare gli eventi per la funzione.

Inoltre, leggi le seguenti sezioni in questo capitolo per ulteriori suggerimenti sulla risoluzione dei problemi e la correzione degli errori.

Grafico di throttling

La scheda Lambda@Edge errors (Errori Lambda@Edge) include anche un grafico Throttles (Throttle). Talvolta, il servizio Lambda limita le invocazioni della funzione in base alla regione, se raggiungi la quota (precedentemente nota come limite) di simultaneità regionale. Se viene visualizzato un errore di superamento del limite, la tua funzione ha raggiunto una quota che il servizio Lambda impone sulle esecuzioni in una regione. Per ulteriori informazioni su come richiedere un aumento della quota, consulta Quote di Lambda@Edge.

Grafico di limitazione (della larghezza di banda della rete) per l’esecuzione della funzione Lambda@Edge.

Per un esempio su come utilizzare queste informazioni nella risoluzione di errori HTTP, consulta Quattro fasi per il debug della distribuzione di contenuti su AWS.

Risoluzione dei problemi relativi alle risposte non valide della funzione Lambda@Edge (errori di convalida)

Se identifichi che il problema è un errore di convalida di Lambda, significa che la tua funzione restituisce una risposta non valida a CloudFront. Segui le istruzioni in questa sezione per eseguire una procedura di revisione della funzione e accertarti che la tua risposta sia conforme ai requisiti CloudFront.

CloudFront convalida la risposta da una funzione Lambda in due modi:

  • La risposta Lambda deve rispettare la struttura richiesta dell'oggetto. Tra gli esempi di errata struttura dell'oggetto figurano i seguenti: JSON non analizzabile, campi obbligatori mancanti e un oggetto non valido nella risposta. Per ulteriori informazioni, consulta Struttura dell'evento Lambda@Edge.

  • La risposta deve includere solo i valori di oggetti validi. Si verifica un errore se la risposta include un oggetto valido ma con valori non supportati. Alcuni esempi sono i seguenti: l'aggiunta o l'aggiornamento di intestazioni inserite nella blacklist o di sola lettura (consulta Restrizioni sulle funzioni edge) che superano la dimensione del corpo massima (consulta Restrizioni sulla dimensione della risposta generata nell’argomento Lambda@Edge Errori) e caratteri o valori non validi (vedi Struttura dell'evento Lambda@Edge).

Quando Lambda restituisce una risposta non valida a CloudFront, i messaggi di errore vengono scritti nei file di registro che CloudFront invia a CloudWatch nella regione in cui viene eseguita la funzione Lambda. È il comportamento predefinito a inviare i file di log a CloudWatch quando c'è una risposta non valida. Tuttavia, se hai associato una funzione Lambda a CloudFront prima del rilascio della funzionalità, potrebbe non essere abilitata per la tua funzione. Per ulteriori informazioni, consulta Stabilire se l'account invia i log a CloudWatch più avanti in questo argomento.

CloudFront invia i file di log alla regione corrispondente in cui è stata eseguita la funzione, nel gruppo di log associato alla distribuzione. I gruppi di log hanno il seguente formato: /aws/cloudfront/LambdaEdge/DistributionId, dove DistributionId è l'ID della distribuzione. Per determinare la regione in cui è possibile trovare i file di log CloudWatch, vedi Stabilire la regione di Lambda@Edge più avanti in questo argomento.

Se l'errore è riproducibile, è possibile creare una nuova richiesta che porta all'errore e quindi trovare l'id della richiesta in una risposta CloudFront non riuscita (intestazione X-Amz-Cf-Id) per individuare un singolo errore nei file di log. La voce del file di log contiene informazioni che consentono di identificare perché l'errore viene restituito ed elenca anche l'id della richiesta Lambda corrispondente che permette di analizzare la causa principale nel contesto di una singola richiesta.

Se si verifica un errore intermittente, è possibile utilizzare i log di accesso CloudFront per trovare l'id della richiesta che non è andata a buon fine, quindi eseguire una ricerca in CloudWatch Logs per i messaggi di errore corrispondenti. Per ulteriori informazioni, consulta la sezione precedente, Determinazione del Tipo di fallimento.

Risoluzione dei problemi relativi agli errori di esecuzione della funzione Lambda@Edge

Se il problema è un errore di esecuzione di Lambda, può essere utile creare istruzioni di registrazione per le funzioni Lambda, scrivere messaggi a file di log CloudWatch in grado di monitorare l'esecuzione della funzione in CloudFront e determinare se funziona correttamente. Quindi è possibile cercare le istruzioni nei file di log di CloudWatch per verificare che la funzione stia lavorando correttamente.

Nota

Anche se non hai modificato la funzione Lambda@Edge, gli aggiornamenti per l'ambiente di esecuzione della funzione Lambda potrebbero influenzarla e potrebbero restituire un errore di esecuzione. Per ulteriori informazioni sui test e sulla migrazione a una versione più recente, consulta Prossimi aggiornamenti agli ambienti di esecuzione AWS Lambda e AWS Lambda@Edge.

Determinazione della regione Lambda@Edge

Per visualizzare le regioni in cui la funzione Lambda@Edge riceve il traffico, visualizza i grafici dei parametri per la funzione nella console CloudFront nella Console di gestione AWS. I parametri vengono visualizzati per ogni regione AWS. Nella stessa pagina, puoi scegliere una regione e visualizzare i file di log per tale regione, in modo da analizzare i problemi. È necessario esaminare i file di log CloudWatch nella regione AWS corretta per visualizzare i file di log creati quando CloudFront ha eseguito la funzione Lambda.

Per ulteriori informazioni sulla visualizzazione di grafici nella sezione Monitoraggio della console CloudFront, consulta Monitoraggio delle metriche CloudFront con Amazon CloudWatch.

Determinare se l’account invia i log a CloudWatch

Per impostazione predefinita, CloudFront abilita la registrazione delle risposte alle funzioni Lambda non valide e spinge i file di registro a CloudWatch utilizzando uno dei file di Ruoli collegati ai servizi per Lambda@Edge. Se si dispone di funzioni Lambda@Edge aggiunte a CloudFront prima del rilascio della funzione di log delle risposte non valide alla funzione Lambda, la registrazione viene abilitata al successivo aggiornamento della configurazione di Lambda@Edge aggiungendo, ad esempio, un trigger CloudFront.

È possibile verificare che l'invio dei file di log a CloudWatch sia abilitato per il tuo account eseguendo le operazioni seguenti:

  • Seleziona per vedere se i log vengono visualizzati in CloudWatch: assicurati di guardare nella Regione in cui è stata eseguita la funzione Lambda@Edge. Per ulteriori informazioni, consulta Determinazione della regione Lambda@Edge.

  • Verifica se il ruolo collegato al servizio correlato esiste nell’account in IAM: devi disporre del ruolo IAM AWSServiceRoleForCloudFrontLogger nell’account. Per ulteriori informazioni su questo ruolo, consulta Ruoli collegati ai servizi per Lambda@Edge.