Configuration de la journalisation CloudWatch pour les API REST dans API Gateway
Pour vous aider à déboguer les problèmes liés à l’exécution de demandes ou à l’accès client à votre API, vous pouvez activer Amazon CloudWatch Logs pour enregistrer les appels d’API. Pour plus d’informations sur CloudWatch, consultez Surveillance de l’exécution d’une API REST à l’aide des métriques Amazon CloudWatch.
Formats des journaux CloudWatch pour API Gateway
Il existe deux types de journalisation d’API dans Amazon CloudWatch : la journalisation des exécutions et celle des accès. Dans la journalisation des exécutions, API Gateway gère CloudWatch Logs. Le processus comprend la création de groupes de journaux et de flux de journaux, et la génération de rapports dans les flux de journaux sur toutes les demandes et réponses des utilisateurs.
Les données journalisées incluent les erreurs ou les suivis d’exécution (comme valeurs des paramètres des demandes ou réponses, ou données utiles), les données utilisées par les mécanismes d’autorisation Lambda (anciennement appelés mécanismes d’autorisation personnalisée), et indiquent, entre autres, si des clés d’API sont requises, si les plans d’utilisation sont activés, ainsi que d’autres informations. 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.
Lorsque vous déployez une API, API Gateway crée un groupe de journaux et, sous celui-ci, les flux de journaux. Le groupe de journaux est nommé selon le format API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}
. Dans chaque groupe de journaux, les journaux sont ensuite divisés en flux de journaux, qui sont ordonnés par Heure du dernier événement à mesure que les données sont rapportées.
Dans la journalisation des accès, vous, en tant que développeur d’API, souhaitez enregistrer qui a accédé à votre API et comment l’appelant à eu accès à l’API. Vous pouvez créer votre propre groupe de journaux ou en choisir un existant, qui peut être géré par API Gateway. Pour spécifier les détails d’accès, vous devez sélectionner des variables $context, un format de journal et une destination de groupe de journaux.
Le format du journal d’accès doit inclure au moins $context.requestId
ou $context.extendedRequestId
. À titre de bonne pratique, incluez $context.requestId
et $context.extendedRequestId
dans le format de votre journal.
$context.requestId
-
Cela journalise la valeur dans l’en-tête
x-amzn-RequestId
. Les clients peuvent écraser la valeur de l’en-têtex-amzn-RequestId
avec une valeur au format d’un identifiant unique universel (UUID). API Gateway renvoie cet ID de demande dans l’en-tête de réponsex-amzn-RequestId
. API Gateway remplace les ID de demande écrasés qui ne sont pas au format UUID par
dans vos journaux d’accès.UUID
_REPLACED_INVALID_REQUEST_ID $context.extendedRequestId
-
extendedRequestID est un ID unique généré par API Gateway. API Gateway renvoie cet ID de demande dans l’en-tête de réponse
x-amz-apigw-id
. Un appelant API ne peut pas fournir ni remplacer cet ID de demande. Vous devrez peut-être fournir cette valeur à AWS Support pour la résolution des problèmes liés à votre API. Pour en savoir plus, consultez Variables $context pour les modèles de données, les mécanismes d’autorisation, les modèles de mappage et la journalisation des accès de CloudWatch..
Note
Seules les variables $context
sont prises en charge.
Choisissez un format de journal également adopté par votre backend analytique, comme Common Log Format
Quelques exemples de certains formats de journaux d’accès utilisés couramment sont affichés dans la console API Gateway et répertoriés ci-dessous.
-
CLF
(Format de journal commun): $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime]"$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
-
JSON
:{ "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" }
-
XML
:<request id="$context.requestId"> <extendedRequestId>$context.extendedRequestId</extendedRequestId> <ip>$context.identity.sourceIp</ip> <caller>$context.identity.caller</caller> <user>$context.identity.user</user> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <resourcePath>$context.resourcePath</resourcePath> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </request>
-
CSV
(valeurs séparées par des virgules) :$context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
Autorisations pour la journalisation CloudWatch
Pour activer CloudWatch Logs, vous devez accorder l’autorisation API Gateway pour lire et écrire les journaux dans CloudWatch pour votre compte. AmazonAPIGatewayPushToCloudWatchLogs dispose de toutes les autorisations requises.
Note
API Gateway appelle AWS Security Token Service afin d’assumer le rôle IAM. Assurez-vous donc que AWS STS est activé pour la Région. Pour en savoir plus, consultez Gestion d’AWS STS dans une région AWS.
Pour accorder ces autorisations à votre compte, créez un rôle IAM avec apigateway.amazonaws.com
comme entité approuvée, attachez la politique précédente au rôle IAM et définissez l’ARN du rôle IAM sur la propriété cloudWatchRoleArn de votre compte. Vous devez définir la propriété CloudWatchroLearn séparément pour chaque Région AWS dans laquelle vous souhaitez activer CloudWatch Logs.
Si vous recevez une erreur lors de la configuration de l’ARN de rôle IAM, vérifiez les paramètres de votre compte AWS Security Token Service pour vous assurer que AWS STS est activé dans la Région que vous utilisez. Pour en savoir plus sur l’activation de AWS STS, consultez Gestion d’AWS STS dans une région AWS dans le Guide de l’utilisateur IAM.
Configuration de la journalisation de l’API CloudWatch à l’aide de la console API Gateway
Pour configurer la journalisation d’API CloudWatch, vous devez avoir déployé l’API jusqu’à une étape. Vous devez également avoir configuré un ARN de rôle CloudWatch Logs approprié pour votre compte.
Connectez-vous à la console API Gateway à l’adresse https://console.aws.amazon.com/apigateway
. -
Dans le volet de navigation principal, choisissez Paramètres, puis sous Journalisation, choisissez Modifier.
-
Pour ARN de rôle du journal CloudWatch, entrez un ARN de rôle IAM avec les autorisations appropriées. Vous devez le faire une fois pour chaque Compte AWS qui crée des API à l’aide d’API Gateway.
-
Dans le volet de navigation principal, choisissez API, puis effectuez l’une des opérations suivantes :
-
Choisissez une API existante, puis une étape.
-
Créez une API et déployez-la dans une étape.
-
Dans le volet de navigation principal, choisissez Étapes.
-
Dans la section Journaux et suivi, choisissez Modifier.
-
Pour activer la journalisation de l’exécution :
-
Sélectionnez un niveau de journalisation dans le menu déroulant CloudWatch Logs. Les niveaux de journalisation sont les suivants :
-
Désactivé – La journalisation n’est pas activée pour cette étape.
-
Erreurs uniquement – La journalisation n’est activée que pour les erreurs.
-
Journaux d’erreurs et d’informations – La journalisation est activée pour tous les événements.
-
-
(Facultatif) Sélectionnez Suivi des données pour activer la journalisation du suivi des données pour votre étape. Cela peut être utile pour dépanner les API, mais peut entraîner la consignation de données sensibles.
Note
Nous vous recommandons de ne pas activer Suivi des données pour les API de production.
-
(Facultatif) Sélectionnez Métriques détaillées pour activer les métriques CloudWatch détaillées.
Pour plus d’informations sur les métriques CloudWatch, consultez Surveillance de l’exécution d’une API REST à l’aide des métriques Amazon CloudWatch.
-
-
Pour activer la journalisation des accès :
-
Activez Journalisation des accès personnalisée.
-
Pour ARN de destination des journaux d’accès, entrez l’ARN d’un groupe de journaux. Le format ARN est le suivant :
arn:aws:logs:
.{region}
:{account-id}
:log-group:log-group-name
-
Dans Format des journaux, entrez un format de journal. Vous pouvez choisir CLF, JSON, XML ou CSV. Pour en savoir plus sur les exemples de formats de journal, consultez Formats des journaux CloudWatch pour API Gateway.
-
-
Sélectionnez Enregistrer les modifications.
Note
Vous pouvez activer la journalisation de l’exécution et la journalisation de l’accès indépendamment l’une de l’autre.
API Gateway est maintenant prêt à enregistrer les demandes adressées à votre API. Vous n’avez pas besoin de redéployer l’API lorsque vous mettez à jour les paramètres de l’étape, les journaux ou variables de l’étape.
Configurez la journalisation de l’API CloudWatch à l’aide de AWS CloudFormation
Utilisez le modèle d’exemple AWS CloudFormation suivant pour créer un groupe de journaux Amazon CloudWatch Logs et configurer la journalisation de l’exécution et des accès pour une étape. Pour activer CloudWatch Logs, vous devez accorder l’autorisation API Gateway pour lire et écrire les journaux dans CloudWatch pour votre compte. Pour en savoir plus, consultez Associer le compte au rôle IAM dans le Guide de l’utilisateur AWS CloudFormation.
TestStage: Type: AWS::ApiGateway::Stage Properties: StageName: test RestApiId: !Ref MyAPI DeploymentId: !Ref Deployment Description: "test stage description" MethodSettings: - ResourcePath: "/*" HttpMethod: "*" LoggingLevel: INFO AccessLogSetting: DestinationArn: !GetAtt MyLogGroup.Arn Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId MyLogGroup: Type: AWS::Logs::LogGroup Properties: LogGroupName: !Join - '-' - - !Ref MyAPI - access-logs