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

Lecture de 6 minute(s)
0

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 les journaux pour résoudre les erreurs 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, 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 Trusted entity type (Type d'entité de confiance), choisissez AWS Service (Service AWS).
Pour use case (cas d'utilisation), choisissez API Gateway.
Choisissez le bouton radio API Gateway.
Choisissez Next (Suivant).

4.    Sous Permissions policies (Politiques d'autorisations), notez que la politique gérée par AWS AmazonAPIGatewayPushToCloudWatchLogs est sélectionnée par défaut. La politique dispose de toutes les autorisations requises.

5.    Choisissez Next (Suivant).

6.    Sous Nom, révision et création, procédez comme suit :
Dans Nom du rôle, entrez un nom pour le rôle.
(Facultatif) Pour Description du rôle, modifiez la description selon vos préférences.
(Facultatif) Ajoutez des identifications.
Choisissez Create role (Créer un rôle).

7.    Sur le panneau Roles (Rôles), 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 recherche.

8.    Dans le volet Summary (Récapitulatif), copiez l'ARN du rôle. Vous aurez besoin de cet Amazon Resource Name (ARN) 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 console API Gateway, dans le volet APIs, choisissez le nom d'une API que vous avez créée. Il s'agit d'une API REST ou d'une API WebSocket (pas d'une API HTTP).

2.    Dans le volet 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, dans le volet APIs, choisissez le nom d'une API que vous avez créée.

2.    Dans le panneau de navigation de gauche, choisissez Schéma. Sélectionnez ensuite le nom de scène de votre choix.

3.    Choisissez l'onglet Logs/Tracing.

4.    Dans l'onglet Logs/Tracing, sous Paramètres CloudWatch Settings, 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 Consigner toutes les données de messages.

5.    Sous 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 Amazon Kinesis Data Firehose (ceci n'est pris en charge que par les API REST) ou d'un groupe de journaux CloudWatch.

Saisissez un Log Format (Format de journal). Pour obtenir des conseils, choisissez CLF, JSON, XML, ou CSV pour voir un exemple dans ce format.

6.    Choisissez 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 de l'API CloudWatch à l'aide de 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 d'accès se trouvent dans le groupe de journaux dont vous avez spécifié l'ARN lorsque vous avez activé la journalisation d'accès.

4.    Dans la liste des Log Streams (Flux de journaux), choisissez le flux de journaux avec la dernière Last Event Time (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 des journaux API Gateway dans la console CloudWatch.


Informations connexes

Configuration de la journalisation CloudWatch pour une API REST dans API Gateway

Modèle de mappage d'API Gateway et référence variable de la journalisation des accès

Surveillance de l'exécution de l'API REST avec les métriques Amazon CloudWatch

Surveillance de l'exécution de l'API WebSocket avec les métriques CloudWatch