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.

Utilisation CloudWatch pour surveiller et enregistrer les données de l'API GraphQL

Vous pouvez enregistrer et déboguer votre API GraphQL à l'aide de CloudWatch métriques et CloudWatch de journaux. Ces outils permettent aux développeurs de surveiller les performances, de résoudre les problèmes et d'optimiser efficacement leurs opérations GraphQL.

CloudWatch metrics est un outil qui fournit un large éventail de mesures pour surveiller les performances et l'utilisation des API. Ces indicateurs se répartissent en deux catégories principales :

Le guide présente également les mesures améliorées, qui fournissent des données plus détaillées sur les performances du résolveur, les interactions entre les sources de données et les opérations GraphQL individuelles. Ces indicateurs fournissent des informations plus détaillées mais entraînent des coûts supplémentaires.

CloudWatch Logs est un outil qui active les fonctionnalités de journalisation pour vos API GraphQL. Les journaux peuvent être définis à deux niveaux de l'API :

Vous pouvez configurer la journalisation, interpréter les entrées du journal et utiliser les données du journal à des fins de dépannage et d'optimisation. AWS AppSync fournit différents types de journaux qui révèlent les données d'exécution, d'analyse, de validation et de résolution des champs de votre requête.

Installation et configuration

Pour activer la journalisation automatique sur une API GraphQL, utilisez la AWS AppSync console.

Configuration manuelle des rôles IAM

Si vous choisissez d'utiliser un rôle IAM existant, celui-ci doit accorder AWS AppSync les autorisations requises pour écrire des journaux. CloudWatch Pour configurer cela manuellement, vous devez fournir un ARN de rôle de service afin qu'il AWS AppSync puisse assumer le rôle lors de l'écriture des journaux.

Dans la console IAM, créez une nouvelle politique AWSAppSyncPushToCloudWatchLogsPolicy dont le nom possède la définition suivante :

JSON

{
    "Version":"2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

Créez ensuite un nouveau rôle avec ce nom AWSAppSyncPushToCloudWatchLogsRole et associez-lui la politique nouvellement créée. Modifiez la relation de confiance pour ce rôle comme suit :

JSON

{
    "Version":"2012-10-17",
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "Service": "appsync.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
        }
    ]
}

Copiez l'ARN du rôle et utilisez-le lors de la configuration de la journalisation pour une API AWS AppSync GraphQL.

CloudWatch métriques

Vous pouvez utiliser CloudWatch des métriques pour surveiller et émettre des alertes concernant des événements spécifiques susceptibles de générer des codes d'état HTTP ou de latence. Les métriques suivantes sont émises :

Real-time abonnements

Toutes les métriques sont émises dans une dimension : GraphQLAPIID. Cela signifie que toutes les métriques sont couplées avec des ID d'API GraphQL. Les statistiques suivantes sont liées aux abonnements GraphQL en version pure WebSockets :

Comparaison des messages entrants et sortants

Lorsqu'une mutation est exécutée, les champs d'abonnement contenant la directive @aws_subscribe pour cette mutation sont invoqués. Chaque appel d'abonnement génère un message entrant. Par exemple, si deux champs d'abonnement spécifient la même mutation dans @aws_subscribe, deux messages entrants sont générés lorsque cette mutation est appelée.

Un message sortant équivaut à 5 Ko de données transmises aux WebSocket clients. Par exemple, l'envoi de 15 Ko de données à 10 clients génère 30 messages sortants (15 ko * 10 clients/5 ko par message = 30 messages).

Vous pouvez demander des augmentations de quota pour les messages entrants ou sortants. Pour plus d'informations, consultez les AWS AppSync points de terminaison et les quotas dans le guide de référence AWS générale et les instructions relatives à la demande d'augmentation de quota dans le guide de l'utilisateur des quotas de service.

Métriques améliorées

Les métriques améliorées émettent des données granulaires sur l'utilisation et les performances des API, telles que le nombre de AWS AppSync requêtes et d'erreurs, la latence et le cache hits/misses. Toutes les données métriques améliorées sont envoyées à votre CloudWatch compte et vous pouvez configurer les types de données qui seront envoyés.

Ces statistiques sont disponibles sur les différentes pages de paramètres de la AWS AppSync console. Sur la page des paramètres de l'API, la section Mesures améliorées vous permet d'activer ou de désactiver les éléments suivants :

Comportement des métriques des résolveurs  : ces options contrôlent la manière dont les métriques supplémentaires sont collectées pour les résolveurs. Vous pouvez choisir d'activer les mesures complètes du résolveur de demandes (mesures activées pour tous les résolveurs des demandes) ou les métriques par résolveur (mesures activées uniquement pour les résolveurs dont la configuration est activée). Les options suivantes sont disponibles :

Comportement des métriques des sources de données  : ces options contrôlent la manière dont les métriques supplémentaires sont collectées pour les sources de données. Vous pouvez choisir d'activer les mesures de source de données de demande complètes (mesures activées pour toutes les sources de données dans les demandes) ou les métriques par source de données (mesures activées uniquement pour les sources de données dont la configuration est activée). Les options suivantes sont disponibles :

Métriques opérationnelles  : active les métriques de niveau opérationnel de GraphQL.

CloudWatch journaux

Vous pouvez configurer deux types de journalisation sur n'importe quelle API GraphQL nouvelle ou existante : au niveau de la demande et au niveau du champ.

Request-level journaux

Lorsque la journalisation au niveau de la demande (inclure du contenu détaillé) est configurée, les informations suivantes sont enregistrées :

Field-level journaux

Lorsque la journalisation au niveau des champs est configurée, les informations suivantes sont enregistrées :

Si vous activez la journalisation, AWS AppSync gère les CloudWatch journaux. 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 avec ces journaux.

Lorsque vous activez la journalisation sur une API GraphQL et que vous envoyez des requêtes, vous AWS AppSync créez un groupe de journaux et enregistrez les flux dans le groupe de journaux. Le groupe de journaux est nommé selon le format /aws/appsync/apis/{graphql_api_id}. Dans chaque groupe de journaux, les journaux sont également divisés en flux de journaux. Ces derniers sont classés selon l'heure du dernier événement lors de la consignation des données.

Chaque événement de journal est marqué avec le x-amzn- RequestId de cette demande. Cela vous permet de filtrer les événements du journal CloudWatch pour obtenir toutes les informations enregistrées concernant cette demande. Vous pouvez les obtenir RequestId à partir des en-têtes de réponse de chaque requête GraphQL AWS AppSync .

La journalisation au niveau du champ est configurée avec les niveaux de journaux suivants :

Avantages de la surveillance

Vous pouvez utiliser la journalisation et les métriques pour identifier, dépanner et optimiser vos requêtes GraphQL. Par exemple, cela vous aidera à déboguer les problèmes de latence à l'aide des informations de suivi consignées pour chaque champ de la requête. Pour illustrer cela, supposons que vous utilisiez un ou plusieurs résolveurs imbriqués dans une requête GraphQL. Un exemple d'opération de champ dans CloudWatch Logs peut ressembler à ce qui suit :

{
    "path": [
        "singlePost",
        "authors",
        0,
        "name"
    ],
    "parentType": "Post",
    "returnType": "String!",
    "fieldName": "name",
    "startOffset": 416563350,
    "duration": 11247
}

Cela peut correspondre à un schéma GraphQL, comme illustré ci-dessous :

type Post {
  id: ID!
  name: String!
  authors: [Author]
}

type Author {
  id: ID!
  name: String!
}

type Query {
  singlePost(id:ID!): Post
}

Dans les résultats du journal précédent, le chemin affiche un seul élément de vos données renvoyées par l'exécution d'une requête nomméesinglePost(). Dans cet exemple, il représente le champ de nom au premier index (0). Le StartOffset donne un décalage à partir du début de l'opération de requête GraphQL. La durée est le temps total nécessaire pour résoudre le champ. Ces valeurs peuvent être utiles afin de déterminer la raison pour laquelle les données d'une source de données spécifique sont exécutées plus lentement que prévu, ou si un champ spécifique ralentit l'ensemble de la requête. Par exemple, vous pouvez choisir d'augmenter le débit provisionné pour une table Amazon DynamoDB ou de supprimer un champ spécifique d'une requête qui entraîne un mauvais fonctionnement de l'opération globale.

À compter du 8 mai 2019, AWS AppSync génère les événements de journal au format JSON entièrement structuré. Cela peut vous aider à utiliser des services d'analyse de CloudWatch journaux tels que Logs Insights et Amazon OpenSearch Service pour comprendre les performances de vos requêtes GraphQL et les caractéristiques d'utilisation de vos champs de schéma. Par exemple, vous pouvez identifier facilement les résolveurs rencontrant des latences importantes et qui pourraient être la cause profonde d'un problème de performances. Vous pouvez également identifier les champs utilisés le plus et le moins fréquemment dans votre schéma et évaluer l'impact des dépréciations des champs GraphQL.

Détection des conflits et journalisation de la synchronisation

Si la journalisation dans les CloudWatch journaux d'une AWS AppSync API est configurée avec le niveau de journalisation du résolveur de champs défini sur Tout, AWS AppSync elle transmet des informations de détection et de résolution des conflits au groupe de journaux. Cela fournit un aperçu précis de la manière dont l' AWS AppSync API a réagi à un conflit. Pour vous aider à interpréter la réponse, les informations suivantes sont fournies dans les journaux :

Utiliser le nombre de jetons pour optimiser vos demandes

Les requêtes qui consomment moins ou moins de 1 500 de mémoire et KB-seconds de temps de processeur virtuel se voient attribuer un jeton. Les requêtes dont la consommation de ressources est supérieure à 1 500 KB-seconds reçoivent des jetons supplémentaires. Par exemple, si une demande en consomme 3 350 KB-seconds, AWS AppSync attribue trois jetons (arrondis à la valeur entière supérieure) à la demande. Par défaut, AWS AppSync alloue un maximum de 5 000 ou 10 000 jetons de demande par seconde aux API de votre compte, en fonction de la AWS région dans laquelle il est déployé. Si vos API utilisent chacune en moyenne deux jetons par seconde, vous serez limité à 2 500 ou 5 000 requêtes par seconde, respectivement. Si vous avez besoin de plus de jetons par seconde que la quantité allouée, vous pouvez soumettre une demande pour augmenter le quota par défaut pour le taux de jetons demandés. Pour plus d'informations, consultez les sections AWS AppSync Points de terminaison et quotas dans le Références générales AWS guide et Demande d'augmentation de quota dans le Guide de l'utilisateur des quotas de service.

Un nombre élevé de jetons par demande peut indiquer qu'il est possible d'optimiser vos demandes et d'améliorer les performances de votre API. Les facteurs qui peuvent augmenter le nombre de jetons par demande sont notamment les suivants :

Limites de taille des journaux

Par défaut, si la journalisation a été activée, jusqu'à 1 Mo de journaux par demande AWS AppSync sera envoyé. Les journaux dépassant cette taille seront tronqués. Pour réduire la taille des journaux, choisissez le niveau de ERROR journalisation pour les journaux au niveau des champs et désactivez la VERBOSE journalisation, ou désactivez complètement les journaux au niveau des champs si cela n'est pas nécessaire. Comme alternative au niveau de ALL journalisation, vous pouvez utiliser Enhanced Metrics pour obtenir des métriques sur des résolveurs, des sources de données ou des opérations GraphQL spécifiques, ou utiliser les utilitaires de journalisation fournis par AppSync pour enregistrer uniquement les informations nécessaires.

Référence du type de journal

RequestSummary

{
     "logType": "RequestSummary",
     "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
     "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4",
     "statusCode": 200,
     "latency": 242000000
}

ExecutionSummary

{
    "duration": 217406145,
    "logType": "ExecutionSummary",
    "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
    "startTime": "2019-01-01T06:06:18.956Z",
    "endTime": "2019-01-01T06:06:19.174Z",
    "parsing": {
        "startOffset": 49033,
        "duration": 34784
    },
    "version": 1,
    "validation": {
        "startOffset": 129048,
        "duration": 69126
    },
    "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4"
}

Tracing

{
    "duration": 216820346,
    "logType": "Tracing",
    "path": [
        "putItem"
    ],
    "fieldName": "putItem",
    "startOffset": 178156,
    "resolverArn": "arn:aws:appsync:us-east-1:111111111111:apis/pmo28inf75eepg63qxq4ekoeg4/types/Mutation/fields/putItem",
    "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
    "parentType": "Mutation",
    "returnType": "Item",
    "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4"
}

Analyser vos journaux avec CloudWatch Logs Insights

Voici des exemples de requêtes que vous pouvez exécuter pour obtenir des informations exploitables sur les performances et l'état de vos opérations GraphQL. Ces exemples sont disponibles sous forme d'exemples de requêtes dans la console CloudWatch Logs Insights. Dans la CloudWatch console, choisissez Logs Insights, sélectionnez le groupe de AWS AppSync journaux pour votre API GraphQL, puis choisissez AWS AppSync des requêtes sous Exemples de requêtes.

La requête suivante renvoie les 10 principales requêtes GraphQL avec le maximum de jetons consommés :

filter @message like "Tokens Consumed"
| parse @message "* Tokens Consumed: *" as requestId, tokens
| sort tokens desc
| display requestId, tokens
| limit 10

La requête suivante renvoie les 10 principaux résolveurs rencontrant une latence maximale :

  fields resolverArn, duration
| filter logType = "Tracing"
| limit 10
| sort duration desc

La requête suivante renvoie les résolveurs les plus fréquemment appelés :

  fields ispresent(resolverArn) as isRes
| stats count() as invocationCount by resolverArn
| filter isRes and logType = "Tracing"
| limit 10
| sort invocationCount desc

La requête suivante renvoie les résolveurs rencontrant le plus grand nombre d'erreurs dans les modèles de mappage :

  fields ispresent(resolverArn) as isRes
| stats count() as errorCount by resolverArn, logType
| filter isRes and (logType = "RequestMapping" or logType = "ResponseMapping") and fieldInError
| limit 10
| sort errorCount desc

La requête suivante renvoie les statistiques de latence du résolveur :

  fields ispresent(resolverArn) as isRes
| stats min(duration), max(duration), avg(duration) as avg_dur by resolverArn
| filter isRes and logType = "Tracing"
| limit 10
| sort avg_dur desc

La requête suivante renvoie les statistiques de latence du champ :

  stats min(duration), max(duration), avg(duration) as avg_dur
  by concat(parentType, '/', fieldName) as fieldKey
| filter logType = "Tracing"
| limit 10
| sort avg_dur desc

Les résultats des requêtes CloudWatch Logs Insights peuvent être exportés vers des CloudWatch tableaux de bord.

Analysez vos journaux avec OpenSearch Service

Vous pouvez rechercher, analyser et visualiser vos AWS AppSync journaux avec Amazon OpenSearch Service afin d'identifier les goulots d'étranglement en matière de performances et les causes profondes des problèmes opérationnels. Vous pouvez identifier les résolveurs rencontrant la latence maximale et le maximum d'erreurs. En outre, vous pouvez utiliser les OpenSearch tableaux de bord pour créer des tableaux de bord dotés de visualisations puissantes. OpenSearch Dashboards est un outil de visualisation et d'exploration de données open source disponible dans OpenSearch Service. À l'aide de OpenSearch tableaux de bord, vous pouvez surveiller en permanence les performances et l'état de vos opérations GraphQL. Par exemple, vous pouvez créer des tableaux de bord pour visualiser la latence P90 de vos requêtes GraphQL et explorer les latences P90 de chaque résolveur.

Lorsque vous utilisez OpenSearch Service, utilisez « cwl* » comme modèle de filtre pour rechercher OpenSearch des index. OpenSearch Le service indexe les journaux diffusés à partir de CloudWatch Logs avec le préfixe « cwl- ». Pour différencier les journaux d' AWS AppSync API CloudWatch des autres journaux envoyés au OpenSearch Service, nous vous recommandons d'ajouter une expression de filtre supplémentaire graphQLAPIID.keyword=YourGraphQLAPIID à votre recherche.

Migration du format de journal

Les événements de journal AWS AppSync générés sont principalement au format JSON entièrement structuré. Cependant, certains messages de diagnostic et de traitement intermédiaire peuvent être émis dans un format non structuré. Si vous devez migrer des journaux non structurés vers un JSON entièrement structuré, vous pouvez utiliser un script disponible dans l'GitHub exemple.

Vous pouvez également utiliser des filtres https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogsConcepts.html métriques CloudWatch pour transformer les données du journal en CloudWatch mesures numériques, afin de pouvoir les représenter graphiquement ou définir une alarme sur celles-ci.