Wie aktiviere ich CloudWatch Logs zur Fehlerbehebung meiner API-Gateway-REST-API oder WebSocket-API?

Lesedauer: 5 Minute

Ich muss Fehler mit einer Amazon API Gateway-REST-API oder WebSocket-API debuggen, die ich gerade entwickle. Wie aktiviere ich die Protokollierung, um Probleme mit meiner API zu beheben?

Kurzbeschreibung

Um Probleme mit einer API-Gateway-REST-API oder WebSocket-API zu beheben, aktivieren Sie die Ausführungsprotokollierung und greifen Sie mithilfe von Amazon CloudWatch Logs auf die Protokollierung zu.

Hinweis: HTTP-APIs unterstützen derzeit nur die Zugriffsprotokollierung. Die Einrichtung der Protokollierung für diese APIs erfolgt auf eine andere Art. Weitere Informationen finden Sie unter Konfigurieren der Protokollierung für HTTP API.

Ausführungsprotokolle enthalten Informationen, mit denen Sie die meisten API-Fehler identifizieren und beheben können. Zum Beispiel:

Die Anfragen, die Ihre API empfängt
Die Integration-Backend-Antworten von Ihrer API
Die Antwort der AWS Lambda-Autorisatoren
Die RequestID für AWS-Integration-Endpunkte
Information darüber, ob ein bereitgestellter API-Schlüssel autorisiert wurde

Zugriffsprotokolle enthalten Details darüber, wer auf Ihre API zugegriffen hat und wie darauf zugegriffen wurde. Sie können die Protokolle auch zur Behebung von API-Fehlern verwenden. Weitere Informationen zu den einzelnen Protokollierungstypen finden Sie unter CloudWatch-Protokollformate für API Gateway.

Behebung

Erstellen Sie eine IAM-Rolle für die Protokollierung an CloudWatch

Wählen Sie in der AWS Identity and Access Management (IAM)-Konsole im Navigationsbereich die Option Rollen aus.
Wählen Sie im Bereich Rollen die Option Rolle erstellen aus.
Gehen Sie auf der Seite Rolle erstellen wie folgt vor:
Wählen Sie für den Typ Vertrauenswürdige Entität die Option AWS Service aus.
Wählen Sie als Anwendungsfall API Gateway.
Wählen Sie das Optionsfeld API Gateway.
Wählen Sie Weiter.
Beachten Sie unter Berechtigungsrichtlinien, dass die von AWS verwaltete Richtlinie AmazonApigatewayPushToCloudWatchLogs standardmäßig ausgewählt ist. Die Richtlinie verfügt über alle erforderlichen Berechtigungen.

5. Wählen Sie Weiter.

Gehen Sie unter Name, überprüfen und erstellen wie folgt vor:
Geben Sie unter Rollenname einen Namen für die Rolle ein.
(Optional) Bearbeiten Sie für die Rollenbeschreibung die Beschreibung nach Ihren Wünschen.
(Optional) Fügen Sie Schlagworte hinzu.
Wählen Sie Rolle erstellen.
Geben Sie im Bereich Rollen in der Suchleiste den Namen der Rolle ein, die Sie erstellt haben. Wählen Sie dann die Rolle aus den Suchergebnissen aus.
Kopieren Sie im Bereich Übersicht den Rollen-ARN. Sie benötigen diesen Amazon-Ressourcennamen (ARN) im nächsten Abschnitt.

Weitere Informationen finden Sie unter Berechtigungen für die CloudWatch-Protokollierung.

Fügen Sie die IAM-Rolle in der API Gateway-Konsole hinzu

**Hinweis:**Wenn Sie mehrere APIs in verschiedenen AWS-Regionen entwickeln, führen Sie diese Schritte in jeder Region durch.

Wählen Sie in der API Gateway-Konsole im Bereich APIs den Namen einer API aus, die Sie erstellt haben. Dies ist entweder eine REST-API oder eine WebSocket-API (keine HTTP-API).
Wählen Sie im linken Navigationsbereich unten im Abschnitt Client-Zertifikate die Option Einstellungen aus.
Fügen Sie unter Einstellungen für die CloudWatch-Protokollrollen-ARN den IAM-Rollen-ARN ein, den Sie kopiert haben.
Wählen Sie Speichern.
Hinweis: Die Konsole bestätigt nicht, dass der ARN gespeichert wurde.

Aktivieren Sie die Protokollierung für Ihre API und Phase

Wählen Sie in der API Gateway-Konsole im Bereich APIs den Namen einer API aus, die Sie erstellt haben.
Wählen Sie im linken Navigationsbereich Phase aus. Wählen Sie dann den gewünschten Phasennamen aus.
Wählen Sie die Registerkarte Protokolle/Nachverfolgung.
Gehen Sie auf der Registerkarte Protokolle/Nachverfolgung unter CloudWatch-Einstellungen wie folgt vor, um die Ausführungsprotokollierung zu aktivieren:
Markieren Sie das Kontrollkästchen CloudWatch Logs aktivieren.
Wählen Sie unter Protokoll-Ebene die Option INFO aus, um Ausführungsprotokolle für alle Anfragen zu generieren. Oder wählen Sie ERROR, um Ausführungsprotokolle nur für Anfragen an Ihre API zu generieren, die zu einem Fehler führen.
Markieren Sie für REST-APIs das Kontrollkästchen Vollständige Anforderungen/Antwortdaten protokollieren. Oder wählen Sie für WebSocket-APIs das Kontrollkästchen Vollständige Nachrichtendaten protokollieren.
Gehen Sie unter Benutzerdefinierte Zugriffsprotokollierung wie folgt vor, um die Zugriffsprotokollierung zu aktivieren:
Markieren Sie das Kontrollkästchen Zugriffsprotokollierung aktivieren .
Geben Sie für Access Log Destination ARN den ARN eines Amazon Kinesis Data Firehose (dies wird nur in REST-APIs unterstützt) oder einer CloudWatch-Protokollgruppe ein.

Geben Sie ein Protokollformat ein. Wählen Sie zur Orientierung CLF, JSON, XML oder CSV, um ein Beispiel in diesem Format zu sehen.

6. Wählen Sie Änderungen speichern.
Hinweis: Die Konsole bestätigt nicht, dass die Einstellungen gespeichert wurden.

Weitere Informationen finden Sie unter Einrichten der CloudWatch-API-Protokollierung mithilfe der API Gateway-Konsole.

Testen Sie Ihr die Einstellungen der Protokollierung

Senden Sie mit Ihrer Client-Anwendung oder einem Tool wie der Postman-App oder wscat (für WebSocket-APIs) eine neue Anfrage an Ihre API.
Wählen Sie in der CloudWatch-Konsole im linken Navigationsbereich unter Protokolle die Option Protokollgruppen aus.
Wählen Sie in der Liste der Protokollgruppen die Protokollgruppe der API aus, die Sie debuggen.
Bei REST-APIs hat der Name der Protokollgruppe das folgende Format: API-Gateway-Execution-Logs_apiId/stageName.
Für WebSocket-APIs hat der Name der Protokollgruppe das folgende Format: /aws/apigateway/apiID/StageName.
Hinweis: Die Zugriffsprotokolle befinden sich in der Protokollgruppe, deren ARN Sie angegeben haben, als Sie die Zugriffsprotokollierung aktiviert haben.
Wählen Sie in der Liste der Protokollstreams den Protokollstream mit der Uhrzeit des letzten Ereignisses aus. Diese Auswahl ermöglicht es Ihnen, Nachrichten mit den Ausführungs- oder Zugriffsdaten Ihrer Anfrage zu sehen.