Testen und Debuggen von Lambda@Edge-Funktionen

Dieses Thema enthält Abschnitte, die Strategien zum Testen und Debuggen von Lambda@Edge-Funktionen beschreiben. Es ist wichtig, Ihren Lambda@Edge-Funktionscode eigenständig zu testen, um sicherzustellen, dass er die beabsichtigte Aufgabe erfüllt. Sie müssen außerdem Integrationstests durchführen, um sicherzustellen, dass die Funktion mit CloudFront korrekt funktioniert.

Während des Integrationstests oder nach der Bereitstellung Ihrer Funktion müssen Sie möglicherweise CloudFront-Fehler, wie z. B. HTTP 5xx-Fehler, debuggen. Fehler können eine ungültige Antwort der Lambda-Funktion, Ausführungsfehler beim Auslösen der Funktion oder Fehler aufgrund einer Ablehnung der Ausführung durch den Lambda-Service sein. Die Abschnitte in diesem Thema enthalten Strategien, um festzustellen, welche Art von Fehler das Problem verursacht. Dazu finden Sie Schritte, die Sie unternehmen können, um das Problem zu beheben.

Anmerkung

Wenn Sie bei der Fehlerbehebung CloudWatch Log-Dateien oder -Metriken überprüfen, sollten Sie beachten, dass diese in der Region angezeigt oder gespeichert werden, die dem Standort am nächsten liegt, an dem die Funktion ausgeführt wurde. Wenn Sie eine Website oder Webanwendung mit Benutzern in Großbritannien haben und Sie beispielsweise eine Lambda-Funktion mit Ihrer Verteilung verknüpft haben, müssen Sie die Region ändern, um die CloudWatch-Metriken oder -Protokolldateien für die AWS-Region London anzuzeigen. Weitere Informationen finden Sie unter Bestimmen der Lambda@Edge-Region weiter unten in diesem Thema.

Testen der Lambda@Edge-Funktionen

Der Test Ihrer Lambda-Funktion besteht aus zwei Schritten: eigenständiger Test und Integrationstest.

Eigenständiger Test der Funktionalität

Bevor Sie Ihre Lambda-Funktion zu CloudFront hinzufügen, sollten Sie die Funktionalität zuerst mit den Testmöglichkeiten in der Lambda-Konsole oder mit anderen Methoden testen. Weitere Informationen über Testmöglichkeiten in der Lambda-Konsole finden Sie im Abschnitt Aufrufen der Lambda-Funktion und Überprüfen der Ergebnisse, Protokolle und Metriken unter Erstellen einer einfachen Lambda-Funktion mit der Konsole im AWS Lambda-Entwicklerhandbuch.

Testen der Funktionsoperation in CloudFront

Es ist wichtig, den Integrationstest abzuschließen, bei dem Ihre Funktion mit einer Verteilung verknüpft ist und für ein CloudFront-Ereignis ausgeführt wird. Stellen Sie sicher, dass die Funktion für das richtige Ereignis ausgelöst wird und eine für CloudFront gültige und korrekte Antwort zurückgibt. Achten Sie beispielsweise darauf, dass die Ereignisstruktur korrekt ist, dass nur gültige Header enthalten sind usw.

Lesen Sie zum Integrationstest Ihrer Funktion in der Lambda-Konsole die Schritte im Lambda@Edge-Tutorial, um Ihren Code oder den CloudFront-Auslöser zu ändern, der Ihre Funktion aufruft. Stellen Sie beispielsweise sicher, dass Sie mit einer nummerierten Version Ihrer Funktion arbeiten, wie in diesem Schritt des Tutorials beschrieben: Schritt 4: Hinzufügen eines CloudFront-Auslösers zum Ausführen der Funktion.

Wenn Sie Änderungen vornehmen und bereitstellen, beachten Sie, dass es einige Minuten dauert, bis sich Ihre aktualisierte Funktion und die CloudFront-Auslöser in allen Regionen repliziert haben. Dies dauert in der Regel wenige Minuten, kann jedoch auch bis zu 15 Minuten dauern.

Sie können überprüfen, ob die Replikation abgeschlossen ist, indem Sie die CloudFront-Konsole öffnen und sich Ihre Verteilung ansehen.

• Gehen Sie zur CloudFront-Konsole unter https://console.aws.amazon.com/cloudfront/v3/home.

Überprüfen Sie, ob sich der Status der Verteilung von InProgress (Läuft) zurück auf Deployed (Bereitgestellt) geändert hat, d.h. Ihre Funktion wurde repliziert. Anschließend befolgen Sie die Schritte im nächsten Abschnitt, um zu überprüfen, ob die Funktion funktioniert.

Beachten Sie, dass das Testen in der Konsole nur die Logik Ihrer Funktion validiert und keine Servicekontingente (früher als Limits bezeichnet) anwendet, die spezifisch für Lambda@Edge sind.

Identifizieren von Lambda@Edge-Funktionsfehlern in CloudFront

Nachdem Sie überprüft haben, dass Ihre Funktionslogik korrekt funktioniert, erhalten Sie möglicherweise weitere HTTP 5xx-Fehler, wenn Ihre Funktion in CloudFront ausgeführt wird. HTTP 5xx-Fehler können aus unterschiedlichen Gründen zurückgegeben werden. Dazu zählen Lambda-Funktionsfehler oder andere Probleme in CloudFront.

• Wenn Sie Lambda@Edge-Funktionen verwenden, können Sie Diagramme in der CloudFront-Konsole nutzen, um herauszufinden, was den Fehler verursacht. Anschließend können Sie diesen beheben. Beispielsweise können Sie prüfen, ob HTTP 5xx-Fehler von CloudFront oder von Lambda-Funktionen verursacht werden. Anschließend können Sie dann für bestimmte Funktionen entsprechende Protokolldateien anzeigen, um das Problem weiter zu untersuchen.

• Informationen zum allgemeinen Beheben von HTTP-Fehlern in CloudFront finden Sie in der Beschreibung der Fehlerbehebungsschritte im folgenden Thema: Fehlerbehebung bei Fehlermeldungen Ihres Ursprungsservers.

Ursachen für Lambda@Edge-Funktionsfehler in CloudFront

Es gibt mehrere Gründe, aus denen eine Lambda-Funktion einen HTTP 5xx-Fehler verursachen kann. Die Schritte zur Fehlerbehebung hängen von der Art des Fehlers ab. Fehler können wie folgt kategorisiert werden:

Ein Lambda-Funktionsausführungsfehler.

Ein Ausführungsfehler entsteht, wenn CloudFront keine Antwort von Lambda erhält, weil es unbehandelte Ausnahmen in der Funktion gibt oder ein Fehler im Code vorliegt. Zum Beispiel, wenn der Code "callback(Error)" beinhaltet. Weitere Informationen finden Sie unter Lambda-Funktionsfehler im AWS Lambda-Lambda-Entwicklerhandbuch.

Eine ungültige Antwort auf die Lambda-Funktion wird an CloudFront zurückgegeben

Nachdem die Funktion ausgeführt wurde, erhält CloudFront eine Antwort von Lambda. Ein Fehler wird zurückgegeben, wenn die Objektstruktur der Antwort nicht der Lambda@Edge-Ereignisstruktur entspricht oder die Antwort ungültige Header oder andere ungültige Felder enthält.

Die Ausführung in CloudFront wird aufgrund von Lambda-Service-Kontingenten (früher als Limits bezeichnet) gedrosselt

Der Lambda-Service drosselt die Ausführung in jeder Region und gibt einen Fehler zurück, wenn Sie das Kontingent überschreiten.

So bestimmten Sie den Typ des Fehlers

Damit Sie entscheiden können, worauf Sie sich konzentrieren sollten, während Sie mit der Behebung von Fehlern beschäftigt sind, die CloudFront zurückgibt, ist es hilfreich, zu identifizieren, warum CloudFront einen HTTP-Fehler ausgibt. Verwenden Sie die Diagramme im AbschnittMonitoring (Überwachung) der CloudFront-Konsole auf der AWS Management Console. Weitere Informationen zum Anzeigen von Diagrammen im Abschnitt Monitoring (Überwachung) der CloudFront-Konsole finden Sie unter Überwachen von CloudFront-Metriken mit Amazon CloudWatch.

Die folgenden Diagramme sind besonders hilfreich, wenn Sie nachverfolgen möchten, ob Fehler von Ursprungs-Servern oder einer Lambda-Funktion zurückgegeben werden, und wenn Sie die Art des Problems eingrenzen möchten, wenn der Fehler aus einer Lambda-Funktion resultiert.

Fehlerratendiagramm

Eines der Diagramme, das Sie auf der Registerkarte Overview (Überblick) für Ihre Verteilungen anzeigen können, ist das Diagramm Error rates (Fehlerraten). Dieses Diagramm zeigt die Rate der Fehler als Prozentsatz aller Anforderungen an, die bei Ihren Verteilungen eingehen. Das Diagramm zeigt die Gesamtfehlerrate, die gesamten 4xx-Fehler, die gesamten 5xx-Fehler und die gesamten 5xx-Fehler an, die aus Lambda-Funktionen resultieren. Basierend auf Fehlertyp und Anzahl können Sie Schritte unternehmen, um diese Probleme zu untersuchen und zu beheben.

• Wenn Lambda-Fehler auftreten, können Sie eine genauere Untersuchung durchführen, indem Sie sich die spezifischen Arten von Fehlern ansehen, die von der Funktion zurückgegeben werden. Die Registerkarte Lambda@Edge errors (Lambda@Edge-Fehler) enthält Diagramme, die Funktionsfehler nach Typ kategorisieren, damit Sie das Problem für eine bestimmte Funktion herausfinden können.

• Wenn CloudFront-Fehler auftreten, können Sie eine Fehlerbehebung durchführen, um Fehler mit dem Ursprungs-Server zu beheben. Sie können alternativ auch Ihre CloudFront-Konfiguration ändern. Weitere Informationen finden Sie unter Fehlerbehebung bei Fehlermeldungen Ihres Ursprungsservers.

Diagramme für Ausführungsfehler und ungültige Funktionsanworten

Die Registerkarte Lambda@Edge errors (Lambda@Edge-Fehler) enthält Diagramme, die Lambda@Edge-Fehler für eine bestimmte Verteilung nach Typ kategorisieren. So zeigt beispielsweise ein Diagramm alle Ausführungsfehler unterteilt nach AWS-Region an. Damit Fehler einfacher erkannt und behoben werden können, können Sie auf derselben Seite nach bestimmten Problemen suchen, indem Sie die Protokolldateien für spezifische Funktionen regionsweise öffnen und prüfen. Wählen Sie unter View execution error logs (Ausführungsfehlerprotokolle anzeigen oder View invalid function response logs (Protokolle zu ungültigen Funktionsantworten anzeigen) eine Region aus (und für Ausführungsfehler eine Funktion) und klicken Sie dann auf View logs (Protokolle anzeigen).

Lesen Sie darüber hinaus die folgenden Abschnitte in diesem Kapitel, um weitere Empfehlungen für die Behebung von Fehlern zu erhalten.

Drosselungsdiagramm

Die Registerkarte Lambda@Edge errors (Lambda@Edge-Fehler) enthält auch ein Diagramm zu Drosselungen. In einigen Situationen drosselt der Lambda-Service Ihre Funktionsaufrufe auf Regionsbasis, wenn Sie sich dem regionalen Kontingent (früher als Limit bezeichnet) für die Gleichzeitigkeit nähern. Wenn Sie einen limit exceeded (Grenzwert überschritten)-Fehler sehen, hat Ihre Funktion ein Kontingent erreicht, das der Lambda-Service für Ausführungen in einer Region nutzt. Weitere Informationen, u. a. auch zur Erhöhung des Kontingents, finden Sie unter Kontingente für Lambda@Edge.

Ein Beispiel zur Verwendung dieser Informationen beim Beheben von HTTP-Fehlern finden Sie unter Vier Schritte zum Debuggen der Bereitstelllung von Inhalten in AWS.

Fehlerbehebung bei ungültigen Lambda@Edge-Funktionsantworten (Validierungsfehler)

Wenn Sie feststellen, dass Ihr Problem ein Lambda-Validierungsfehler ist, bedeutet dies, dass Ihre Lambda-Funktion eine ungültige Antwort an CloudFront zurückgibt. Befolgen Sie die Anweisungen in diesem Abschnitt, um Ihre Funktion zu überprüfen und sicherzustellen, dass Ihre Antwort den CloudFront-Anforderungen entspricht.

CloudFront überprüft die Antwort einer Lambda-Funktion auf zwei Arten:

• Die Lambda-Antwort muss der gewünschten Objektstruktur entsprechen. Beispiele für eine fehlerhafte Objektstruktur sind: nicht interpretierbarer JSON-Code, fehlende Pflichtfelder und ein ungültiges Objekt in der Antwort. Weitere Informationen hierzu finden Sie unter Lambda@Edge-Ereignisstruktur.

• Die Antwort darf nur gültige Objektwerte beinhalten. Ein Fehler tritt auf, wenn die Antwort ein gültiges Objekt aber nicht unterstützte Werte enthält. Beispiele sind das Hinzufügen oder Aktualisieren von ungültigen Headern oder schreibgeschützten Headern (siehe Einschränkungen für Edge-Funktionen), das Überschreiten der maximalen Body-Größe (siehe Beschränkungen für die Größe der generierten Antwort im Thema Lambda@Edge Fehler) und ungültige Zeichen oder Werte (siehe Lambda@Edge-Ereignisstruktur).

Wenn Lambda eine ungültige Antwort an CloudFront zurückgibt, werden Fehlermeldungen in Protokolldateien geschrieben, die CloudFront in der Region an CloudWatch sendet, in der die Lambda-Funktion ausgeführt wurde. Standardmäßig werden die Protokolldateien an CloudWatch gesendet, falls eine ungültige Antwort vorliegt. Wenn Sie jedoch eine Lambda-Funktion mit CloudFront verknüpft haben, bevor die Funktionalität veröffentlicht wurde, ist diese möglicherweise nicht für Ihre Funktion aktiviert. Weitere Informationen finden Sie unter Feststellen, ob Ihr Konto Protokolle an CloudWatch überträgt weiter unten im Thema.

CloudFront verschiebt Protokolldateien in die Region, die dem Ort entspricht, an dem Ihre Funktion ausgeführt wurde (in die Protokollgruppe, die Ihrer Verteilung zugeordnet ist). Protokollgruppen haben das folgende Format: /aws/cloudfront/LambdaEdge/DistributionId (wobei DistributionId die ID Ihrer Verteilung ist). Um die Region zu bestimmen, in der Sie die CloudWatch Log-Dateien finden, lesen Sie bitte Bestimmen der Lambda@Edge-Region später in diesem Thema.

Wenn der Fehler reproduzierbar ist, können Sie eine neue Anforderung erstellen, die zu dem Fehler führt. Dann finden Sie die Anforderungs-ID in einer fehlgeschlagenen CloudFront-Antwort (X-Amz-Cf-Id-Header), über die Sie einen bestimmten Fehler in Protokolldateien finden. Der Eintrag in der Protokolldatei enthält Informationen, die Ihnen bei der Identifizierung Ursache für den Fehler helfen können. Er zeigt außerdem die entsprechende Lambda-Anforderungs-ID an, mit der Sie die Ursache im Kontext einer einzelnen Anforderung analysieren können.

Wenn ein Fehler zeitweilig auftritt, können Sie mit Hilfe von CloudFront-Zugriffsprotokollen die Anforderungs-ID für eine fehlgeschlagene Anforderung ermitteln und dann die CloudWatch Logs nach den entsprechenden Fehlermeldungen durchsuchen. Weitere Informationen finden Sie im vorherigen Abschnitt Bestimmung der Fehlerart.

Fehlerbehebung bei Lambda@Edge-Funktionsausführungsfehlern

Wenn das Problem ein Lambda-Ausführungsfehler ist, kann es hilfreich sein, Protokollierungsanweisungen für Lambda-Funktionen zu erstellen. So werden Nachrichten in CloudWatch Log-Dateien geschrieben, die die Ausführung Ihrer Funktion in CloudFront überwachen und feststellen, ob sie wie erwartet funktioniert. Dann können Sie nach diesen Anweisungen in den CloudWatch Log-Dateien suchen, um zu überprüfen, ob Ihre Funktion funktioniert.

Anmerkung

Auch wenn Sie Ihre Lambda@Edge-Funktion nicht geändert haben, kann diese durch Aktualisierungen der Lambda-Funktionsausführungsumgebung beeinträchtigt werden und einen Ausführungsfehler ausgeben. Weitere Informationen zum Testen und Migrieren auf eine neuere Version finden Sie unter Bevorstehende Aktualisierungen der AWS-Lambda- und AWS-Lambda@Edge-Ausführungsumgebung.

Bestimmung der Lambda@Edge-Region

Zum Anzeigen der Regionen, in denen Ihre Lambda@Edge-Funktion Datenverkehr empfängt, zeigen Sie Diagramme der Metriken für die Funktion in der CloudFront-Konsole auf AWS Management Console an. Metriken werden für jede AWS-Region angezeigt. Auf derselben Seite können Sie eine Region auswählen und Protokolldateien für diese anzeigen, um Probleme näher zu untersuchen. Sie müssen CloudWatch Log-Dateien in der richtigen AWS-Region überprüfen, um die Protokolldateien anzuzeigen, die erstellt wurden, wenn CloudFront Ihre Lambda-Funktion ausgeführt hat.

Weitere Informationen zum Anzeigen von Diagrammen im Abschnitt Monitoring (Überwachung) der CloudFront-Konsole finden Sie unter Überwachen von CloudFront-Metriken mit Amazon CloudWatch.

Feststellen, ob Ihr Konto Protokolle an CloudWatch überträgt

Standardmäßig aktiviert CloudFront das Protokollieren ungültiger Lambda-Funktionsantworten und überträgt die Protokolldateien mithilfe einer der Serviceverknüpfte Rollen für Lambda@Edge an CloudWatch. Wenn Sie Lambda@Edge-Funktionen haben, die Sie vor der Veröffentlichung der ungültigen Antwort der Lambda-Funktion zu CloudFront hinzugefügt haben, ist die Protokollierung beim nächsten Update Ihrer Lambda@Edge-Konfiguration aktiviert (z. B. durch Hinzufügen eines CloudFront-Auslösers).

Sie können überprüfen, ob das Verschieben der Protokolldateien zu CloudWatch für Ihr Konto aktiviert ist, indem Sie wie folgt vorgehen:

• Überprüfen Sie, ob die Protokolle in CloudWatch erscheinen. Achten Sie darauf, dass Sie in der Region suchen, in der die Lambda@Edge-Funktion ausgeführt wurde. Weitere Informationen finden Sie unter Bestimmung der Lambda@Edge-Region.

• Stellen Sie fest, ob die zugehörige servicegebundene Rolle in Ihrem Konto in IAM existiert. Öffnen Sie dazu die IAM-Konsole unter https://console.aws.amazon.com/iam/ und wählen Sie dann Roles (Rollen), um die Liste der serviceverknüpften Rollen für Ihr Konto anzuzeigen. Achten Sie auf die folgende Rolle: AWSServiceRoleForCloudFrontLogger.