Comment activer CloudWatch Logs pour résoudre les problèmes liés à l'API REST ou l'API WebSocket de mon API Gateway ?

Dernière mise à jour : 10/11/2020

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 que vous développez, 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 un HTTP API.

Les journaux des exécutions contiennent des informations utiles que vous pouvez utiliser pour identifier et éliminer la plupart des erreurs liées à vos API. Ces informations incluent :

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. Pour plus d'informations sur chaque type de journalisation, consultez Formats de journaux CloudWatch pour API Gateway.

Ré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, sélectionnez Roles (Rôles).
  2. Dans le volet Roles (Rôles), sélectionnez Create role (Créer un rôle).
  3. Sur la page Create role (Créer un rôle), procédez comme suit :
    Dans la section Select type of trusted entity (Sélectionner le type d'entité de confiance), sélectionnez AWS service (Service AWS).
    Dans la section Choose the service that will use this role (Choisir le service qui utilisera ce rôle), choisissez API Gateway.
    Sélectionnez Next: Permissions (Étape suivante : 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. Cette stratégie dispose de toutes les autorisations requises.
  5. Sélectionnez Next: Tags (Étape suivante : balises).
  6. Ajoutez éventuellement des balises, puis sélectionnez Next: Review (Étape suivante : vérification).
  7. 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 (Créer un rôle).
  8. Dans la barre de recherche du volet Roles (Rôles), entrez le nom du rôle que vous avez créé, puis choisissez le rôle dans les résultats de recherche.
  9. Dans le volet 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 CloudWatch Logging.

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.
  2. Dans le volet de navigation de gauche, en bas, sélectionnez Paramètres.
  3. En dessous de Paramètres, 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 bien été enregistré.

Activer la journalisation pour votre API et votre étape

  1. Dans la console API Gateway, recherchez Stage Editor pour votre API.
  2. Dans le volet Stage Editor choisissez l'onglet Logs/Tracing (Journaux/Traçage).
  3. Dans l'onglet Logs/Tracing (Journaux/Suivi), 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 choisissez ERROR pour générer des journaux des exécutions uniquement pour les demandes envoyées à votre API, qui entraînent une erreur.
    Cochez la case Log full requests/responses data (Consigner toutes les demandes/données des réponses) pour une API REST. Vous pouvez également cocher la case Log full message data (Consigner toutes les données de messages) pour une API WebSocket.
  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, vous pouvez choisir 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 ces paramètres ont été enregistrés avec succè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 cliente ou un outil comme l'application Postman ou wscat (pour les API WebSocket).
  2. Dans le volet de navigation de gauche de la console CloudWatch, en dessous de Logs (Journaux), sélectionnez Log Groups (Groupes de journaux).
  3. Dans la liste Log Groups (Groupes de journaux), choisissez le groupe de journaux de l'API que vous déboguez.
    Pour une API REST, le nom du groupe de journaux a le format API-Gateway-Execution-Logs_apiId/stageName.
    Pour une API WebSocket, le nom du groupe de journaux a le format /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 Log Streams (Flux de journaux), choisissez le flux de journaux avec la Last Event Time (toute dernière heure d'événement) pour afficher 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.