Comment activer CloudWatch Logs pour le dépannage de mon API REST ou WebSocket API de mon API Gateway ?

Dernière mise à jour : 10/03/2021

Je dois éliminer des erreurs liées à une API REST ou une API WebSocket d'une Amazon API Gateway que je développe. Comment activer la journalisation pour résoudre les problèmes liés à mon API ?

Brève description

Pour résoudre les problèmes liés à une API REST ou une API WebSocket d'une API Gateway, activez la journalisation des exécutions et la journalisation des accès dans Amazon CloudWatch Logs.

Remarque : les API HTTP prennent actuellement en charge la journalisation des accès uniquement et la configuration de la journalisation est différente pour ces API. Pour plus d'informations, consultez Configuration de la journalisation pour une API HTTP.

Les journaux des exécutions contiennent des informations que vous pouvez utiliser pour identifier et résoudre la plupart des erreurs d'API. Par exemple :

Les journaux des accès contiennent des informations sur les personnes ayant accédé à votre API et la façon dont elles y ont accédé. Vous pouvez également utiliser ces informations pour résoudre les problèmes d’API. Pour plus d'informations sur chaque type de journalisation, consultez Formats de journaux CloudWatch pour API Gateway.

Solution

Créer un rôle IAM pour la journalisation dans CloudWatch

1.    Dans la console AWS Identity and Access Management (IAM), dans le volet de navigation de gauche, choisissez Roles (Rôles).

2.    Dans le volet Roles (Rôles), choisissez Create role (Créer un rôle).

3.    Sur la page Create role (Créer un rôle), procédez comme suit :
Pour Select type of trusted entity (Sélectionner le type d'entité de confiance), choisissez AWS Service (Service AWS).
Pour Choose a use case (Choisir un cas d'utilisation), choisissez API Gateway.
Pour Select your use case (Sélectionnez votre cas d'utilisation), choisissez API Gateway.
Sélectionnez Next: Permissions (Suivant : autorisations).

4.    Sous Attached permissions policies (Stratégies d'autorisations attachées), notez que la stratégie gérée AWS AmazonAPIGatewayPushToCloudWatchLogs est sélectionnée par défaut. La stratégie dispose de toutes les autorisations requises.

5.    Choisissez Next: Tags (Suivant : Balises).

6.    (Facultatif) Ajoutez des tags (balises).

7.    Sélectionnez Next: Review (Suivant : vérification).

8.    Sous Review (Vérification), procédez comme suit :
Pour Role name (Nom du rôle), saisissez le nom du rôle.
(Facultatif) Pour le champ Role description (Description du rôle), modifiez la description selon vos préférences.
Sélectionnez Create role.

9.    Sur le panneau Roles, dans la barre de recherche, saisissez le nom du rôle que vous avez créé. Choisissez ensuite le rôle parmi les résultats de la recherche.

10.    Dans le panneau Summary (Récapitulatif), copiez l'ARN du rôle. Vous aurez besoin de cet ARN (Amazon Resource Name) dans la section suivante.

Pour plus d'informations, consultez Autorisations pour la journalisation CloudWatch.

Ajouter le rôle IAM dans la console API Gateway

Remarque : si vous développez plusieurs API dans différentes régions AWS, réalisez ces étapes dans chaque région.

1.    Dans la API Gateway console (console API Gateway), dans le volet APIs, choisissez le nom d'une API que vous avez créée.

2.    Dans le panneau de navigation de gauche, en bas, sous la section Client Certificates (Certificats clients), choisissez Settings (Paramètres).

3.    En dessous de Settings, pour CloudWatch log role ARN (ARN de rôle du journal CloudWatch), collez l'ARN du rôle IAM que vous avez copié.

4.    Choisissez Save (Enregistrer).
Remarque : la console ne confirme pas que l'ARN a été enregistré.

Activer la journalisation pour votre API et votre étape

1.    Dans la console API Gateway, recherchez Stage Editor (Éditeur d’étape) pour votre API.

2.    Dans le panneau Stage Editor, choisissez l'onglet Logs/Tracing (Journaux/Suivi).

3.     Dans l'onglet Logs/Tracing, sous CloudWatch Settings (Paramètres CloudWatch), procédez comme suit pour activer la journalisation des exécutions :
Cochez la case Enable CloudWatch Logs (Activer CloudWatch Logs).
Pour Log level (Niveau de journalisation), choisissez INFO pour générer des journaux des exécutions pour toutes les demandes. Ou sélectionnez ERROR pour générer des journaux des exécutions uniquement pour les demandes envoyées à votre API qui entraînent une erreur.
Pour les API REST, cochez la case Log full requests/responses data (Consigner toutes les demandes/données des réponses). Ou, pour les API WebSocket, cochez la case Log full message data (Consigner les données complètes des messages).

4.    Sous Custom Access Logging (Journalisation des accès personnalisée), procédez de la manière suivante pour activer la journalisation des accès :
Cochez la case Enable Access Logging (Activer la journalisation des accès).
Pour Access Log Destination ARN (Accéder à l'ARN de destination du journal), saisissez l'ARN d'un CloudWatch log group (Groupe de journaux CloudWatch) ou d'un flux Amazon Kinesis Data Firehose.
Saisissez un format de journal. Pour obtenir des conseils, choisissez CLF, JSON, XML, ou CSV pour voir un exemple dans ce format.

5.    Sélectionnez Save changes (Enregistrer les modifications).
Remarque : la console ne confirme pas que les paramètres sont enregistrés.

Pour plus d'informations, consultez Configuration de la journalisation des API CloudWatch en utilisant la console API Gateway.

Tester votre configuration de journalisation

1.    Envoyez une nouvelle demande à votre API en utilisant votre application client ou un outil comme l'application Postman ou wscat (pour les API WebSocket).

2.    Dans la console CloudWatch, dans le panneau de navigation de gauche, sous Logs (Journaux), sélectionnez Log Groups (Groupes de journaux).

3.    Dans la liste des Log Groups, choisissez le groupe de journaux de l'API que vous déboguez.
Pour les API REST, le nom du groupe de journaux a le format suivant : API-Gateway-Execution-Logs_apiId/stageName.
Pour les API WebSocket, le nom du groupe de journaux a le format suivant : /aws/apigateway/apiId/stageName.
Remarque : les journaux des accès se trouvent dans le groupe de journaux dont vous avez spécifié l'ARN lorsque vous avez activé la journalisation des accès.

4.    Dans la liste des Log Streams (Flux de journaux), choisissez le flux de journaux avec la dernière Heure du dernier événement. Cette sélection vous permettra de voir les messages avec les détails d’exécution ou d’accès de votre demande.

Pour plus d'informations, consultez Affichage des événements de journaux API Gateway dans la console CloudWatch.