Wie aktiviere ich CloudWatch-Protokolle 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.

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-Protokollen auf die Protokollierung zu.

Hinweis: HTTP-APIs unterstützen derzeit nur die Zugriffsprotokollierung. Die Einrichtung der Protokollierung ist für diese APIs unterschiedlich. Weitere Informationen finden Sie unterKonfigurieren der Protokollierung für eine HTTP-API.

Ausführungsprotokolle enthalten Informationen, mit denen Sie die meisten API-Fehler identifizieren und beheben können. Die Protokolle können beispielsweise die folgenden Informationen enthalten:

Die Anfragen, die Ihre API empfängt
Integration-Backend-Antworten von Ihrer API
Die Antwort von AWS Lambda Authorizer
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.

Lösung

Erstellen Sie eine IAM-Rolle, um sich bei CloudWatch anzumelden

Gehen Sie wie folgt vor, um eine AWS Identity and Access Management (IAM) -Rolle zum Senden von Protokollen an CloudWatch zu erstellen:

Öffnen Sie die IAM-Konsole.
Wählen Sie im Navigationsbereich Rollen aus.
Wählen Sie im Bereich Rollen die Option Rolle erstellen aus.
Geben Sie auf der Seite Rolle erstellen die folgenden Informationen ein:
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 aus.
Beachten Sie unter Berechtigungsrichtlinien, dass die von AWS verwaltete Richtlinie AmazonAPIGatewayPushToCloudWatchLogs standardmäßig ausgewählt ist. Die Richtlinie verfügt über alle erforderlichen Berechtigungen.
Wählen Sie Weiter aus.
Geben Sie unter Benennen, überprüfen und erstellen die folgenden Informationen ein:
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.
Kopieren Sie im Bereich Übersicht den Rollen-ARN. Sie benötigen diesen 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

Gehen Sie wie folgt vor, um die IAM-Rolle zur API Gateway-Konsole hinzuzufügen:

Öffnen Sie die API-Gateway-Konsole.
Wählen Sie 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 Navigationsbereich Einstellungen aus.
Geben Sie unter Einstellungen für den ARN der CloudWatch-Protokollrolle den ARN der IAM-Rolle ein.
Hinweis: Die CloudWatch-Protokollrolle ist eine Konfiguration auf AWS-Regionsebene und wird mit allen APIs in dieser AWS-Region verwendet.
Wählen Sie Speichern.

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

Aktivieren Sie die Protokollierung für Ihre API und Phase

Gehen Sie wie folgt vor, um die Protokollierung für Ihre API und Ihren Stage zu aktivieren:

Öffnen Sie die API-Gateway-Konsole.
Wählen Sie im Navigationsbereich APIs und dann Ihre API aus.
Wählen Sie im Navigationsbereich Stages aus. Wählen Sie dann Ihre Stage aus.
Wählen Sie unter Protokolle und Verfolgung die Option Bearbeiten aus.
Führen Sie unter CloudWatch-Protokolle die folgenden Aufgaben aus, um die Ausführungsprotokollierung zu aktivieren:
Wählen Sie aus der Drop-down-Liste Ihre Protokollebene aus:
Oder wählen Sie Nur Fehler, um Ausführungsprotokolle nur für Anfragen an Ihre API zu generieren, die zu einem Fehler führen.
Wählen Sie Fehler- und Infoprotokolle, um Ausführungsprotokolle für alle Anfragen zu generieren.
Wählen Sie Vollständige Anfragen und Antwortprotokolle, um eine detaillierte Protokollierung für alle Ereignisse zu erstellen.
Hinweis: Vollständige Anfragen- und Antwortprotokolle sind für die Problembehandlung nützlich, können aber vertrauliche Daten protokollieren. Es hat sich bewährt, keine vollständigen Anfragen und Antwortprotokolle für Produktions-APIs zu verwenden.
Führen Sie unter Benutzerdefinierte Zugriffsprotokollierung die folgenden Aufgaben aus, um die Zugriffsprotokollierung zu aktivieren:
Aktivieren Sie das Kontrollkästchen Zugriffsprotokollierung aktivieren.
Geben Sie für Zugriffsprotokoll-Ziel-ARN den ARN einer Amazon Kinesis Data Firehose - oder CloudWatch-Protokollgruppe ein.
Hinweis: Der ARN von Amazon Kinesis Data Firehose wird nur in REST-APIs unterstützt.
Geben Sie ein Protokollformat ein.
Klicken Sie auf Änderungen speichern.

Weitere Informationen finden Sie unter CloudWatch-Protokollformate für API Gateway.

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.

Gehen Sie wie folgt vor, um Ihr Protokollierungs-Setup zu testen:

Öffnen Sie die CloudWatch-Konsole.
Wählen Sie im Navigationsbereich unter Protokolle die Option Protokollgruppen aus.
Wählen Sie in der Liste der Protokollgruppen die Protokollgruppe der API aus, die Sie debuggen möchten.
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.