Concepts AWS X-Ray

AWS X-Ray reçoit des données à partir des services sous forme de segments. X-Ray regroupe ensuite les segments ayant une demande commune dans des traces. X-Ray traite les traces pour générer un graphe de service qui fournit une représentation visuelle de votre application.

Segments

Les ressources de calcul qui exécutent la logique de votre application envoient des données concernant leur travail sous forme de segments. Chaque segment indique le nom de la ressource, des détails concernant la demande, ainsi que des détails sur le travail effectué. Par exemple, lorsqu'une demande HTTP parvient à votre application, elle peut enregistrer les données suivantes sur :

• L'hôte : nom d'hôte, alias ou adresse IP

• La demande : méthode, adresse du client, chemin, agent utilisateur

• La réponse : statut, contenu

• Le travail effectué : heures de début et de fin, sous-segments

• Problèmes qui se produisent : erreurs, défauts et exceptions, y compris la capture automatique des piles d'exceptions.

Le SDK X-Ray recueille des informations à partir des en-têtes de demande et de réponse, du code de votre application et des métadonnées relatives auxAWS ressources sur lesquelles elle s'exécute. Vous choisissez les données à collecter en modifiant la configuration ou le code de votre application pour instrumenter les demandes entrantes, les demandes en aval et les clients duAWS SDK.

Demandes transmises

Si un équilibreur de charge ou un autre intermédiaire transmet une demande à votre application, X-Ray extrait l'adresse IP du client de l'X-Forwarded-Foren-tête de la demande plutôt que de l'adresse IP source du paquet IP. L'adresse IP du client enregistrée pour une demande transférée peut être falsifiée. Elle ne doit donc pas être fiable.

Vous pouvez utiliser le kit SDK X-Ray pour enregistrer des informations supplémentaires, telles que des annotations et des métadonnées. Pour plus d'informations sur la structure et les informations enregistrées dans les segments et les sous-segments, consultez Documents de segment AWS X-Ray. Les documents segmentés peuvent contenir jusqu'à 64 kB.

Sous-segments

Un segment peut décomposer les données concernant le travail effectué en sous-segments. Les sous-segments fournissent des informations de durée plus précises et des détails sur les appels en aval effectués par votre application pour satisfaire la demande initiale. Un sous-segment peut contenir des informations supplémentaires sur un appel à unAWS service, à une API HTTP externe ou à une base de données SQL. Vous pouvez même définir des sous-segments arbitraires pour instrumenter des fonctions spécifiques ou des lignes de code dans votre application.

Pour les services qui n'envoient pas leurs propres segments, comme Amazon DynamoDB, X-Ray utilise des sous-segments pour générer des segments inférés et des nœuds en aval sur la carte des services. Cela vous permet de voir l'ensemble de vos dépendances en aval, même si elles ne prennent pas en charge le suivi ou sont externes.

Les sous-segments représentent la vue par votre application d'un appel en aval en tant que client. Si le service en aval est également instrumenté, le segment qu'il envoie remplace le segment déduit généré à partir du sous-segment du client en amont. Le nœud sur le graphique de services utilise toujours des informations provenant du segment du service, si elle sont disponibles, tandis que la zone périphérique entre les deux nœuds utilise le sous-segment du service en amont.

Par exemple, lorsque vous appelez DynamoDB avec un clientAWS SDK instrumenté, le kit SDK X-Ray enregistre un sous-segment pour cet appel. DynamoDB n'envoie aucun segment. Par conséquent, le segment déduit de la trace, le nœud DynamoDB sur le graphe de service et la limite entre votre service et DynamoDB contiennent tous des informations provenant du sous-segment.

Lorsque vous appelez un autre service instrumenté avec une application instrumentée, le service en aval envoie son propre segment pour enregistrer sa vue de l'appel que le service en amont a enregistré dans un sous-segment. Dans le graphique de services, les deux nœuds de service contiennent des informations de synchronisation et des informations d'erreur provenant de ces services, tandis que l'arc entre eux contient des informations provenant du sous-segment du service en amont.

Ces deux points de vue sont utiles, car le service en aval enregistre précisément le moment auquel il a commencé et terminé le travail sur la demande et le service en amont enregistre la latence de l'aller-retour, y compris le temps passé par la demande pour circuler entre les deux services.

Graphique de services

X-Ray utilise les données envoyées par votre application pour générer un graphe de service. ChaqueAWS ressource qui envoie des données à X-Ray apparaît sous la forme d'un service dans le graphique. Les zones périphériques connectent les services qui fonctionnent ensemble pour traiter les demandes. Les arcs connectent les clients à votre application, et votre application aux ressources et services en aval qu'elle utilise.

Noms des services

Le segmentname doit correspondre au nom de domaine ou au nom logique du service qui génère le segment. Toutefois, cela n'est pas appliqué. Toute application autorisée PutTraceSegmentspeut envoyer des segments avec n'importe quel nom.

Un graphique de services est un document au format JSON qui contient des informations sur les services et ressources qui composent votre application. La console X-Ray utilise le graphe de service pour générer une visualisation ou une carte de service.

Dans le cas d'une application distribuée, X-Ray combine les nœuds de tous les services qui traitent les demandes ayant le même identifiant de trace dans un graphe de service unique. Le premier service qui traite la demande ajoute un en-tête de suivi, lequel est ensuite propagé entre le serveur frontal et les services appelés.

Par exemple, Scorekeep exécute une API web qui appelle un microservice (une fonction AWS Lambda) pour générer un nom aléatoire à l'aide d'une bibliothèque Node.js. Le SDK X-Ray pour Java génère l'identifiant de trace et l'inclut dans les appels à Lambda. Lambda envoie des données de suivi et transmet l'identifiant de trace à la fonction. Le kit SDK X-Ray pour Node.js utilise également l'ID de suivi pour envoyer des données. Par conséquent, les nœuds de l'API, du service Lambda et de la fonction Lambda apparaissent tous comme des nœuds distincts mais connectés sur la carte des services.

Les données du graphe de service sont conservées pendant 30 jours.

Suivis

Un ID de suivi permet de suivre le cheminement d'une demande au sein de votre application. Un suivi recueille tous les segments générés par une seule demande. Cette demande est généralement une requête HTTP GET ou POST qui passe par un équilibreur de charge, atteint le code de votre application et génère des appels en aval vers d'autresAWS services ou des API Web externes. Le premier service pris en charge avec lequel la demande HTTP interagit ajoute un en-tête d'ID de suivi à la demande et le propage en aval pour suivre la latence, l'organisation et les autres données de la demande.

Les données du graphe de service sont conservées pendant 30 jours.

Echantillonnage

Pour s'assurer que le suivi est efficace et s'assurer que l'échantillon est représentatif des demandes servies par votre application, le kit SDK X-Ray applique un algorithme d'échantillonnage pour déterminer quelles demandes sont servies. Par défaut, le SDK X-Ray enregistre la première demande chaque seconde, ainsi que cinq pour cent des demandes supplémentaires.

Afin de ne pas encourir de frais de service lors de la mise en route, le taux d'échantillonnage par défaut est prudent. Vous pouvez configurer X-Ray pour modifier la règle d'échantillonnage par défaut et configurer des règles supplémentaires qui appliquent l'échantillonnage en fonction des propriétés du service ou de la demande.

Par exemple, vous souhaiterez peut-être désactiver l'échantillonnage et suivre toutes les demandes d'appels qui modifient l'état ou gèrent des utilisateurs ou des transactions. Pour les appels en lecture seule à fort volume, tels que les appels d'interrogation d'arrière-plan, les vérifications de l'état ou la maintenance des connexions, vous pouvez effectuer un échantillon à faible taux et obtenir malgré tout suffisamment de données pour voir tout problème éventuel.

Pour plus d'informations, veuillez consulter Configuration de règles d'échantillonnage .

En-tête de suivi

Toutes les demandes sont suivies jusqu'à un minimum configurable. Une fois ce minimum atteint, seul un certain pourcentage des demandes est suivi afin d'éviter les coûts superflus. La décision d'échantillonnage et l'ID de suivi sont ajoutés aux demandes HTTP dans des en-têtes de suivi nommés X-Amzn-Trace-Id. Le premier service intégré aux rayons X auquel la demande accède ajoute un en-tête de suivi, qui est lu par le SDK X-Ray et inclus dans la réponse.

Exemple En-tête de suivi avec ID de suivi racine et décision d'échantillonnage

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1

Sécurité de l'en-tête de suivi

Un en-tête de suivi peut provenir du SDK X-Ray, d'unAWS service ou de la demande du client. Votre application peut supprimer X-Amzn-Trace-Id des demandes entrantes, afin d'éviter les problèmes provoqués par les utilisateurs qui ajoutent des ID de suivi ou des décisions d'échantillonnage à leurs demandes.

L'en-tête de suivi peut également contenir un ID de segment parent si la demande provenait d'une application instrumentée. Par exemple, si votre application appelle une API Web HTTP en aval avec un client HTTP instrumenté, le SDK X-Ray ajoute l'ID de segment de la demande d'origine à l'en-tête de suivi de la demande en aval. Une application instrumentée qui sert la demande en aval peut enregistrer l'ID de segment parent pour connecter les deux demandes.

Exemple En-tête de suivi avec ID de suivi racine, ID de segment parent et décision d'échantillonnage

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1

Lineagepeuvent être ajoutés à l'en-tête de trace par Lambda et d'autresAWS services dans le cadre de leurs mécanismes de traitement, et ne doivent pas être utilisés directement.

Exemple En-tête de traçage avec Lineage

X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1;Lineage=a87bd80c:1|68fd508a:5|c512fbe3:2

Expressions de filtrage

Même avec l'échantillonnage, une application complexe génère beaucoup de données. LaAWS X-Ray console fournit une easy-to-navigate vue du graphe des services. Elle affiche des informations de santé et de performances qui vous aide à identifier les problèmes et les occasions d'optimiser votre application. Pour les suivis avancés, vous pouvez explorer les suivis pour les demandes individuelles ou utiliser des expressions de filtrage pour trouver des suivis liés à des chemins ou des utilisateurs spécifiques.

Groups

En élargissant les expressions de filtre, X-Ray prend également en charge la fonctionnalité de groupe. En utilisant une expression de filtrage, vous pouvez définir les critères en vertu desquels vous acceptez les suivis dans le groupe.

Vous pouvez appeler le groupe par son nom ou par Amazon Resource Name (ARN) pour générer son propre graphe de service, des résumés de suivi et des CloudWatch statistiques Amazon. Une fois qu'un groupe est créé, les traces entrantes sont comparées à l'expression de filtre du groupe lorsqu'elles sont stockées dans le service X-Ray. Les mesures relatives au nombre de traces correspondant à chaque critère sont publiées à CloudWatch chaque minute.

Le fait de mettre à jour l'expression de filtrage d'un groupe n'a pas pour effet de modifier les données déjà enregistrées. La mise à jour s'applique uniquement aux suivis ultérieurs. Cela peut entraîner la fusion des expressions nouvelles et anciennes dans le graphique. Pour éviter cela, supprimez le groupe actuel et créez-en un nouveau.

Note

Les groupes sont facturés en fonction du nombre de suivis récupérés qui correspondent à l'expression de filtrage. Pour en savoir plus, consultez PricingAWS X-Ray (Tarification).

Pour plus d'informations sur les groupes, consultezConfigurer des groupes.

Annotations et métadonnées

Lorsque vous instrumentez votre application, le SDK X-Ray enregistre des informations sur les demandes entrantes et sortantes, lesAWS ressources utilisées et l'application elle-même. Vous pouvez ajouter d'autres informations dans le document de segment, comme des annotations et des métadonnées. Les annotations et les métadonnées sont agrégées au niveau du suivi et peuvent être ajoutées à n'importe quel segment ou sous-segment.

Les annotations sont de simples paires clé-valeur, indexées en vue de leur utilisation avec les expressions de filtre. Utilisez les annotations pour enregistrer les données que vous souhaitez utiliser pour regrouper les suivis dans la console ou lors de l'appel de l'API GetTraceSummaries.

X-Ray indexe jusqu'à 50 annotations par trace.

Les métadonnées sont des paires clé-valeur dont les valeurs peuvent être de tout type (objet et liste inclus), mais elles ne sont pas indexées. Utilisez les métadonnées pour enregistrer les données qui doivent être stockées dans le suivi, mais n'ont pas besoin d'être utilisées pour explorer les suivis.

Vous pouvez afficher les annotations et les métadonnées dans les détails du segment ou du sous-segment dans la console X-Ray.

Erreurs, anomalies et exceptions

X-Ray suit les erreurs qui se produisent dans le code de votre application et les erreurs renvoyées par les services en aval. Les erreurs sont classées comme suit :

• Error— Erreurs du client (erreurs de la série 400)

• Fault— Défaillances du serveur (erreurs de la série 500)

• Throttle— Erreurs de limitation (429 demandes de trop)

Lorsqu'une exception se produit alors que votre application traite une demande instrumentée, le SDK X-Ray enregistre les détails de l'exception, y compris la trace de pile, si disponible. Vous pouvez afficher les exceptions dans les détails des segments dans la console X-Ray.