View a markdown version of this page

Journalisation des exécutions pour les API REST - Amazon API Gateway
Journalisation des exécutions standardLivraison CloudWatch des journaux d'exécution par Amazon Logs

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Journalisation des exécutions pour les API REST

La journalisation des exécutions enregistre les actions entreprises par API Gateway pour traiter une demande d'API. Les données enregistrées incluent les erreurs, les traces d'exécution, les valeurs des paramètres de demande et de réponse ou les charges utiles, les données utilisées par les autorisateurs Lambda, si des clés d'API sont requises et si les plans d'utilisation sont activés. API Gateway supprime les en-têtes d’autorisation, les valeurs des clés d’API et d’autres paramètres de demande sensibles similaires des données journalisées.

Pour renforcer votre niveau de sécurité, nous vous recommandons d’utiliser la journalisation des exécutions au niveau ERROR ou INFO. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez Amazon API Gateway controls dans le Guide de l’utilisateur AWS Security Hub .

Journalisation des exécutions standard

Lorsque vous activez la journalisation des exécutions sur une étape, API Gateway crée et gère automatiquement un groupe de CloudWatch journaux de journaux. Le groupe de journaux est nomméAPI-Gateway-Execution-Logs_{rest-api-id}/{stage_name}. Au sein de chaque groupe de journaux, les journaux sont divisés en flux de journaux classés par date du dernier événement.

Avec la journalisation d'exécution standard :

  • Les événements du journal sont tronqués à 1 Ko.

  • API Gateway gère le nom du groupe de journaux. Vous ne pouvez pas choisir le nom du groupe de journaux ou envoyer des journaux directement à Amazon S3 ou Firehose.

Pour activer la journalisation des exécutions standard, réglez le paramètre loggingLevel on your stage sur ERROR ouINFO. Aucune autre configuration n'est requise.

Permissions

Pour activer CloudWatch les journaux, vous devez autoriser API Gateway à lire et à écrire les journaux CloudWatch de votre compte. La politique AmazonAPIGatewayPushToCloudWatchLogs gérée possède toutes les autorisations requises.

Créez un rôle IAM avec apigateway.amazonaws.com comme entité de confiance, associez la politique précédente et définissez l'ARN du rôle IAM sur la WatchRoleArn propriété cloud de votre compte. Vous devez définir cette propriété séparément pour chaque AWS région dans laquelle vous souhaitez activer CloudWatch les journaux.

Note

API Gateway appelle AWS Security Token Service pour assumer le rôle IAM. Assurez-vous donc que cette option AWS STS est activée pour la région. Pour plus d'informations, consultez la section Gestion AWS des STS dans une AWS région.

Activer la journalisation des exécutions (console)

Avant de commencer, déployez l'API sur une étape et configurez un ARN de rôle CloudWatch Logs approprié pour votre compte.

  1. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

  2. Dans le volet de navigation principal, choisissez Paramètres, puis sous Journalisation, choisissez Modifier.

  3. Pour l'ARN du rôle de CloudWatch journal, entrez l'ARN d'un rôle IAM doté des autorisations appropriées. Vous devez effectuer cette opération une fois pour chaque application Compte AWS qui crée des API à l'aide d'API Gateway.

  4. Dans le volet de navigation principal, choisissez API, choisissez votre API REST, puis choisissez Stages.

  5. Choisissez une étape, puis dans la section Journaux et suivi, choisissez Modifier.

  6. Sélectionnez un niveau de journalisation dans le menu déroulant CloudWatch Journaux :

    • Désactivé : API Gateway n'enregistre pas les demandes pour cette étape.

    • Erreurs uniquement  : API Gateway enregistre uniquement les erreurs.

    • Erreurs et journaux d'informations  : API Gateway enregistre tous les événements.

  7. (Facultatif) Sélectionnez Suivi des données pour enregistrer les données complètes des demandes et des réponses. Cela peut entraîner l'enregistrement de données sensibles.

    Note

    Nous vous recommandons de ne pas activer Suivi des données pour les API de production.

  8. (Facultatif) Sélectionnez Mesures détaillées pour activer les CloudWatch mesures détaillées. Pour plus d’informations, consultez Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon.

  9. Sélectionnez Save Changes (Enregistrer les modifications).

Il n'est pas nécessaire de redéployer l'API lorsque vous mettez à jour les paramètres de stage.

Activez la journalisation des exécutions (CloudFormation)

Utilisez la MethodSettings propriété de la ressource de scène pour activer la journalisation de l'exécution.

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      MethodSettings:
        - ResourcePath: "/*"
          HttpMethod: "*"
          LoggingLevel: INFO

Pour activer CloudWatch les journaux, vous devez autoriser API Gateway à lire et à écrire les journaux CloudWatch de votre compte. Pour en savoir plus, consultez Associer le compte au rôle IAM dans le Guide de l’utilisateur AWS CloudFormation .

Livraison CloudWatch des journaux d'exécution par Amazon Logs

La diffusion CloudWatch d'Amazon Logs fournit un autre chemin pour les journaux d'exécution. Au lieu d'écrire dans un groupe de Gateway-managed journaux d'API, vous configurez une diffusion qui envoie des journaux d'exécution vers des destinations que vous possédez et contrôlez.

Avec la livraison Amazon CloudWatch Logs :

  • Les événements du journal peuvent atteindre 1 Mo, ce qui permet de capturer des données de demande et de réponse plus complètes. Les charges utiles supérieures à 1 Mo sont toujours tronquées.

  • Vous choisissez la destination : vos propres groupes de CloudWatch journaux Logs, vos compartiments Amazon S3 ou vos flux Firehose.

  • Vous pouvez envoyer des journaux vers plusieurs destinations simultanément.

  • Vous contrôlez la configuration des groupes de journaux, y compris la dénomination et la conservation.

Important

CloudWatch La livraison des journaux remplace la journalisation d'exécution standard. Lorsque vous configurez une diffusion, API Gateway arrête d'écrire dans le groupe de journaux géré automatiquement. Vous ne pouvez pas utiliser les deux chemins en même temps pour la même étape.

Lorsque vous créez une diffusion, API Gateway achemine les journaux d'exécution vers les destinations que vous avez configurées au lieu du groupe de journaux géré automatiquement. Lorsque vous supprimez une livraison, les journaux d'exécution reprennent automatiquement leur transfert vers le groupe de journaux géré automatiquement. Aucune modification de configuration d'API Gateway n'est nécessaire au-delà de la condition préalable de paramétrage loggingLevel sur ERROR ouINFO.

Note

La livraison des grumes constitue le meilleur effort. Dans de rares cas, certains événements du journal peuvent ne pas être transmis.

Avertissement

Avant d'activer la remise des journaux, mettez à jour les tableaux de bord, les alarmes ou les filtres d'abonnement qui font référence au groupe de journaux géré automatiquement ()API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}. Une fois la livraison active, ce groupe de journaux ne reçoit plus de nouveaux événements.

Le tableau suivant compare la journalisation d'exécution standard à la diffusion d'Amazon CloudWatch Logs.

Journalisation des exécutions standard Livraison Amazon CloudWatch Logs
Taille maximale des événements de journalisation 1 Ko 1 Mo
Destinations CloudWatch Journaux (groupe de journaux géré) CloudWatch Logs, Amazon S3, Firehose (vos propres ressources)
Destinations multiples Non Oui
Nom du groupe de journaux Corrigé par API Gateway À vous de choisir
Configuration Automatique lorsque la journalisation est activée Nécessite la création d'une livraison Amazon CloudWatch Logs
Prérequis Réglez loggingLevel sur ERROR ou INFO Réglez loggingLevel sur ERROR ou INFO
Note

Si vous définissez cette loggingLevel valeur OFF après avoir configuré une diffusion, aucun journal d'exécution n'est généré ou transmis. Vos destinations de livraison restent configurées mais ne reçoivent aucune donnée.

Pour créer une diffusion, consultezCréation d'une livraison de journal pour les journaux d'exécution de l'API REST.