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.
# Choix d'une interface
AWS X-Ray peut fournir des informations sur le fonctionnement de votre application et sur la manière dont elle interagit avec d'autres services et ressources. Une fois que vous avez instrumenté ou configuré votre application, X-Ray collecte des données de suivi lorsque votre application répond aux demandes. Vous pouvez analyser ces données de suivi pour identifier les problèmes de performances, résoudre les erreurs et optimiser vos ressources. Ce guide explique comment interagir avec X-Ray en respectant les consignes suivantes :
+ Utilisez-en un AWS Management Console si vous souhaitez démarrer rapidement ou si vous pouvez utiliser des visualisations prédéfinies pour effectuer des tâches de base.
+ Choisissez la CloudWatch console Amazon pour bénéficier de l'expérience utilisateur la plus récente contenant toutes les fonctionnalités de la console X-Ray.
+ Utilisez la console X-Ray si vous souhaitez une interface plus simple ou si vous ne voulez pas changer la façon dont vous interagissez avec X-Ray.
+ Utilisez un SDK si vous avez besoin de fonctionnalités de suivi, de surveillance ou de journalisation plus personnalisées que celles qu'un logiciel AWS Management Console peut fournir.
+ Choisissez le ADOT SDK si vous souhaitez un SDK indépendant du fournisseur basé sur le SDK open source avec des couches supplémentaires de OpenTelemetry sécurité et d'optimisation. AWS
+ Choisissez le SDK X-Ray si vous souhaitez un SDK plus simple ou si vous ne souhaitez pas mettre à jour le code de votre application.
+ Utilisez les opérations de l'API X-Ray si un SDK ne prend pas en charge le langage de programmation de votre application.
Le schéma suivant vous aide à choisir comment interagir avec X-Ray :
![\[X-Ray affiche des informations détaillées sur les demandes de candidature.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/xray-choose-interface.png)
**Topics**
+ [Utiliser un SDK](aws-xray-interface-sdk.md)
+ [Utiliser une console](aws-xray-interface-console.md)
+ [Utiliser l'API X-Ray](xray-api.md)
# Utiliser un SDK
**Note**
Avis de SDK/Daemon maintenance de X-Ray — Le 25 février 2026, le AWS X-Ray SDKs/Daemon passera en mode maintenance, où les versions du SDK et du Daemon de X-Ray AWS seront limitées uniquement pour résoudre les problèmes de sécurité. Pour plus d'informations sur le calendrier de support, consultez[Chronologie du support pour le SDK et Daemon X-Ray](xray-sdk-daemon-timeline.md). Nous vous recommandons de migrer vers OpenTelemetry. Pour plus d'informations sur la migration vers OpenTelemetry, voir [Migration de l'instrumentation X-Ray vers OpenTelemetry l'instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
Utilisez un SDK si vous souhaitez utiliser une interface de ligne de commande ou si vous avez besoin de fonctionnalités de suivi, de surveillance ou de journalisation plus personnalisées que celles disponibles dans un AWS Management Console. Vous pouvez également utiliser un AWS SDK pour développer des programmes utilisant le X-Ray APIs. Vous pouvez utiliser le SDK AWS Distro for OpenTelemetry (ADOT) ou le SDK X-Ray.
Si vous utilisez un SDK, vous pouvez ajouter des personnalisations à votre flux de travail à la fois lorsque vous instrumentez votre application et lorsque vous configurez votre collecteur ou votre agent. Vous pouvez utiliser un SDK pour effectuer les tâches suivantes que vous ne pouvez pas effectuer à l'aide d'un AWS Management Console :
+ Publiez des métriques personnalisées : échantillonnez des métriques à des résolutions élevées (jusqu'à 1 seconde), utilisez plusieurs dimensions pour ajouter des informations sur une métrique et agréger des points de données dans un ensemble de statistiques.
+ Personnalisez votre collecteur : personnalisez la configuration de n'importe quelle partie d'un collecteur, y compris le récepteur, le processeur, l'exportateur et le connecteur.
+ Personnalisez votre instrumentation : personnalisez les segments et les sous-segments, ajoutez des paires clé-valeur personnalisées en tant qu'attributs et créez des métriques personnalisées.
+ Créez et mettez à jour des règles d'échantillonnage par programmation.
Utilisez le ADOT SDK si vous souhaitez bénéficier de la flexibilité d'un OpenTelemetry SDK standardisé avec des niveaux supplémentaires de AWS sécurité et d'optimisation. Le SDK AWS Distro for OpenTelemetry (ADOT) est un package indépendant du fournisseur qui permet l'intégration avec les backends d'autres fournisseurs et AWS non-services sans avoir à réinstrumenter votre code.
Utilisez le SDK X-Ray si vous utilisez déjà le SDK X-Ray, si vous l'intégrez uniquement aux AWS backends et si vous ne souhaitez pas modifier la façon dont vous interagissez avec X-Ray ou le code de votre application.
Pour plus d'informations sur chaque fonctionnalité, consultez[Choisir entre The AWS Distro for OpenTelemetry et X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
## Utiliser le ADOT SDK
Le ADOT SDK est un ensemble de bibliothèques APIs, d'agents et de bibliothèques open source qui envoient des données aux services principaux. ADOTest pris en charge par AWS, s'intègre à plusieurs backends et agents et fournit un grand nombre de bibliothèques open source gérées par la OpenTelemetry communauté. Utilisez le ADOT SDK pour instrumenter votre application et collecter des journaux, des métadonnées, des métriques et des traces. Vous pouvez également l'utiliser ADOT pour surveiller les services et définir une alarme en fonction de vos indicateurs CloudWatch.
Si vous utilisez le ADOT SDK, vous disposez des options suivantes, en combinaison avec un agent :
+ Utiliser le ADOT SDK avec l'[CloudWatch agent, c'](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)est recommandé.
+ Utiliser le ADOT SDK avec le [ADOTcollecteur](https://aws-otel.github.io/docs/getting-started/collector) : recommandé si vous souhaitez utiliser un logiciel indépendant du fournisseur avec AWS plusieurs niveaux de sécurité et d'optimisation.
Pour utiliser le ADOT SDK, procédez comme suit :
+ Instrumentez votre application à l'aide du ADOT SDK. Pour plus d'informations, consultez la documentation de votre langage de programmation dans la [documentation technique ADOT](https://aws-otel.github.io/docs/introduction).
+ Configurez un ADOT collecteur pour lui indiquer où envoyer les données qu'il collecte.
Une fois que le ADOT collecteur a reçu vos données, il les envoie au backend que vous spécifiez dans la ADOT configuration. ADOTpeut envoyer des données à plusieurs backends, y compris à des fournisseurs extérieurs AWS, comme le montre le schéma suivant :
![\[Vous pouvez personnaliser le collecteur ADOT lorsque vous instrumentez votre application et configurez le collecteur.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/adot-sdk.png)
AWS mises à jour régulières ADOT pour ajouter des fonctionnalités et s'aligner sur le [OpenTelemetry](https://opentelemetry.io/docs/)cadre. Les mises à jour et les futurs plans de développement ADOT font partie d'une [feuille](https://github.com/orgs/aws-observability/projects/4) de route accessible au public. ADOTprend en charge plusieurs langages de programmation, dont les suivants :
+ Go
+ Java
+ JavaScript
+ Python
+ .NET
+ Ruby
+ PHP
Si vous utilisez Python, vous ADOT pouvez automatiquement instrumenter votre application. Pour commencer à utiliserADOT, consultez [Introduction](https://aws-otel.github.io/docs/introduction) et prise [en main de la AWS distribution pour OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector).
## Utiliser le X-Ray SDK
Le SDK X-Ray est un ensemble de AWS APIs bibliothèques qui envoient des données aux services AWS principaux. Utilisez le SDK X-Ray pour instrumenter votre application et collecter des données de suivi. Vous ne pouvez pas utiliser le SDK X-Ray pour collecter des données de log ou de métrique.
Si vous utilisez le SDK X-Ray, vous disposez des options suivantes, en combinaison avec un agent :
+ Utilisez le SDK X-Ray avec le [AWS X-Ray daemon](xray-daemon.md) — Utilisez-le si vous ne souhaitez pas mettre à jour le code de votre application.
+ Utiliser le SDK X-Ray avec l' CloudWatch agent — (recommandé) L' CloudWatch agent est compatible avec le X-Ray SDK.
Pour utiliser le SDK X-Ray, procédez comme suit :
+ Instrumentez votre application à l'aide du SDK X-Ray.
+ Configurez un collecteur pour lui indiquer où envoyer les données qu'il collecte. Vous pouvez utiliser l' CloudWatch agent ou le daemon X-Ray pour collecter vos informations de suivi.
Une fois que le collecteur ou l'agent a reçu vos données, il les envoie à un AWS backend que vous spécifiez dans la configuration de l'agent. Le SDK X-Ray peut uniquement envoyer des données à un AWS backend, comme le montre le schéma suivant :
![\[Utilisez le SDK X-Ray avec l' CloudWatch agent ou le daemon X-Ray.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/xray-sdk.png)
Si vous en utilisezJava, vous pouvez utiliser le SDK X-Ray pour instrumenter automatiquement votre application. Pour commencer à utiliser le SDK X-Ray, consultez les bibliothèques associées aux langages de programmation suivants :
+ [Go](xray-go.md)
+ [Java](xray-java.md)
+ [Node.js](xray-nodejs.md)
+ [Python](xray-python.md)
+ [.NET](xray-dotnet.md)
+ [Ruby](xray-ruby.md)
# Utiliser une console
Utilisez une console si vous souhaitez une interface utilisateur graphique (GUI) nécessitant un minimum de codage. Les utilisateurs novices de X-Ray peuvent se lancer rapidement à l'aide de visualisations prédéfinies et à effectuer des tâches de base. Vous pouvez effectuer les opérations suivantes directement depuis la console :
+ Activez X-Ray.
+ Consultez des résumés de haut niveau des performances de votre application.
+ Vérifiez l'état de santé de vos applications.
+ Identifiez les erreurs de haut niveau.
+ Consultez les résumés des traces de base.
Vous pouvez utiliser la CloudWatch console Amazon [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)ou la console X-Ray de votre [https://console.aws.amazon.com/xray/domicile](https://console.aws.amazon.com/xray/home) pour interagir avec X-Ray.
## Utiliser la CloudWatch console Amazon
La CloudWatch console inclut une nouvelle fonctionnalité X-Ray qui a été repensée par rapport à la console X-Ray pour en faciliter l'utilisation. Si vous utilisez la CloudWatch console, vous pouvez consulter les CloudWatch journaux et les métriques ainsi que les données de suivi de X-Ray. Utilisez la CloudWatch console pour afficher et analyser les données, notamment les suivantes :
+ X-Ray Traces : visualisez, analysez et filtrez les traces associées à votre application lorsqu'elle répond à une demande. Utilisez ces traces pour détecter les latences élevées, les erreurs de débogage et optimiser le flux de travail de votre application. Consultez une carte de trace et une carte des services pour obtenir des représentations visuelles du flux de travail de votre application.
+ Journaux : affichez, analysez et filtrez les journaux produits par votre application. Utilisez les journaux pour résoudre les erreurs et configurez la surveillance en fonction de valeurs de journal spécifiques.
+ Métriques : mesurez et surveillez les performances de vos applications à l'aide de métriques émises par vos ressources ou créez vos propres métriques. Affichez ces indicateurs sous forme de graphiques et de tableaux.
+ Surveillance des réseaux et de l'infrastructure : surveillez les principaux réseaux pour détecter les pannes, ainsi que l'état et les performances de votre infrastructure, y compris les applications conteneurisées, les autres AWS services et les clients.
+ Toutes les fonctionnalités de la console X-Ray sont répertoriées dans la section **Utiliser la console X-Ray** suivante.
Pour plus d'informations sur la CloudWatch console, consultez [Getting started with Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingStarted.html).
Connectez-vous à la CloudWatch console Amazon à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
## Utiliser la console X-Ray
La console X-Ray propose un suivi distribué pour les demandes d'applications. Utilisez la console X-Ray si vous souhaitez une expérience de console plus simple ou si vous ne souhaitez pas mettre à jour le code de votre application. AWS ne développe plus la console X-Ray. La console X-Ray contient les fonctionnalités suivantes pour les applications instrumentées :
+ [Informations](xray-console-insights.md) : détectez automatiquement les anomalies dans les performances de votre application et identifiez les causes sous-jacentes. Les informations sont incluses dans la CloudWatch console sous **Insights**. Pour plus d'informations, consultez la section **Utiliser X-Ray Insights** dans[Utiliser la console X-Ray](#xray-console).
+ Carte des services : affichez une structure graphique de votre application et de ses connexions avec les clients, les ressources, les services et les dépendances.
+ Traces — Consultez un aperçu des traces générées par votre application lorsqu'elle répond à une demande. Utilisez les données de suivi pour comprendre les performances de votre application par rapport aux indicateurs de base, notamment le temps de HTTP réponse et le temps de réponse.
+ Analyses — Interprétez, explorez et analysez les données de suivi à l'aide de graphiques pour la distribution des temps de réponse.
+ Configuration — Créez des traces personnalisées pour modifier les configurations par défaut pour les éléments suivants :
+ Échantillonnage : créez une règle qui définit la fréquence à laquelle vous devez échantillonner votre application pour obtenir des informations de suivi. Pour plus d'informations, voir **Configurer les règles d'échantillonnage** dans[Utiliser la console X-Ray](#xray-console).
+ [Chiffrement](xray-console-encryption.md) — Chiffrez les données au repos à l'aide d'une clé que vous pouvez auditer ou désactiver à l'aide AWS Key Management Service d'une clé.
+ Groupes : utilisez une expression de filtre pour définir un groupe de traces présentant une caractéristique commune telle que le nom d'une URL ou un temps de réponse. Pour plus d'informations, consultez la section [Configuration des groupes](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups).
Connectez-vous à la console X-Ray à la [https://console.aws.amazon.com/xray/maison](https://console.aws.amazon.com/xray/home).
## Découvrez la console X-Ray
Utilisez la console X-Ray pour afficher une carte des services et des traces associées aux demandes traitées par vos applications, et pour configurer les groupes et les règles d'échantillonnage qui affectent la manière dont les traces sont envoyées à X-Ray.
**Note**
La carte et CloudWatch ServiceLens la carte X-Ray Service ont été combinées dans la carte de trace X-Ray dans la CloudWatch console Amazon. Ouvrez la [CloudWatchconsole](https://console.aws.amazon.com/cloudwatch/) et choisissez **Trace Map** sous **X-Ray Traces** dans le volet de navigation de gauche.
CloudWatch inclut désormais [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html), qui permet de découvrir et de surveiller les services de votre application, vos clients, les canaries Synthetics et les dépendances des services. Utilisez Application Signals pour consulter une liste ou une carte visuelle de vos services, consulter les indicateurs de santé en fonction de vos objectifs de niveau de service (SLOs) et effectuer une analyse descendante pour voir les traces de X-Ray corrélées afin de résoudre les problèmes de manière plus détaillée.
La page principale de la console X-Ray est la carte de trace, qui est une représentation visuelle du graphe de service JSON généré par X-Ray à partir des données de suivi générées par vos applications. La cartographie se compose de nœuds de service pour chaque application de votre compte qui sert des demandes, de nœuds clients en amont qui représentent les origines des demandes et de nœuds de service en aval qui représentent les services web et les ressources utilisées par une application lors du traitement d'une demande. Des pages supplémentaires permettent d'afficher les traces et les détails des traces, ainsi que de configurer les groupes et les règles d'échantillonnage.
Consultez l'expérience de X-Ray sur console et comparez-la avec la CloudWatch console dans les sections suivantes.
**Topics**
+ [Utiliser la CloudWatch console Amazon](#aws-xray-interface-console-cw)
+ [Utiliser la console X-Ray](#xray-console)
+ [Découvrez la console X-Ray](#xray-console-explore)
+ [Utilisation de la carte de traçage X-Ray](xray-console-servicemap.md)
+ [Afficher les traces et les détails des traces](xray-console-traces.md)
+ [Utilisation d'expressions de filtre](xray-console-filters.md)
+ [Traçabilité entre comptes](xray-console-crossaccount.md)
+ [Suivi des applications pilotées par des événements](xray-tracelinking.md)
+ [Utilisation d'histogrammes de latence](xray-console-histograms.md)
+ [Utilisation des informations issues de X-Ray](xray-console-insights.md)
+ [Interaction avec la console Analytics](xray-console-analytics.md)
+ [Configuration des groupes](xray-console-groups.md)
+ [Configuration de règles d'échantillonnage](xray-console-sampling.md)
+ [Configuration de l'échantillonnage adaptatif](xray-adaptive-sampling.md)
+ [Liens profonds sur console](xray-console-deeplinks.md)
# Utilisation de la carte de traçage X-Ray
Consultez la carte de suivi X-Ray pour identifier les services présentant des erreurs, les connexions présentant une latence élevée ou les traces de demandes infructueuses.
**Note**
CloudWatch inclut désormais [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html), qui permet de découvrir et de surveiller les services, les clients, les canaris synthétiques et les dépendances des services de votre application. Utilisez Application Signals pour consulter une liste ou une carte visuelle de vos services, consulter les indicateurs de santé en fonction de vos objectifs de niveau de service (SLOs) et effectuer une analyse descendante pour voir les traces de X-Ray corrélées afin de résoudre les problèmes de manière plus détaillée.
La carte et CloudWatch ServiceLens la carte du service X-Ray sont combinées dans la carte de suivi X-Ray dans la CloudWatch console Amazon. Ouvrez la [CloudWatch console](https://console.aws.amazon.com/cloudwatch/) et choisissez **Trace Map** sous **X-Ray Traces** dans le volet de navigation de gauche.
## Affichage de la carte de suivi
La carte de trace est une représentation visuelle des données de trace générées par vos applications. La carte montre les nœuds de service qui répondent aux demandes, les nœuds clients en amont qui représentent l'origine des demandes et les nœuds de service en aval qui représentent les services Web et les ressources utilisés par une application lors du traitement d'une demande.
La carte de trace affiche une vue connectée des traces dans les applications pilotées par des événements qui utilisent Amazon SQS et Lambda. Pour plus d'informations, consultez la section [Suivi des applications pilotées par des événements](xray-tracelinking.md). La carte de suivi prend également en [charge le suivi entre comptes](xray-console-crossaccount.md), en affichant les nœuds de plusieurs comptes sur une seule carte.
------
#### [ CloudWatch console ]
**Pour afficher la carte de suivi dans la CloudWatch console**
1. Ouvrez la [CloudWatch console](https://console.aws.amazon.com/cloudwatch/). Choisissez **Trace Map** dans la section **X-Ray Traces** dans le volet de navigation de gauche.
![\[CloudWatch page cartographique de trace de la console\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-servicemap-cw.png)
1. Choisissez un nœud de service pour consulter les demandes pour ce nœud, ou un arc entre deux nœuds pour afficher les suivis des demandes qui ont circulé sur cette connexion.
1. Des informations supplémentaires sont affichées sous la carte de suivi, notamment des onglets pour les métriques, les alertes et la distribution des temps de réponse. Dans l'onglet **Mesures**, sélectionnez une plage dans chaque graphique pour accéder à une vue plus détaillée, ou choisissez les options **Défauts** ou **Erreurs** pour filtrer les traces. Dans l'onglet **Distribution du temps de réponse**, sélectionnez une plage dans le graphique pour filtrer les traces en fonction du temps de réponse.
![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-cw-servicemap-node-detail.png)
1. Affichez les traces en choisissant **Afficher les traces**, ou si un filtre a été appliqué, choisissez **Afficher les traces filtrées**.
1. Choisissez **Afficher les journaux** pour voir CloudWatch les journaux associés au nœud sélectionné. Tous les nœuds de carte de trace ne prennent pas en charge l'affichage des journaux. Consultez les [ CloudWatch journaux de résolution des problèmes](xray-troubleshooting.md#xray-troubleshooting-Nologs) pour plus d'informations.
La carte de suivi indique les problèmes rencontrés au sein de chaque nœud en le décrivant en couleurs :
+ **Rouge** pour les erreurs serveur (erreurs de type 500)
+ **Jaune** pour les erreurs client (erreurs de type 400)
+ **Violet** pour les erreurs de limitation (erreur 429, nombre de requêtes trop élevé)
Si votre carte de traçage est grande, utilisez les commandes à l'écran ou la souris pour zoomer ou dézoomer et déplacer la carte.
------
#### [ X-Ray console ]
**Pour consulter la carte des services**
1. Ouvrez la [console X-Ray](https://console.aws.amazon.com/xray/home#). La carte des services est affichée par défaut. Vous pouvez également sélectionner **Service Map** dans le volet de navigation de gauche.
![\[Page de plan de service de la console X-Ray\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-servicemap-xray.png)
1. Choisissez un nœud de service pour consulter les demandes pour ce nœud, ou un arc entre deux nœuds pour afficher les suivis des demandes qui ont circulé sur cette connexion.
1. Utilisez l'[histogramme](xray-console-histograms.md) de distribution des réponses pour filtrer les traces par durée et sélectionnez les codes d'état pour lesquels vous souhaitez afficher les traces. Ensuite, choisissez **View traces (Afficher les suivis)** pour ouvrir la liste de suivi avec l'expression de filtre appliquée.
![\[Response distribution graph showing latency peaks and service details for Scorekeep AWS ECS container.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-servicemap-nodedetail-xray.png)
La cartographie des services indique l'état de chaque nœud en lui appliquant une couleur déterminée par le rapport entre le nombre d'appels réussis et le nombre d'erreurs ou d'échecs:
+ **Vert** pour les appels réussis
+ **Rouge** pour les erreurs serveur (erreurs de type 500)
+ **Jaune** pour les erreurs client (erreurs de type 400)
+ **Violet** pour les erreurs de limitation (erreur 429, nombre de requêtes trop élevé)
Si votre carte de service est grande, utilisez les commandes à l'écran ou la souris pour zoomer ou dézoomer et déplacer la carte.
------
**Note**
La carte de trace X-Ray peut afficher jusqu'à 10 000 nœuds. Dans de rares cas où le nombre total de nœuds de service dépasse cette limite, il est possible que vous receviez une erreur et que vous ne puissiez pas afficher une carte de suivi complète dans la console.
## Filtrer la carte de trace par groupe
À l'aide d'une [expression de filtre](xray-console-filters.md), vous pouvez définir des critères selon lesquels inclure des traces au sein d'un groupe. Suivez les étapes ci-dessous pour afficher ensuite ce groupe spécifique sur la carte de trace.
------
#### [ CloudWatch console ]
Choisissez un nom de groupe dans le filtre de groupe en haut à gauche de la carte de trace.
![\[Search bar for filtering by X-Ray group, with "TestGroup" displayed as an option.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-servicemap-groups-cw.png)
------
#### [ X-Ray console ]
Choisissez un nom de groupe dans le menu déroulant à gauche de la barre de recherche.
![\[Drop-down menu showing Default, TestGroup, Create group, and Learn more options.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-select-console.png)
------
La carte des services sera désormais filtrée pour afficher les traces correspondant à l'expression du filtre du groupe sélectionné.
## Tracez la légende et les options de la carte
La carte de trace inclut une légende et plusieurs options permettant de personnaliser l'affichage de la carte.
------
#### [ CloudWatch console ]
Choisissez le menu déroulant **Légende et options** en haut à droite de la carte. Choisissez ce qui est affiché dans les nœuds, notamment :
+ **Metrics** affiche le temps de réponse moyen et le nombre de traces envoyées par minute pendant la période choisie.
+ **Nodes** affiche l'icône de service dans chaque nœud.
Choisissez des paramètres de carte supplémentaires dans le volet **Préférences**, accessible via l'icône en forme de roue dentée en haut à droite de la carte. Ces paramètres incluent la sélection de la métrique utilisée pour déterminer la taille de chaque nœud et des canaris à afficher sur la carte.
------
#### [ X-Ray console ]
Affichez la légende de la carte de service en cliquant sur le lien **Légende de la carte** en haut à droite de la carte. Les options de carte de service peuvent être choisies en bas à droite de la carte de suivi, notamment :
+ Les **icônes de service** activent ce qui est affiché dans chaque nœud, en affichant soit l'icône du service, soit le temps de réponse moyen et le nombre de traces envoyées par minute pendant la période choisie.
+ **Dimensionnement des nœuds : aucun ne** définit la même taille pour tous les nœuds.
+ **Dimensionnement des nœuds : Health** classe les nœuds en fonction du nombre de demandes concernées, y compris les erreurs, les défauts ou les demandes limitées.
+ **Dimensionnement des nœuds : le trafic** taille les nœuds en fonction du nombre total de demandes.
------
# Afficher les traces et les détails des traces
Utilisez la page **Traces** de la console X-Ray pour rechercher des traces par URL, code de réponse ou autres données dans le résumé des traces. Après avoir sélectionné une trace dans la liste des traces, la page **Détails de la trace** affiche une carte des nœuds de service associés à la trace sélectionnée et une chronologie des segments de trace.
## Affichage des suivis
------
#### [ CloudWatch console ]
**Pour afficher les traces dans la CloudWatch console**
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Dans le volet de navigation de gauche, choisissez **X-Ray Traces**, puis **Traces**. Vous pouvez filtrer par groupe ou saisir une [expression de filtre](xray-console-filters.md). Cela filtre les traces affichées dans la section **Traces** au bas de la page.
Vous pouvez également utiliser la carte des services pour accéder à un nœud de service spécifique, puis afficher les traces. Cela ouvre la page **Traces** avec une requête déjà appliquée.
1. Affinez votre requête dans la section **Affinateurs de requêtes**. Pour filtrer les traces en fonction d'un attribut commun, choisissez une option dans la flèche vers le bas située à côté de **Affiner la requête par**. Les options disponibles sont les suivantes :
+ Nœud : filtrez les traces par nœud de service.
+ ARN de la ressource — Filtrez les traces en fonction d'une ressource associée à une trace. Ces ressources incluent par exemple une instance Amazon Elastic Compute Cloud (Amazon EC2), une AWS Lambda fonction ou une Amazon DynamoDB table.
+ Utilisateur : filtrez les traces à l'aide d'un ID utilisateur.
+ Message de cause première de l'erreur : filtrez les traces par cause première de l'erreur.
+ URL : filtrez les traces en fonction du chemin d'URL utilisé par votre application.
+ Code d'état HTTP : filtrez les traces en fonction du code d'état HTTP renvoyé par votre application. Vous pouvez spécifier un code de réponse personnalisé ou sélectionner l'une des options suivantes :
+ `200`— La demande a été acceptée.
+ `401`— La demande ne comportait pas d'informations d'authentification valides.
+ `403`— La demande ne comportait pas d'autorisations valides.
+ `404`— Le serveur n'a pas pu trouver la ressource demandée.
+ `500`— Le serveur a rencontré une situation inattendue et a généré une erreur interne.
Choisissez une ou plusieurs entrées, puis cliquez sur **Ajouter à la requête** pour les ajouter à l'expression de filtre en haut de la page.
1. Pour rechercher une trace unique, entrez un [ID de trace](xray-api-sendingdata.md#xray-api-traceids) directement dans le champ de requête. Vous pouvez utiliser le format X-Ray ou le format World Wide Web Consortium (W3C). Par exemple, une trace créée à l'aide de [AWS Distro pour OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) est au format W3C.
**Note**
Lorsque vous interrogez des traces créées avec un ID de trace au format W3C, la console affiche la trace correspondante au format X-Ray. Par exemple, si vous recherchez `4efaaf4d1e8720b39541901950019ee5` au format W3C, la console affiche l'équivalent de X-Ray :`1-4efaaf4d-1e8720b39541901950019ee5`.
1. Choisissez **Exécuter la requête** à tout moment pour afficher une liste des traces correspondantes dans la section **Traces** au bas de la page.
1. Pour afficher la page des **détails du suivi** pour un seul suivi, sélectionnez un ID de suivi dans la liste.
L'image suivante montre une **carte de trace** contenant les nœuds de service associés au tracé et les arêtes entre les nœuds représentant le chemin emprunté par les segments qui composent le tracé. Un **résumé de trace** suit la **carte de trace**. Le résumé contient des informations sur un exemple d'`GET`opération, son **code de réponse**, la **durée** d'exécution du suivi et l'**âge** de la demande. La **chronologie des segments** suit le **résumé du suivi** qui indique la durée des segments et sous-segments de suivi.
![\[Une carte de trace, un résumé et une chronologie des segments fournissent des informations détaillées sur les nœuds de service et les segments du suivi.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/xray-trace-details-cw.png)
**Si vous avez une application pilotée par des événements qui utilise Amazon SQS et Lambda, vous pouvez voir une vue connectée des traces pour chaque requête dans la carte Trace.** Sur la carte, les traces des producteurs de messages sont liées aux traces des AWS Lambda consommateurs et sont affichées sous forme de bord pointillé. Pour plus d'informations sur les applications pilotées par des événements, consultez. [Suivi des applications pilotées par des événements](xray-tracelinking.md)
Les pages de **détails **des traces**** et des traces prennent également en [charge le suivi entre comptes](xray-console-crossaccount.md), qui permet de répertorier les traces de plusieurs comptes dans la liste de traces et dans une seule carte de trace.
------
#### [ X-Ray console ]
**Pour afficher les traces dans la console X-Ray**
1. Ouvrez la page [Traces](https://console.aws.amazon.com/xray/home#/traces) dans la console X-Ray. Le panneau de **présentation des traces** affiche une liste de traces regroupées par fonctionnalités communes, notamment les **causes profondes des erreurs**, **ResourceArn** et. **InstanceId**
1. Pour sélectionner une fonction commune afin d'afficher un ensemble groupé de traces, déployez la flèche vers le bas à côté de **Grouper par**. L'illustration suivante présente une vue d'ensemble des traces regroupées par URL pour le[AWS X-Ray exemple d'application](xray-scorekeep.md), ainsi qu'une liste des traces associées.
![\[Exemple d'aperçu du suivi groupé par URL, suivi d'une liste de suivi avec des détails tels que l'ID, la méthode et la réponse.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-traces.png)
1. Choisissez l'**ID** d'une trace pour l'afficher dans la **liste des traces**. Vous pouvez également sélectionner **Service map** dans le volet de navigation pour afficher les traces d'un nœud de service spécifique. Vous pouvez ensuite afficher les traces associées à ce nœud.
L'onglet **Chronologie** indique le flux de demandes pour le suivi et inclut les éléments suivants :
+ Une carte du chemin pour chaque segment de la trace.
+ Le temps qu'il a fallu au segment pour atteindre un nœud de la carte de trace.
+ Combien de demandes ont été adressées au nœud dans la carte de trace.
L'illustration suivante montre un exemple de **carte de suivi** associée à une `GET` demande envoyée à un exemple d'application. Les flèches indiquent le chemin emprunté par chaque segment pour terminer la demande. Les nœuds de service indiquent le nombre de demandes effectuées pendant la `GET` demande.
![\[Tracez une carte suivie d'une chronologie avec les segments, leur durée, leur origine et leur fin les uns par rapport aux autres.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/xray-trace-details.png)
Pour plus d'informations sur l'onglet **Chronologie**, consultez la section **Exploration de la chronologie de suivi** suivante.
L'onglet **Données brutes** affiche des informations sur le tracé, ainsi que sur les segments et sous-segments qui le composent, sous `JSON` forme de format. Ces informations peuvent inclure les éléments suivants :
+ Horodatages
+ Unique IDs
+ Ressources associées au segment ou au sous-segment
+ La source, ou origine, du segment ou du sous-segment
+ Informations supplémentaires sur la demande adressée à votre application, telles que la réponse d'une requête HTTP
------
## Exploration de la chronologie des traces
La section **Chronologie** présente une hiérarchie de segments et de sous-segments à côté d'une barre horizontale qui correspond au temps qu'ils ont utilisé pour accomplir leurs tâches. La première entrée de la liste est le segment, qui représente toutes les données enregistrées par le service pour une seule demande. Les sous-segments sont mis en retrait et répertoriés après le segment. Les colonnes contiennent des informations sur chaque segment.
------
#### [ CloudWatch console ]
Dans la CloudWatch console, la **chronologie des segments** fournit les informations suivantes :
+ La première colonne : répertorie les segments et sous-segments de la trace sélectionnée.
+ La colonne **État du segment** : répertorie le résultat du statut de chaque segment et sous-segment.
+ La colonne **Code de réponse** : répertorie un code d'état de réponse HTTP à une demande de navigateur effectuée par le segment ou le sous-segment, lorsqu'il est disponible.
+ La colonne **Durée** : indique la durée du segment ou du sous-segment.
+ La colonne **Hosted in** : répertorie l'espace de noms ou l'environnement dans lequel le segment ou le sous-segment est exécuté, le cas échéant. Pour plus d'informations, voir [Dimensions collectées et combinaisons de dimensions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions).
+ La dernière colonne : affiche des barres horizontales qui correspondent à la durée pendant laquelle le segment ou le sous-segment s'est déroulé, par rapport aux autres segments ou sous-segments de la chronologie.
Pour regrouper la liste des segments et sous-segments par nœud de service, activez l'option **Regrouper par nœuds**.
------
#### [ X-Ray console ]
Sur la page des détails de la trace, choisissez l'onglet **Chronologie** pour voir la chronologie de chaque segment et sous-segment constituant une trace.
Dans la console X-Ray, la **chronologie** fournit les informations suivantes :
+ La colonne **Nom** : répertorie les noms des segments et sous-segments de la trace.
+ La colonne **Res.** : répertorie un code d'état de réponse HTTP à une demande de navigateur effectuée par le segment ou le sous-segment, lorsqu'il est disponible.
+ La colonne **Durée** : indique la durée du segment ou du sous-segment.
+ La colonne **État** : répertorie le résultat de l'état du segment ou du sous-segment.
+ La dernière colonne : affiche des barres horizontales qui correspondent à la durée pendant laquelle le segment ou le sous-segment s'est déroulé, par rapport aux autres segments ou sous-segments de la chronologie.
Pour voir les données de trace brutes que la console utilise pour générer la chronologie, choisissez l'onglet **Données brutes**. Les données brutes vous fournissent des informations sur le tracé, ainsi que sur les segments et sous-segments qui le composent au `JSON` format. Ces informations peuvent inclure les éléments suivants :
+ Horodatages
+ Unique IDs
+ Ressources associées au segment ou au sous-segment
+ La source, ou origine, du segment ou du sous-segment
+ Informations supplémentaires sur la demande adressée à votre application, telles que la réponse d'une requête HTTP.
------
Lorsque vous utilisez un AWS SDK instrumenté, HTTP, ou SQL client pour appeler des ressources externes, le SDK X-Ray enregistre automatiquement les sous-segments. Vous pouvez également utiliser le SDK X-Ray pour enregistrer des sous-segments personnalisés pour n'importe quelle fonction ou bloc de code. Les sous-segments supplémentaires enregistrés alors qu'un sous-segment personnalisé est ouvert deviennent les enfants du sous-segment personnalisé.
## Affichage des détails d'un segment
Dans la **chronologie** du tracé, choisissez le nom d'un segment pour en afficher les détails.
Le panneau **Détails du segment** affiche les onglets **Vue d'ensemble**, **Ressources**, **Annotations**, **Métadonnées**, **Exceptions** et **SQL**. Les conditions suivantes s'appliquent :
+ L’onglet **Overview (Présentation)** présente les informations relatives à la demande et à la réponse. Les informations incluent le nom, l'heure de début, l'heure de fin, la durée, l'URL de la demande, le fonctionnement de la demande, le code de réponse à la demande et les erreurs et défauts éventuels.
+ L'onglet **Ressources** d'un segment affiche des informations provenant du SDK X-Ray et des AWS ressources qui exécutent votre application. Utilisez les plug-ins Amazon EC2 ou Amazon ECS pour le SDK X-Ray afin d'enregistrer des informations sur les ressources spécifiques au service. AWS Elastic Beanstalk Pour plus d'informations sur les plug-ins, consultez la section **Plug-ins de service** dans[Configuration du SDK X-Ray pour Java](xray-sdk-java-configuration.md).
+ Les autres onglets affichent **les annotations**, **les métadonnées** et les **exceptions** enregistrées pour le segment. Les exceptions sont capturées automatiquement lorsqu'elles sont générées à partir d'une demande instrumentée. Les annotations et les métadonnées contiennent des informations supplémentaires que vous enregistrez à l'aide des opérations fournies par le SDK X-Ray. Pour ajouter des annotations ou des métadonnées à vos segments, utilisez le SDK X-Ray. Pour plus d'informations, consultez le lien spécifique à la langue répertorié sous Instrumentation de votre application avec. AWS X-Ray SDKs [Instrumentation de votre application pour AWS X-Ray](xray-instrumenting-your-app.md)
## Affichage des détails d'un sous-segment
Dans la chronologie du suivi, choisissez le nom d'un sous-segment pour en afficher les détails :
+ L'onglet **Vue d'ensemble** contient des informations sur la demande et la réponse. Cela inclut le nom, l'heure de début, l'heure de fin, la durée, la demande URL, le fonctionnement de la demande, le code de réponse à la demande et toutes les erreurs et défauts. Pour les sous-segments générés avec des clients instrumentés, l’onglet **Overview (Présentation)** contient des informations sur la demande et la réponse du point de vue de votre application.
+ L'onglet **Ressources** d'un sous-segment affiche des informations détaillées sur les AWS ressources utilisées pour exécuter le sous-segment. Par exemple, l'onglet Ressources peut inclure un ARN de AWS Lambda fonction, des informations sur une table DynamoDB, toute opération appelée et un ID de demande.
+ Les autres onglets affichent les **annotations, les** **métadonnées** et les **exceptions** enregistrées sur le sous-segment. Les exceptions sont capturées automatiquement lorsqu'elles sont générées à partir d'une demande instrumentée. Les annotations et les métadonnées contiennent des informations supplémentaires que vous enregistrez à l'aide des opérations fournies par le SDK X-Ray. Utilisez le SDK X-Ray pour ajouter des annotations ou des métadonnées à vos segments. Pour plus d'informations, consultez le lien spécifique à la langue répertorié sous **Instrumentation de votre application** avec. AWS X-Ray SDKs [Instrumentation de votre application pour AWS X-Ray](xray-instrumenting-your-app.md)
Pour les sous-segments personnalisés, l’onglet **Overview (Présentation)** affiche le nom du sous-segment, que vous pouvez définir pour spécifier la zone de code ou la fonction que celui-ci enregistre. Pour plus d'informations, consultez le lien spécifique à la langue répertorié sous **Instrumentation de votre application** avec. AWS X-Ray SDKs [Génération de sous-segments personnalisés avec le SDK X-Ray pour Java](xray-sdk-java-subsegments.md)
L'image suivante montre l'onglet **Vue d'ensemble d'**un sous-segment personnalisé. La vue d'ensemble contient l'ID du sous-segment, l'ID parent, le nom, les heures de début et de fin, la durée, le statut et les erreurs ou défauts.
![\[Informations générales sur un sous-segment, notamment l'ID, l'ID parent, le nom, les heures, les erreurs et les défauts.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-PUTrules-customsubsegment-overview.png)
L'onglet **Métadonnées** d'un sous-segment personnalisé contient des informations dans JSON format concernant les ressources utilisées par ce sous-segment.
# Utilisation d'expressions de filtre
Utilisez des *expressions de filtre* pour afficher une carte de trace ou les traces d'une demande, d'un service, d'une connexion entre deux services (une périphérie) ou de demandes répondant à une condition spécifique. X-Ray fournit un langage d'expression de filtre pour filtrer les demandes, les services et les limites en fonction des données contenues dans les en-têtes des demandes, de l'état des réponses et des champs indexés sur les segments d'origine.
Lorsque vous choisissez une période de traces à afficher dans la console X-Ray, vous pouvez obtenir plus de résultats que ce que la console peut afficher. Dans le coin supérieur droit, la console affiche le nombre de suivis qu'elle a analysés et s'il y a d'autres suivis disponibles. Vous pouvez utiliser une expression de filtre pour limiter les résultats aux seules traces que vous souhaitez rechercher.
**Topics**
+ [Filtrer les détails de l'expression](#xray-console-filters-details)
+ [Utilisation d'expressions de filtrage avec les groupes](#groups)
+ [Syntaxe d'une expression de filtrage](#console-filters-syntax)
+ [Mots-clés booléens](#console-filters-boolean)
+ [Mots-clés valeur](#console-filters-number)
+ [Mots-clés chaîne](#console-filters-string)
+ [Mots-clés complexes](#console-filters-complex)
+ [fonction id](#console-filters-functions)
## Filtrer les détails de l'expression
Lorsque vous [choisissez un nœud dans la carte de trace](xray-console-servicemap.md), la console crée une expression de filtre en fonction du nom de service du nœud et des types d'erreurs présents en fonction de votre sélection. Pour trouver les suivis montrant les problèmes de performances ou concernant des demandes spécifiques, vous pouvez ajuster l'expression fournie par la console ou créer vos propres expressions. Si vous ajoutez des annotations avec le SDK X-Ray, vous pouvez également filtrer en fonction de la présence d'une clé d'annotation ou de la valeur d'une clé.
**Note**
Si vous choisissez une plage de temps relative dans la carte de trace et que vous choisissez un nœud, la console convertit la plage de temps en heure de début et de fin absolues. Pour assurer que les suivis du nœud apparaissent dans les résultats de recherche et éviter d'analyser les heures auxquelles le nœud n'était pas actif, la plage de temps inclut uniquement les heures pendant lesquelles le nœud a envoyé des suivis. Pour effectuer une recherche par rapport à l'heure actuelle, vous pouvez revenir à une plage de temps relative dans la page des suivis et relancer l'analyse.
S'il y a toujours plus de résultats disponibles que la console ne peut en afficher, la console affiche le nombre de suivis correspondants et le nombre de suivis analysés. Le pourcentage affiché est le pourcentage de la période sélectionnée qui a été analysée. Pour vous assurer d’afficher tous les suivis correspondants représentés dans les résultats, réduisez encore votre expression de filtrage ou choisissez une période plus courte.
Pour obtenir les résultats les plus récents en premier, la console démarre l'analyse à la fin de la plage de temps et fonctionne en marche arrière. S'il y a un grand nombre de suivis, mais peu de résultats, la console fractionne la plage de temps en blocs qu'elle analyse en parallèle. La barre de progression indique les parties de la plage de temps qui ont été analysées.
![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-tracescan-parallel.png)
## Utilisation d'expressions de filtrage avec les groupes
Les groupes sont un ensemble de traces définies par une expression de filtre. Vous pouvez utiliser des groupes pour générer des graphiques de service supplémentaires et fournir CloudWatch des statistiques Amazon.
Les groupes sont identifiés par leur nom ou un Amazon Resource Name (ARN), et contiennent une expression de filtre. Le service compare les suivis entrants à l'expression, et les stocke en conséquence.
Vous pouvez créer et modifier des groupes en utilisant le menu déroulant à gauche de la barre de recherche d'expression de filtre.
**Note**
Si le service rencontre une erreur en qualifiant un groupe, ce groupe n'est plus inclus dans le traitement des suivis entrants et une métrique d'erreur est enregistrée.
Pour plus d'informations sur les groupes, consultez[Configuration des groupes](xray-console-groups.md).
## Syntaxe d'une expression de filtrage
Les expressions de filtrage peuvent contenir un *mot-clé*, un *opérateur unaire ou binaire* et une *valeur* de comparaison.
```
keyword operator value
```
Différents opérateurs sont disponibles pour les différents types de mot-clé. Par exemple, `responsetime` est un mot-clé valeur et peut être comparé aux opérateurs liés à des chiffres.
**Example — demandes dont le temps de réponse était supérieur à 5 secondes**
```
responsetime > 5
```
Vous pouvez combiner plusieurs expressions dans une expression composée avec les opérateurs `AND` ou `OR`.
**Example — demandes dont la durée totale était de 5 à 8 secondes**
```
duration >= 5 AND duration <= 8
```
Les mots-clés et opérateurs simples permettent uniquement de rechercher des problèmes au niveau des données de suivi. Si une erreur survient en aval, mais est gérée par votre application et n'est pas renvoyée à l'utilisateur, la recherche lancée sur `error` ne la trouvera pas.
Pour trouver les données de suivi concernant des problèmes en aval, vous pouvez utiliser les [mots-clés complexes](#console-filters-complex) `service()` et `edge()`. Ces mots-clés vous permettent d'appliquer une expression de filtre à tous les nœuds en aval, à un seul nœud en aval ou à un arc entre deux nœuds. Pour encore plus de granularité, vous pouvez filtrer les services et les arcs par type avec [la fonction id()](#console-filters-functions).
## Mots-clés booléens
Les valeurs des mots-clés booléens sont true ou false. Utilisez ces mots-clés pour trouver des données de suivi ayant généré des erreurs.
**Mots-clés booléens**
+ `ok`— Le code d'état de la réponse était 2XX Success.
+ `error`— Le code d'état de la réponse était 4XX Client Error.
+ `throttle`— Le code d'état de la réponse était 429 trop de demandes.
+ `fault`— Le code d'état de la réponse était une erreur de serveur 5XX.
+ `partial`— La demande contient des segments incomplets.
+ `inferred`— La demande contient des segments déduits.
+ `first`— L'élément est le premier d'une liste énumérée.
+ `last`— L'élément est le dernier d'une liste énumérée.
+ `remote`— L'entité responsable est distante.
+ `root`— Le service est le point d'entrée ou le segment racine d'une trace.
Les opérateurs booléens trouvent les segments dans lesquels la clé spécifiée est `true` ou `false`.
**Opérateurs booléens**
+ none — L'expression est vraie si le mot clé est vrai.
+ `!`— L'expression est vraie si le mot clé est faux.
+ `=`, `!=` — Comparez la valeur du mot-clé à la chaîne `true` ou`false`. Ces opérateurs agissent de la même manière que les autres opérateurs mais sont plus explicites.
**Example — le statut de la réponse est 2XX OK**
```
ok
```
**Example — le statut de la réponse n'est pas 2XX OK**
```
!ok
```
**Example — le statut de la réponse n'est pas 2XX OK**
```
ok = false
```
**Example — la dernière trace de panne énumérée porte le nom d'erreur « désérialiser »**
```
rootcause.fault.entity { last and name = "deserialize" }
```
**Example — demandes avec des segments distants dont la couverture est supérieure à 0,7 et dont le nom du service est « traces »**
```
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
```
**Example — requêtes contenant des segments inférés dont le type de service est « AWS:DynamoDB »**
```
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
```
**Example — requêtes dont un segment porte le nom « plan de données » comme racine**
```
service("data-plane") {root = true and fault = true}
```
## Mots-clés valeur
Utilisez les mots-clés valeur pour rechercher des demandes avec un temps de réponse, une durée ou un statut de réponse spécifique.
**Mots-clés valeur**
+ `responsetime`— Temps nécessaire au serveur pour envoyer une réponse.
+ `duration`— Durée totale de la demande, y compris tous les appels en aval.
+ `http.status`— Code d'état de la réponse.
+ `index`— Position d'un élément dans une liste énumérée.
+ `coverage`— Pourcentage décimal du temps de réponse de l'entité par rapport au temps de réponse du segment racine. Applicable uniquement aux entités de cause racine des temps de réponse.
**Opérateurs numériques**
Les mots-clés valeur utilisent l'égalité standard et les opérateurs de comparaison.
+ `=`, `!=` — Le mot clé est égal ou non à une valeur numérique.
+ `<`,`<=`,`>`, `>=` — Le mot clé est inférieur ou supérieur à une valeur numérique.
**Example — le statut de la réponse n'est pas 200 OK**
```
http.status != 200
```
**Example — demande dont la durée totale était de 5 à 8 secondes**
```
duration >= 5 AND duration <= 8
```
**Example — demandes traitées avec succès en moins de 3 secondes, y compris tous les appels en aval**
```
ok !partial duration <3
```
**Example — entité de liste énumérée dont l'indice est supérieur à 5**
```
rootcause.fault.service { index > 5 }
```
**Example — demandes pour lesquelles la dernière entité dont la couverture est supérieure à 0,8**
```
rootcause.responsetime.entity { last and coverage > 0.8 }
```
## Mots-clés chaîne
Utilisez des mots-clés de chaîne pour rechercher des traces contenant du texte spécifique dans les en-têtes de demande ou un utilisateur IDs spécifique.
**Mots-clés chaîne**
+ `http.url`— URL de demande.
+ `http.method`— Méthode de demande.
+ `http.useragent`— Demande une chaîne d'agent utilisateur.
+ `http.clientip`— Adresse IP du demandeur.
+ `user`— Valeur du champ utilisateur sur n'importe quel segment de la trace.
+ `name`— Le nom d'un service ou d'une exception.
+ `type`— Type de service
+ `message`— Message d'exception.
+ `availabilityzone`— Valeur du champ de zone de disponibilité sur n'importe quel segment de la trace.
+ `instance.id`— Valeur du champ ID d'instance sur n'importe quel segment de la trace.
+ `resource.arn`— Valeur du champ ARN de la ressource sur n'importe quel segment de la trace.
Les opérateurs chaîne trouvent des valeurs qui sont égales à un texte spécifique ou contiennent un texte spécifique. Ces valeurs doivent toujours être spécifiées entre guillemets.
**Opérateurs de chaîne**
+ `=`, `!=` — Le mot clé est égal ou non à une valeur numérique.
+ `CONTAINS`— Le mot clé contient une chaîne spécifique.
+ `BEGINSWITH`, `ENDSWITH` — Le mot clé commence ou se termine par une chaîne spécifique.
**Example — filtre http.url**
```
http.url CONTAINS "/api/game/"
```
Pour vérifier si un champ existe sur une donnée de suivi, quelle que soit sa valeur, vérifiez si elle contient la chaîne vide.
**Example — filtre utilisateur**
Trouvez toutes les traces avec l'utilisateur IDs.
```
user CONTAINS ""
```
**Example — sélectionnez les traces dont la cause première est une erreur et qui incluent un service appelé « Auth »**
```
rootcause.fault.service { name = "Auth" }
```
**Example — sélectionne les traces dont la cause première est le temps de réponse et dont le dernier service est de type DynamoDB**
```
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
```
**Example — sélectionne les traces dont la cause première est une erreur dont la dernière exception contient le message « accès refusé pour account\$1id : 1234567890 »**
```
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
```
## Mots-clés complexes
Utilisez les mots-clés complexes pour trouver des demandes en fonction du nom du service, du nom de l'arc ou d'une valeur d'annotation. Pour les services et les arcs, vous pouvez spécifier une expression de filtrage supplémentaire qui s'applique au service ou à l'arc. Pour les annotations, vous pouvez appliquer un filtre sur la valeur d'une annotation avec une clé spécifique en utilisant des opérateurs booléens, numériques ou de chaîne.
**Mots-clés complexes**
+ `annotation[key]`— Valeur d'une annotation avec champ*key*. La valeur d'une annotation peut être un opérateur booléen, une valeur numérique ou une chaîne. Vous pouvez donc utiliser n'importe lequel de ces types d'opérateurs de comparaison. Vous pouvez utiliser ce mot clé en combinaison avec le `edge` mot clé `service` or. Une clé d'annotation contenant des points (points) doit être placée entre crochets (**[]**).
+ `edge(source, destination) {filter}`— Connexion entre les services *source* et*destination*. Vous pouvez, si vous le souhaitez, utiliser des accolades pour englober une expression de filtrage à appliquer aux segments de cette connexion.
+ `group.name / group.arn`— La valeur de l'expression de filtre d'un groupe, référencée par le nom ou l'ARN du groupe.
+ `json`— Objet source JSON. Consultez [Getting data from AWS X-Ray](xray-api-gettingdata.md) pour connaître les étapes de création d'entités JSON par programmation.
+ `service(name) {filter}`— Service avec nom*name*. Vous pouvez, si vous le souhaitez, utiliser des accolades pour englober une expression de filtrage à appliquer aux segments créés par le service.
Utilisez le mot clé service pour trouver des traces pour les requêtes qui atteignent un certain nœud de votre carte de suivi.
Les opérateurs de mots clés complexes trouvent les segments dans lesquels la clé spécifiée a été définie ou non définie.
**Opérateurs de mots clés complexes**
+ none — L'expression est vraie si le mot clé est défini. Si le mot clé est de type booléen, il sera évalué à la valeur booléenne.
+ `!`— L'expression est vraie si le mot clé n'est pas défini. Si le mot clé est de type booléen, il sera évalué à la valeur booléenne.
+ `=`, `!=` — Comparez la valeur du mot clé.
+ `edge(source, destination) {filter}`— Connexion entre les services *source* et*destination*. Vous pouvez, si vous le souhaitez, utiliser des accolades pour englober une expression de filtrage à appliquer aux segments de cette connexion.
+ `annotation[key]`— Valeur d'une annotation avec champ*key*. La valeur d'une annotation peut être un opérateur booléen, une valeur numérique ou une chaîne. Vous pouvez donc utiliser n'importe lequel de ces types d'opérateurs de comparaison. Vous pouvez utiliser ce mot clé en combinaison avec le `edge` mot clé `service` or.
+ `json`— Objet source JSON. Consultez [Getting data from AWS X-Ray](xray-api-gettingdata.md) pour connaître les étapes de création d'entités JSON par programmation.
Utilisez le mot clé service pour trouver des traces pour les requêtes qui atteignent un certain nœud de votre carte de suivi.
**Example — Filtre de service**
Demandes comprenant un appel vers `api.example.com` avec une anomalie (erreur de la série 500).
```
service("api.example.com") { fault }
```
Vous pouvez exclure le nom du service pour appliquer une expression de filtre à tous les nœuds sur votre cartographie des services.
**Example — filtre de service**
Demandes à l'origine d'une erreur n'importe où sur votre carte de trace.
```
service() { fault }
```
Le mot-clé arc applique une expression de filtre à une connexion entre deux nœuds.
**Example — filtre de bord**
Demande pour laquelle l'appel du service `api.example.com` à `backend.example.com` a échoué suite à une erreur.
```
edge("api.example.com", "backend.example.com") { error }
```
Vous pouvez également utiliser l'opérateur `!` avec les mots-clés service et arc pour exclure un service ou un arc des résultats d'une autre expression de filtre.
**Example — filtre de service et de demande**
Demande pour laquelle l'URL commence par `http://api.example.com/` et inclut `/v2/` mais ne contacte pas un service nommé `api.example.com`.
```
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
```
**Example — filtre de service et de temps de réponse**
Trouvez des traces là où `http url` est défini et où le temps de réponse est supérieur à 2 secondes.
```
http.url AND responseTime > 2
```
Pour les annotations, vous pouvez appeler toutes les traces où `annotation[key]` est défini ou utiliser les opérateurs de comparaison correspondant au type de valeur.
**Example — annotation avec valeur de chaîne**
Demandes avec une annotation nommée `gameid` avec une valeur de chaîne `"817DL6VO"`.
```
annotation[gameid] = "817DL6VO"
```
**Example — l'annotation est définie**
Demandes avec une annotation nommée `age` set.
```
annotation[age]
```
**Example — l'annotation n'est pas définie**
Demandes sans annotation nommées `age` set.
```
!annotation[age]
```
**Example — annotation avec valeur numérique**
Demandes avec un âge d'annotation avec une valeur numérique supérieure à 29.
```
annotation[age] > 29
```
**Example — annotation en combinaison avec le service ou l'arête**
```
service { annotation[request.id] = "917DL6VO" }
```
```
edge { source.annotation[request.id] = "916DL6VO" }
```
```
edge { destination.annotation[request.id] = "918DL6VO" }
```
**Example — groupe avec utilisateur**
Demandes où les traces rencontrent le filtre de `high_response_time` groupe (par exemple`responseTime > 3`) et où l'utilisateur s'appelle Alice.
```
group.name = "high_response_time" AND user = "alice"
```
**Example — JSON avec entité de cause première**
Requêtes avec entités de cause racine correspondantes.
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
## fonction id
Lorsque vous fournissez un nom de service pour les mots-clés `service` ou `edge`, vous obtenez des résultats pour tous les nœuds correspondant à ce nom. Pour un filtrage plus précis, vous pouvez utiliser la fonction `id` pour spécifier un type de service en plus d'un nom et faire la distinction entre les nœuds portant le même nom.
Utilisez cette `account.id` fonction pour spécifier un compte particulier pour le service, lorsque vous consultez les traces de plusieurs comptes dans un compte de surveillance.
```
id(name: "service-name", type:"service::type", account.id:"account-ID")
```
Vous pouvez utiliser la fonction `id` à la place d'un nom de service dans les filtres de service et d'arc.
```
service(id(name: "service-name", type:"service::type")) { filter }
```
```
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }
```
Par exemple, AWS Lambda les fonctions génèrent deux nœuds dans la carte de trace : un pour l'invocation de la fonction et un pour le service Lambda. Les deux nœuds ont le même nom, mais des types différents. Un filtre de service standard trouvera des données de suivi pour les deux.
**Example — filtre de service**
Demandes qui incluent une erreur sur n'importe quel service nommé `random-name`.
```
service("random-name") { error }
```
Utilisez la fonction `id` pour limiter la recherche aux erreurs portant sur la fonction elle-même et exclure les erreurs du service.
**Example — filtre de service avec fonction id**
Demandes qui incluent une erreur sur un service nommé `random-name` de type `AWS::Lambda::Function`.
```
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
```
Pour rechercher des nœuds par type, vous pouvez également exclure complètement le nom.
**Example — filtre de service avec fonction d'identification et type de service**
Demandes qui incluent une erreur sur un service de type `AWS::Lambda::Function`.
```
service(id(type: "AWS::Lambda::Function")) { error }
```
Pour rechercher des nœuds pour un utilisateur en particulier Compte AWS, spécifiez un ID de compte.
**Example — filtre de service avec fonction d'identification et identifiant de compte**
Demandes qui incluent un service associé à un identifiant de compte spécifique`AWS::Lambda::Function`.
```
service(id(account.id: "account-id"))
```
# Traçabilité entre comptes
AWS X-Ray prend en *charge l'observabilité entre comptes*, vous permettant de surveiller et de dépanner les applications qui couvrent plusieurs comptes au sein d'un. Région AWS Vous pouvez facilement rechercher, visualiser et analyser vos indicateurs, journaux et traces dans tous les comptes associés, comme si vous travailliez sur un seul compte. Cela fournit une vue complète des demandes qui transitent par plusieurs comptes. Vous pouvez consulter les traces entre comptes sur la carte de suivi X-Ray et sur les pages de traces de la [CloudWatchconsole](https://console.aws.amazon.com/cloudwatch/).
Les données d'observabilité partagées peuvent inclure l'un des types de télémétrie suivants :
+ Métriques sur Amazon CloudWatch
+ Groupes de journaux dans Amazon CloudWatch Logs
+ Traces dans AWS X-Ray
+ Applications dans Amazon CloudWatch Application Insights
## Configurer l'observabilité entre comptes
Pour activer l'observabilité entre comptes, configurez un ou plusieurs comptes de AWS *surveillance* et associez-les à plusieurs comptes *sources*. Un compte de surveillance est une centrale Compte AWS qui permet de visualiser et d'interagir avec les données d'observabilité générées à partir des comptes sources. Un compte source est une personne Compte AWS qui génère des données d'observabilité pour les ressources qu'il contient.
Les comptes sources partagent leurs données d'observabilité avec les comptes de surveillance. Les traces sont copiées de chaque compte source vers un maximum de cinq comptes de surveillance. Les copies des traces des comptes sources vers le premier compte de surveillance sont gratuites. Les copies des traces envoyées à des comptes de surveillance supplémentaires sont facturées à chaque compte source, sur la base de la tarification standard. Pour plus d'informations, consultez les sections [AWS X-Ray Tarification](https://aws.amazon.com/xray/pricing/) et [ CloudWatch Tarification Amazon](https://aws.amazon.com/cloudwatch/pricing/).
Pour créer des liens entre les comptes de surveillance et les comptes sources, utilisez la CloudWatch console ou les nouvelles commandes Observability Access Manager de l'API AWS CLI and. Pour plus d'informations, consultez la section [Observabilité inter-comptes de CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html) (français non garanti).
**Note**
Les tracés X-Ray sont facturés à l' Compte AWS endroit où ils sont reçus. Si une demande [échantillonnée](xray-concepts.md#xray-concepts-sampling) couvre plusieurs services Compte AWS, chaque compte enregistre une trace distincte, et toutes les traces partagent le même identifiant de trace. Pour en savoir plus sur la tarification de l'observabilité entre comptes, consultez les sections Tarification et [AWS X-Ray Tarification](https://aws.amazon.com/xray/pricing/) [Amazon CloudWatch ](https://aws.amazon.com/cloudwatch/pricing/).
## Afficher les traces entre comptes
Les traces entre comptes sont affichées dans le compte de surveillance. Chaque compte source affiche uniquement les traces locales pour ce compte spécifique. Les sections suivantes supposent que vous êtes connecté au compte de surveillance et que vous avez ouvert la CloudWatch console Amazon. Sur les pages de la carte de suivi et des traces, un badge de compte de surveillance est affiché dans le coin supérieur droit.
![\[Badge de compte de surveillance\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-monitoring-account.png)
### Carte de traçage
Dans la CloudWatch console, choisissez **Trace Map** sous **X-Ray Traces** dans le volet de navigation de gauche. Par défaut, la carte de suivi affiche les nœuds de tous les comptes sources qui envoient des traces au compte de surveillance, ainsi que les nœuds du compte de surveillance lui-même. Sur la carte de trace, choisissez **Filtres** en haut à gauche pour filtrer la carte de trace à l'aide de la liste déroulante **Comptes**. Une fois qu'un filtre de compte est appliqué, les nœuds de service des comptes qui ne correspondent pas au filtre actuel sont grisés.
![\[Carte de suivi filtrée\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png)
Lorsque vous choisissez un nœud de service, le volet de détails du nœud inclut l'ID de compte et le libellé du service.
![\[Volet détaillé du nœud\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png)
Dans le coin supérieur droit de la carte de trace, choisissez Affichage en **liste pour afficher** la liste des nœuds de service. La liste des nœuds de service inclut les services du compte de surveillance et tous les comptes sources configurés. Filtrez la liste des nœuds par **étiquette de compte** ou **identifiant de compte** en les choisissant dans le filtre **Nœuds**.
![\[Liste de services filtrée\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-servicelist-account-filter.png)
### Suivis
Consultez les détails des traces couvrant plusieurs comptes en ouvrant la CloudWatch console depuis le compte de surveillance et en choisissant **Traces** sous **X-Ray Traces** dans le volet de navigation de gauche. Vous pouvez également ouvrir cette page en choisissant un nœud dans la X-Ray **Trace Map**, puis en choisissant **View traces** dans le volet des détails du nœud.
La page **Traces** permet d'effectuer des requêtes par identifiant de compte. Pour commencer, [entrez une requête](xray-console-filters.md) qui inclut un ou plusieurs comptes IDs. L'exemple suivant demande des traces transmises par le biais de l'ID de compte X** ou *Y* :
```
service(id(account.id:"X")) OR service(id(account.id:"Y"))
```
![\[Traces de requêtes par compte\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-traces-query-by-account.png)
Affinez votre requête par **compte**. Sélectionnez un ou plusieurs comptes dans la liste, puis cliquez sur **Ajouter à la requête**.
![\[Affiner la requête de suivi par compte\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png)
### Détails du tracé
Consultez les détails d'une trace en la sélectionnant dans la liste **Traces** en bas de la page **Traces**. Les **détails du suivi** s'affichent, y compris une carte des détails du suivi avec les nœuds de service de tous les comptes traversés par le suivi. Choisissez un nœud de service spécifique pour voir le compte correspondant.
La section **Chronologie des segments** affiche les détails du compte pour chaque segment de la chronologie.
![\[Chronologie des segments\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png)
# Suivi des applications pilotées par des événements
AWS X-Ray prend en charge le suivi des applications pilotées par des événements à l'aide d'Amazon SQS et. AWS Lambda Utilisez la CloudWatch console pour voir une vue connectée de chaque demande mise en file d'attente avec Amazon SQS et traitée par une ou plusieurs fonctions Lambda. Les traces provenant des producteurs de messages en amont sont automatiquement liées aux traces provenant des nœuds consommateurs Lambda en aval, créant ainsi une end-to-end vue de l'application.
**Note**
Chaque segment de trace peut être lié à un maximum de 20 traces, tandis qu'une trace peut inclure un maximum de 100 liens. Dans certains scénarios, l'association de traces supplémentaires peut entraîner le dépassement de la [taille maximale du document de trace](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray), ce qui peut entraîner une trace incomplète. Cela peut se produire, par exemple, lorsqu'une fonction Lambda dont le suivi est activé envoie de nombreux messages SQS à une file d'attente en un seul appel. Si vous rencontrez ce problème, une solution d'atténuation utilisant le X-Ray est disponible SDKs. Consultez le SDK X-Ray pour [Java](https://github.com/aws/aws-xray-sdk-java#oversampling-mitigation), [Node.js](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core#oversampling-mitigation), [Python](https://github.com/aws/aws-xray-sdk-python#oversampling-mitigation), [Go](https://github.com/aws/aws-xray-sdk-go#oversampling-mitigation) ou [.NET](https://github.com/aws/aws-xray-sdk-dotnet#oversampling-mitigation) pour plus d'informations.
## Afficher les traces liées dans la carte des traces
Utilisez la page **Trace Map** de la [CloudWatchconsole](https://console.aws.amazon.com/cloudwatch/) pour afficher une carte de suivi contenant les traces des créateurs de messages associées aux traces des consommateurs Lambda. Ces liens sont affichés avec un bord en pointillé qui connecte le nœud Amazon SQS aux nœuds consommateurs Lambda en aval.
![\[Edge entre les nœuds Amazon SQS et Lambda.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)
Sélectionnez un bord en pointillé pour afficher un histogramme de l'*âge de l'événement reçu*, qui indique la répartition de l'âge de l'événement lorsqu'il est reçu par les consommateurs. L'âge est calculé chaque fois qu'un événement est reçu.
![\[Bord avec histogramme de l'âge de l'événement reçu.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png)
## Afficher les détails du suivi lié
**Consultez les informations de suivi envoyées par un producteur de messages, une file d'attente Amazon SQS ou un client Lambda :**
1. Utilisez la **carte de suivi** pour sélectionner un nœud producteur de messages, Amazon SQS ou consommateur Lambda.
1. Choisissez **Afficher les traces** dans le volet des détails du nœud pour afficher la liste des traces. Vous pouvez également accéder directement à la page **Traces** dans la CloudWatch console.
1. Choisissez une trace spécifique dans la liste pour ouvrir la page des détails de la trace. La page des détails de la trace affiche un message lorsque la trace sélectionnée fait partie d'un ensemble de traces liées.
![\[Détails du tracé lié\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-batch-tracedetails-header.png)
La carte des détails de la trace affiche la trace actuelle, ainsi que les traces liées en amont et en aval, chacune d'elles étant contenue dans un cadre indiquant les limites de chaque trace. Si la trace actuellement sélectionnée est liée à plusieurs traces en amont ou en aval, les nœuds des traces liées en amont ou en aval sont empilés et un bouton **Sélectionner une trace** s'affiche.
![\[Plusieurs traces en amont liées\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png)
Sous la carte des détails du tracé, une chronologie des segments de trace s'affiche, y compris les traces liées en amont et en aval. S'il existe plusieurs traces liées en amont ou en aval, les détails de leurs segments ne peuvent pas être affichés. Pour afficher les détails d'un segment pour une seule trace au sein d'un ensemble de traces liées, [sélectionnez une seule trace](#xray-tracelinking-filterbatch) comme décrit ci-dessous.
![\[Chronologie des segments montrant les traces liées\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-batch-tracedetails-timeline.png)
## Sélectionnez une seule trace parmi un ensemble de traces liées
**Filtrez un ensemble de traces liées en une seule trace, pour voir les détails des segments dans la chronologie.**
1. Choisissez **Sélectionner une trace** sous les traces liées sur la carte des détails de la trace. La liste des traces s'affiche.
![\[Liste de traces liée\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png)
1. Sélectionnez le bouton radio à côté d'une trace pour l'afficher dans la carte des détails de la trace.
1. Choisissez **Annuler la sélection de traces** pour afficher l'ensemble complet des traces liées.
![\[Trace à lien unique\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png)
# Utilisation d'histogrammes de latence
Lorsque vous sélectionnez un nœud ou une arête sur une [carte de AWS X-Ray traçage, la](xray-console-servicemap.md) console X-Ray affiche un histogramme de distribution de latence.
## Latence
La latence correspond au temps écoulé entre le moment où une demande commence et celui où elle prend fin. Un histogramme montre la répartition des latences. Il indique la durée sur l'axe X et le pourcentage de demandes correspondant à chaque durée sur l'axe Y.
Cet histogramme montre un service qui répond à la plupart des demandes en moins de 300 ms. Un faible pourcentage des demandes prennent jusqu'à 2 secondes et quelques valeurs hors norme peuvent prendre un peu plus de temps.
![\[Histogramme des latences avec la durée sur l'axe X et le pourcentage de demandes pour chaque durée sur l'axe Y\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-servicemap-histogram.png)
## Interprétation des détails du service
Les histogrammes des services et des arcs offrent une représentation visuelle des latences du point de vue d'un service ou d'un demandeur.
+ Choisissez un *nœud de service* en cliquant sur le cercle. X-Ray affiche un histogramme des demandes traitées par le service. Les latences sont celles enregistrées par le service et n'incluent aucune latence réseau entre le service et le demandeur.
+ Choisissez une *arête* en cliquant sur le bout de la ligne ou de la flèche située entre deux services. X-Ray affiche un histogramme des demandes du demandeur qui ont été traitées par le service en aval. Les latences sont celles enregistrées par le demandeur et incluent les latences au niveau de la connexion réseau entre les deux services.
Pour interpréter l'histogramme du panneau **Service details**, vous pouvez rechercher les valeurs les plus extrêmes. Ces *valeurs hors norme* peuvent être considérées comme des pics dans l'histogramme. Vous pouvez alors consulter les suivis d'une zone donnée pour voir ce qu'il se passe.
Pour afficher les suivis filtrés par latence, sélectionnez une plage dans l'histogramme. Cliquez à l'endroit où vous souhaitez commencer la sélection et faites glisser la souris de la gauche vers la droite pour mettre en surbrillance une plage de latences à inclure dans le filtre de suivi.
![\[Pour sélectionner une plage pour laquelle afficher les suivis, cliquez à l'endroit où vous souhaitez commencer et faites glisser la souris de la gauche vers la droite afin de créer la plage du filtre de suivi\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png)
Une fois que vous avez sélectionné une plage, vous pouvez choisir **Zoom** pour afficher uniquement une certaine partie de l'histogramme et affiner votre sélection.
![\[Choisissez Zoom pour afficher la plage sélectionnée dans l'histogramme\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png)
Une fois que vous avez défini la zone qui vous intéresse, choisissez **View traces**.
# Utilisation des informations issues de X-Ray
AWS X-Ray analyse en permanence les données de suivi de votre compte afin d'identifier les problèmes émergents dans vos applications. Lorsque les taux de défaillance dépassent la plage prévue, cela crée un *aperçu* qui enregistre le problème et suit son impact jusqu'à ce qu'il soit résolu. Grâce à Insights, vous pouvez :
+ Identifiez l'endroit où les problèmes se produisent dans votre application, la cause première du problème et l'impact associé. L'analyse d'impact fournie par Insights vous permet de déterminer la gravité et la priorité d'un problème.
+ Recevez des notifications lorsque le problème évolue au fil du temps. Les notifications Insights peuvent être intégrées à votre solution de surveillance et d'alerte à l'aide d'Amazon EventBridge. Cette intégration vous permet d'envoyer des e-mails ou des alertes automatisés en fonction de la gravité du problème.
La console X-Ray identifie les nœuds présentant des incidents en cours sur la carte de trace. Pour voir un résumé des informations, choisissez le nœud concerné. Vous pouvez également afficher et filtrer les informations en choisissant **Insights** dans le volet de navigation de gauche.
![\[Tracez le nœud cartographique avec un résumé des informations.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights-servicemap.png)
X-Ray crée un aperçu lorsqu'il détecte une *anomalie* dans un ou plusieurs nœuds de la carte des services. Le service utilise une modélisation statistique pour prévoir les taux de défaillance attendus des services de votre application. Dans l'exemple précédent, l'anomalie est une augmentation du nombre de défauts provenant de AWS Elastic Beanstalk. Le serveur Elastic Beanstalk a connu plusieurs délais d'attente pour les appels d'API, ce qui a provoqué une anomalie dans les nœuds en aval.
## Activez les informations dans la console X-Ray
Insights doit être activé pour chaque groupe avec lequel vous souhaitez utiliser les fonctionnalités Insights. Vous pouvez activer les informations depuis la page **Groupes**.
1. Ouvrez la [console X-Ray](https://console.aws.amazon.com/xray/home#).
1. Sélectionnez un groupe existant ou créez-en un nouveau en choisissant **Create group**, puis en sélectionnant **Enable Insights**. Pour plus d'informations sur la configuration des groupes dans la console X-Ray, consultez[Configuration des groupes](xray-console-groups.md).
1. Dans le volet de navigation de gauche, choisissez **Insights**, puis choisissez un aperçu à afficher.
![\[Liste des informations disponibles dans la console X-Ray.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights.png)
**Note**
X-Ray utilise GetInsightSummaries, GetInsight GetInsightEvents, et des opérations GetInsightImpactGraph d'API pour récupérer des données à partir d'informations.
Pour de plus amples informations, veuillez consulter [Comment AWS X-Ray fonctionne avec IAM](security_iam_service-with-iam.md).
## Activez les notifications d'informations
Avec les notifications d'informations, une notification est créée pour chaque événement d'information, par exemple lorsqu'une information est créée, change de manière significative ou est fermée. Les clients peuvent recevoir ces notifications par le biais d' EventBridge événements Amazon et utiliser des règles conditionnelles pour effectuer des actions telles que la notification SNS, l'invocation Lambda, la publication de messages dans une file d'attente SQS ou l'un des supports cibles. EventBridge Les notifications Insights sont émises dans la mesure du possible, mais ne sont pas garanties. Pour plus d'informations sur les cibles, consultez [Amazon EventBridge Targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html).
Vous pouvez activer les notifications d'informations pour tout groupe activé sur la page **Groupes**.
**Pour activer les notifications pour un groupe X-Ray**
1. Ouvrez la [console X-Ray](https://console.aws.amazon.com/xray/home#).
1. Sélectionnez un groupe existant ou créez-en un nouveau en choisissant **Créer un groupe**, assurez-vous que l'**option Activer les informations** est sélectionnée, puis sélectionnez **Activer les notifications**. Pour plus d'informations sur la configuration des groupes dans la console X-Ray, consultez[Configuration des groupes](xray-console-groups.md).
**Pour configurer les règles EventBridge conditionnelles d'Amazon**
1. Ouvrez la [ EventBridge console Amazon](https://console.aws.amazon.com/events/home).
1. Accédez à **Règles** dans la barre de navigation de gauche, puis choisissez **Créer une règle**.
1. Donnez un nom et une description à la règle.
1. Choisissez **Modèle d'événement**, puis choisissez **Modèle personnalisé**. Fournissez un modèle contenant `"source": [ "aws.xray" ]` et`"detail-type": [ "AWS X-Ray Insight Update" ]`. Voici quelques exemples de modèles possibles.
+ Modèle d'événements correspondant à tous les événements entrants provenant de X-Ray Insights :
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ]
}
```
+ Modèle d'événement correspondant à une valeur spécifiée **state** et **category** :
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ],
"detail": {
"State": [ "ACTIVE" ],
"Category": [ "FAULT" ]
}
}
```
1. Sélectionnez et configurez les cibles que vous souhaitez appeler lorsqu'un événement répond à cette règle.
1. (Facultatif) Fournissez des balises pour identifier et sélectionner plus facilement cette règle.
1. Choisissez **Créer**.
**Note**
Les notifications X-Ray Insights envoient des événements à Amazon EventBridge, qui ne prend actuellement pas en charge les clés gérées par les clients. Pour de plus amples informations, veuillez consulter [Protection des données dans AWS X-Ray](xray-console-encryption.md).
## Aperçu d'Insight
La page de présentation d'un aperçu tente de répondre à trois questions clés :
+ Quel est le problème sous-jacent ?
+ Quelle en est la cause première ?
+ Quel en est l'impact ?
La section **Services anormaux** présente une chronologie pour chaque service qui illustre l'évolution du taux de défaillance au cours de l'incident. La chronologie indique le nombre de traces comportant des défaillances superposées sur une bande continue qui indique le nombre de défaillances attendu en fonction du volume de trafic enregistré. La durée de l'aperçu est visualisée par la *fenêtre Incident.* La fenêtre d'incident commence lorsque X-Ray observe que la métrique devient anormale et persiste tant que l'aperçu est actif.
L'exemple suivant montre une augmentation du nombre de défaillances à l'origine d'un incident :
![\[Page d'aperçu d'un X-Ray Insight.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights-overview.png)
La section **Cause première** affiche une carte de trace axée sur le service responsable et le chemin concerné. Vous pouvez masquer les nœuds non affectés en sélectionnant l'icône en forme d'œil en haut à droite de la carte des causes profondes. Le service responsable est le nœud le plus en aval où X-Ray a identifié une anomalie. Il peut s'agir d'un service que vous avez instrumenté ou d'un service externe que votre service a appelé auprès d'un client instrumenté. Par exemple, si vous appelez Amazon DynamoDB avec un client SDK AWS instrumenté, l'augmentation du nombre de défaillances provenant de DynamoDB permet d'obtenir un aperçu dont DynamoDB est la cause première.
Pour étudier plus en détail la cause première, sélectionnez **Afficher les détails de la cause** première sur le graphique des causes premières. Vous pouvez utiliser la page **Analytics** pour rechercher la cause première et les messages associés. Pour de plus amples informations, veuillez consulter [Interaction avec la console Analytics](xray-console-analytics.md).
![\[Page d'aperçu d'un X-Ray Insight.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights-root-cause.png)
Les défaillances qui se poursuivent en amont de la carte peuvent avoir un impact sur plusieurs nœuds et provoquer de multiples anomalies. Si une erreur est retransmise à l'utilisateur qui a fait la demande, il en résulte une *erreur du client*. Il s'agit d'un défaut dans le nœud racine de la carte de trace. Le graphique d'**impact** fournit une chronologie de l'expérience client pour l'ensemble du groupe. **Cette expérience est calculée en fonction des pourcentages des états suivants : **Fault**, **Error**, **Throttle** et OK.**
![\[Graphique d'impact d'un incident aux rayons X.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights-impact.png)
Cet exemple montre une augmentation du nombre de traces associées à une défaillance au niveau du nœud racine au moment d'un incident. Les incidents dans les services en aval ne correspondent pas toujours à une augmentation des erreurs des clients.
Choisissez **Analyze insight pour** ouvrir la console X-Ray Analytics dans une fenêtre dans laquelle vous pouvez examiner en détail l'ensemble des traces à l'origine des informations. Pour de plus amples informations, veuillez consulter [Interaction avec la console Analytics](xray-console-analytics.md).
**Comprendre l'impact**
AWS X-Ray mesure l'impact causé par un problème persistant dans le cadre de la génération d'informations et de notifications. L'impact est mesuré de deux manières :
+ Impact sur le [groupe](xray-console-groups.md) X-Ray
+ Impact sur le service responsable
Cet impact est déterminé par le pourcentage de demandes qui échouent ou sont à l'origine d'une erreur au cours d'une période donnée. Cette analyse d'impact vous permet de déterminer la gravité et la priorité du problème en fonction de votre scénario particulier. Cet impact est disponible dans le cadre de l'expérience de console, en plus des notifications d'informations.
**Déduplication**
AWS X-Ray Insights déduplique les problèmes sur plusieurs microservices. Il utilise la détection des anomalies pour déterminer le service à l'origine d'un problème, déterminer si d'autres services connexes présentent un comportement anormal dû à la même cause première et enregistre le résultat sous forme d'aperçu unique.
## Passez en revue la progression d'un aperçu
X-Ray réévalue régulièrement les informations jusqu'à ce qu'elles soient résolues, et enregistre chaque modification intermédiaire notable sous forme de [notification](#xray-console-insight-notifications), qui peut être envoyée sous forme d'événement Amazon EventBridge . Cela vous permet de créer des processus et des flux de travail pour déterminer l'évolution du problème au fil du temps et de prendre les mesures appropriées, telles que l'envoi d'un e-mail ou l'intégration à un système d'alerte utilisant EventBridge.
Vous pouvez consulter les événements de l'incident dans la **chronologie de l'impact** sur la page **Inspect**. Par défaut, la chronologie affiche le service le plus touché jusqu'à ce que vous choisissiez un autre service.
![\[Inspectez la page avec la chronologie de l'impact.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights-inspect.png)
Pour consulter la carte de suivi et les graphiques d'un événement, sélectionnez-le dans la chronologie de l'impact. La carte de suivi indique les services de votre application concernés par l'incident. Sous **Analyse d'impact**, les graphiques indiquent la chronologie des défaillances pour le nœud sélectionné et pour les clients du groupe.
![\[Graphique d'analyse d'impact pour un aperçu de X-Ray\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/console-insights-inspect-analysis.png)
Pour examiner de manière plus approfondie les traces impliquées dans un incident, choisissez **Analyser l'événement** sur la page **Inspecter**. Vous pouvez utiliser la page **Analytics** pour affiner la liste des traces et identifier les utilisateurs concernés. Pour de plus amples informations, veuillez consulter [Interaction avec la console Analytics](xray-console-analytics.md).
# Interaction avec la console Analytics
La console AWS X-Ray Analytics est un outil interactif permettant d'interpréter les données de trace afin de comprendre rapidement les performances de votre application et de ses services sous-jacents. La console vous permet d'explorer, d'analyser et de visualiser les suivis grâce à des graphiques interactifs sur les temps de réponse et la chronologie.
Lorsque vous sélectionnez un élément dans la console Analytics, celle-ci crée des filtres afin d’afficher le sous-ensemble de suivis sélectionné. Vous pouvez affiner l’ensemble de données actif en appliquant des filtres de plus en plus précis. Pour ce faire, cliquez sur les graphiques, les panneaux de métriques et les champs associés à l’ensemble de suivis sélectionné.
**Topics**
+ [Fonctions de la console](#xray-console-analytics-features)
+ [Distribution des temps de réponse](#xray-console-analytics-response)
+ [Activités chronologiques](#xray-console-analytics-time)
+ [Exemples de flux de travail](#xray-console-analytics-workflows)
+ [Observez les erreurs sur le graphique des services](#xray-console-analytics-observe-faults)
+ [Identifier les pics des temps de réponse](#xray-console-analytics-response-peaks)
+ [Afficher tous les suivis marqués d'un code d'état](#xray-console-analytics-response-peaks)
+ [Affichage de l'ensemble des éléments d'un sous-groupe et associés à un utilisateur](#xray-console-analytics-subgroups)
+ [Comparaison de deux ensembles de suivis avec des critères différents](#xray-console-analytics-compare)
+ [Identifier un suivi qui vous intéresse et afficher ses détails](#xray-console-analytics-identify)
## Fonctions de la console
La console X-Ray Analytics utilise les fonctionnalités clés suivantes pour regrouper, filtrer, comparer et quantifier les données de suivi.
### Fonctionnalités
| Fonctionnalité | Description |
| --- | --- |
| **Groups** (Groupes) | Le premier groupe sélectionné est `Default`. Pour modifier le groupe extrait, sélectionnez un groupe différent dans le menu situé à droite de la barre de recherche principale pour les expressions de filtre. Pour plus d’informations sur les groupes, consultez [Utilisation d'expressions de filtrage avec les groupes](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html#groups). |
| **Retrieved traces** (Suivis extraits) | Par défaut, la console Analytics génère des graphiques basés sur tous les suivis du groupe sélectionné. Les suivis extraits représentent tous les suivis de l’ensemble sur lequel vous travaillez. Le nombre de suivis est affiché dans cette vignette. Les expressions de filtre que vous appliquez à la barre de recherche principale affinent et mettent à jour les suivis extraits. |
| **Show in charts/Hide from charts** (Afficher dans les graphiques/Masquer dans les graphiques) | Une fonctionnalité de basculement pour comparer le groupe actif aux suivis extraits. Pour comparer les données du groupe aux filtres actifs, sélectionnez **Show in charts** (Afficher dans les graphiques). Pour supprimer cette vue des graphiques, sélectionnez **Hide from charts** (Masquer dans les graphiques). |
| **Filtered trace set A** (Ensemble de suivis filtrés A) | En interagissant avec les graphiques et les tableaux, appliquez des filtres pour créer les critères du **jeu de traces filtré** A. Au fur et à mesure que les filtres sont appliqués, le nombre de traces applicables et le pourcentage de traces extraites par rapport au total sont calculés dans cette vignette. Les filtres sont renseignés comme des balises au sein de la vignette **Filtered trace set A (Ensemble de suivis filtrés A)** et peuvent également être supprimés de la vignette. |
| **Refine** (Affiner) | Cette fonction met à jour l'ensemble des suivis extraits en fonction des filtres appliqués à l'ensemble de suivis A. L'affinage de l'ensemble permet d'actualiser le jeu de suivis extraits sur lequel vous travaillez en fonction des filtres de l'ensemble des suivis A. L'ensemble des suivis extraits sur lequel vous travaillez est un exemple de sous-ensemble de tous les suivis du groupe. |
| **Filtered trace set B** (Ensemble de suivis filtrés B) | Une fois créé, le **jeu de traces filtré B** est une copie du **jeu de traces filtré** A. Pour comparer les deux ensembles de traces, effectuez de nouvelles sélections de filtres qui s'appliqueront au jeu de traces B, tandis que le jeu de traces A reste fixe. À mesure que les filtres sont appliqués, le nombre de suivis applicables ainsi que le pourcentage de suivis par rapport au nombre total de suivis extraits sont recalculés au sein de la vignette. Les filtres sont renseignés comme des balises au sein de la vignette **Filtered trace set B (Ensemble de suivis filtrés B)**. Ils peuvent également être supprimés de la vignette. |
| **Response Time Root Cause Entity Paths (Chemins d’entité constituant la cause racine du temps de réponse)** | Tableau des chemins d'entités enregistrés. X-Ray détermine la trajectoire de votre trace qui est la cause la plus probable du temps de réponse. Le format indique une hiérarchie d’entités qui a été rencontrée, qui constitue la cause racine du temps de réponse. Utilisez ces lignes pour filtrer les erreurs de temps de réponse récurrentes. Pour plus d’informations sur la personnalisation des filtres de cause racine et sur l'obtention des données via l'API, consultez [Extraction et affinage de l'analyse de la cause racine](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics). |
| **Delta (**�**)** | Colonne qui est ajoutée aux tables de métriques lorsque les ensembles A et B sont tous les deux actifs. La colonne Delta calcule la différence de suivis entre l'ensemble A et l'ensemble B sous forme de pourcentage. |
## Distribution des temps de réponse
La console X-Ray Analytics génère deux graphiques principaux pour vous aider à visualiser les traces : la **distribution du temps de réponse** et **l'activité des séries chronologiques**. Cette section fournit des exemples de chacun de ces graphiques, et explique les principes de base pour savoir les lire.
Voici les couleurs associées au graphique linéaire des temps de réponse (le graphique chronologique utilise le même code couleurs) :
+ **Toutes les traces du groupe** — gris
+ **Traces récupérées** — orange
+ **Set de traces filtrées A** — vert
+ **Set de traces filtrées B** — bleu
**Example — Répartition du temps de réponse**
La distribution des temps de réponse est un graphique qui montre le nombre de suivis correspondant à un temps de réponse donné. Cliquez et faites glisser pour effectuer des sélections au sein du graphique de distribution des temps de réponse. Lorsque vous effectuez une sélection, un filtre est créé pour l’ensemble des suivis actifs. Cet ensemble est appelé `responseTime`, et correspond à tous les suivis au sein d'un temps de réponse spécifique.
![\[Un graphique qui montre la distribution du temps de réponse des traces.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/analytics-responseTime.png)
## Activités chronologiques
Le graphique sur les activités chronologiques affiche le nombre de suivis sur une période donnée. Les indicateurs de couleurs reflètent le graphique linéaire de distribution des temps de réponse. Plus le bloc de couleur est foncé et rempli dans les activités chronologiques, plus la quantité de suivis représentée est élevée pour la période de temps donnée.
**Example — Activité liée aux séries chronologiques**
Cliquez et faites glisser pour effectuer des sélections au sein du graphique d’activités chronologiques. Lorsque vous effectuez une sélection, un filtre appelé `timerange` est créé pour l’ensemble des suivis actifs au sein d’une période de temps spécifique.
![\[Make a selection and create filter (Effectuer une sélection et créer un filtre)\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/analytics-timeSeries.png)
## Exemples de flux de travail
Les exemples suivants présentent des cas d'utilisation courants de la console X-Ray Analytics. Chaque exemple montre une fonctionnalité clé de la console. En tant que groupe, les exemples suivent un flux de travail basique pour la résolution de problèmes. Les étapes expliquent comment repérer d'abord les nœuds défectueux, puis comment interagir avec la console Analytics pour générer automatiquement des requêtes comparatives. Une fois que vous avez réduit la portée par le biais de requêtes, vous examinez enfin les détails des suivis d'intérêt pour déterminer ce qui nuit à l'état de votre service.
## Observez les erreurs sur le graphique des services
La carte de suivi indique l'état de santé de chaque nœud en le colorant en fonction du rapport entre les appels réussis et les erreurs et les défaillances. Lorsque votre nœud affiche un pourcentage rouge, cela indique une erreur. Utilisez la console X-Ray Analytics pour l'étudier.
Pour plus d'informations sur la façon de lire la carte de trace, reportez-vous à la section [Affichage de la carte de trace](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap).
![\[Observe a fault (Examiner une erreur)\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png)
## Identifier les pics des temps de réponse
À l’aide du graphique sur la distribution des temps de réponse, vous pouvez observer les pics. Lorsque vous sélectionnez un pic dans les temps de réponse, les tables en dessous des graphiques se mettent à jour afin d'afficher toutes les métriques associées, comme les codes d'état.
Lorsque vous cliquez et faites glisser le pointeur, X-Ray sélectionne et crée un filtre. Il est grisé au-dessus des lignes du graphique. Vous pouvez alors faire glisser cet élément grisé vers la gauche ou vers la droite de la distribution pour modifier la sélection et filtrer.
![\[Make a selection and create filter (Effectuer une sélection et créer un filtre)\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/analytics-showFilterf.png)
## Afficher tous les suivis marqués d'un code d'état
Vous pouvez afficher le détail des suivis au sein du pic sélectionné à l’aide des tables de métriques en dessous des graphiques. En cliquant sur une ligne de la table **HTTP STATUS CODE** (CODE D’ÉTAT HTTP), vous créez automatiquement un filtre pour l’ensemble de données actif. Par exemple, vous pouvez afficher tous les suivis du code d'état 500. Une balise de filtre est alors créée dans la vignette de l’ensemble des suivis nommé `http.status`.
## Affichage de l'ensemble des éléments d'un sous-groupe et associés à un utilisateur
Affichez le détail de l’ensemble des erreurs en fonction de l’utilisateur, de l’URL, de la cause racine du temps de réponse et d’autres attributs prédéfinis. Par exemple, pour filtrer l'ensemble des suivis dont le code d’état est 500, sélectionnez une ligne dans la table **USERS** (UTILISATEURS). Deux balises de filtre sont alors générées dans la vignette de l’ensemble des suivis : `http.status`, comme indiqué précédemment, et `user`.
## Comparaison de deux ensembles de suivis avec des critères différents
Comparez plusieurs utilisateurs et leurs requêtes POST pour identifier des divergences et des corrélations. Appliquez votre premier ensemble de filtres. Ils sont indiqués par une ligne bleue dans le graphique de distribution des temps de réponse. Ensuite, sélectionnez **Compare** (Comparer). Pour commencer, une copie des filtres est créée sur l’ensemble des suivis A.
Ensuite, définissez un nouvel ensemble de filtres à appliquer à l’ensemble des suivis B. Ce deuxième ensemble est représenté par une ligne verte. L'exemple suivant montre les différentes courbes conformément au code de couleurs (bleu et vert).
![\[Line graph comparison (Comparaison au sein des graphiques linéaires)\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/analytics-compareLines.png)
## Identifier un suivi qui vous intéresse et afficher ses détails
À mesure que vous réduisez le champ d’application à l’aide des filtres de la console, la liste des suivis en dessous des tables de métriques devient plus parlante. La table de la liste des suivis combine des informations sur l'**URL**, l'**UTILISATEUR**, et le **CODE D'ÉTAT** dans une même vue. Pour obtenir plus d’informations, sélectionnez une ligne de la table afin d’ouvrir la page détaillée du suivi et d’examiner sa chronologie et ses données brutes.
# Configuration des groupes
Les groupes constituent un ensemble de suivis qui sont définis par une expression de filtre. Vous pouvez utiliser des groupes pour générer des graphiques de service supplémentaires et fournir CloudWatch des statistiques Amazon. Vous pouvez utiliser la AWS X-Ray console ou l'API X-Ray pour créer et gérer des groupes pour vos services. Cette rubrique explique comment créer et gérer des groupes à l'aide de la console X-Ray. Pour plus d'informations sur la gestion des groupes à l'aide de l'API X-Ray, consultez[Groupes](xray-api-configuration.md#xray-api-configuration-groups).
Vous pouvez créer des groupes de traces pour les cartes de traçage, les traces ou les analyses. Lorsque vous créez un groupe, celui-ci devient disponible sous forme de filtre dans le menu déroulant du groupe sur les trois pages : **Trace Map**, **Traces** et **Analytics**.
![\[Menu de groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-menu.png)
Les groupes sont identifiés par leur nom ou un Amazon Resource Name (ARN), et contiennent une expression de filtre. Le service compare les suivis entrants à l'expression, et les stocke en conséquence. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md).
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 [Pricing AWS X-Ray](https://aws.amazon.com/xray/pricing/) (Tarification).
**Topics**
+ [Créez un groupe](#xray-console-group-create-console)
+ [Appliquer un groupe](#xray-console-group-apply)
+ [Modifier un groupe](#xray-console-group-edit)
+ [Cloner un groupe](#xray-console-group-clone)
+ [Supprimer un groupe](#xray-console-group-delete)
+ [Afficher les statistiques du groupe sur Amazon CloudWatch](#xray-console-group-cloudwatch)
## Créez un groupe
**Note**
Vous pouvez désormais configurer les groupes X-Ray depuis la CloudWatch console Amazon. Vous pouvez également continuer à utiliser la console X-Ray.
------
#### [ CloudWatch console ]
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Paramètres** dans le volet de navigation de gauche.
1. Choisissez **Afficher les paramètres** sous **Groupes** dans la section **X-Ray Traces**.
1. Choisissez **Créer un groupe** au-dessus de la liste des groupes.
1. Sur la page **Créer un groupe**, entrez le nom du groupe. Le nom d'un groupe peut comporter un maximum de 32 caractères, dont des caractères alphanumériques et des tirets. Les noms de groupes distinguent les majuscules et minuscules.
1. Entrez une expression de filtre. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md). Dans l'exemple suivant, le groupe filtre les traces d'erreur provenant du service `api.example.com` et les demandes adressées au service dont le temps de réponse était supérieur ou égal à cinq secondes.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Dans **Insights**, activez ou désactivez l'accès aux insights pour le groupe. Pour en savoir plus sur les informations, consultez [Utilisation des informations issues de X-Ray](xray-console-insights.md).
![\[Cases à cocher Insights sur la page Groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-insights-cw.png)
1. Dans **Balises**, choisissez **Ajouter une nouvelle balise** pour saisir une clé de balise et, éventuellement, une valeur de balise. Continuez à ajouter des balises supplémentaires si vous le souhaitez. Les clés de tag doivent être uniques. Pour supprimer un tag, choisissez **Supprimer** en dessous de chaque tag. Pour en savoir plus sur les identifications, consultez [Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
![\[Marquer les champs sur la page du groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-tags-cw.png)
1. Choisissez **Créer un groupe**.
------
#### [ X-Ray console ]
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Ouvrez la page **Créer un groupe** depuis la page **Groupes** du volet de navigation de gauche ou depuis le menu du groupe sur l'une des pages suivantes : **Trace Map**, **Traces** et **Analytics**.
1. Sur la page **Créer un groupe**, entrez le nom du groupe. Le nom d'un groupe peut comporter un maximum de 32 caractères, dont des caractères alphanumériques et des tirets. Les noms de groupes distinguent les majuscules et minuscules.
1. Entrez une expression de filtre. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md). Dans l'exemple suivant, le groupe filtre les traces d'erreur provenant du service `api.example.com` et les demandes adressées au service dont le temps de réponse était supérieur ou égal à cinq secondes.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Dans **Insights**, activez ou désactivez l'accès aux insights pour le groupe. Pour en savoir plus sur les informations, consultez [Utilisation des informations issues de X-Ray](xray-console-insights.md).
![\[Cases à cocher Insights sur la page Groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-insights.png)
1. Dans **Balises**, entrez une clé de balise et, éventuellement, une valeur de balise. Lorsque vous ajoutez un tag, une nouvelle ligne apparaît pour vous permettre de saisir un autre tag. Les clés de tag doivent être uniques. Pour supprimer un tag, choisissez **X** à la fin de la ligne du tag. Pour en savoir plus sur les identifications, consultez [Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
![\[Marquer les champs sur la page du groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-tags.png)
1. Choisissez **Créer un groupe**.
------
## Appliquer un groupe
------
#### [ CloudWatch console ]
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Ouvrez l'une des pages suivantes depuis le volet de navigation sous **X-Ray Traces** :
+ **Carte de suivi**
+ **Suivis**
1. Entrez un nom de groupe dans le **filtre de groupe Filter by X-Ray**. Les données affichées sur la page changent pour correspondre à l'expression de filtre définie dans le groupe.
------
#### [ X-Ray console ]
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Ouvrez l'une des pages suivantes depuis le volet de navigation :
+ **Carte de suivi**
+ **Suivis**
+ **Analyse**
1. Dans le menu du groupe, choisissez le groupe dans lequel vous avez créé le groupe[Créez un groupe](#xray-console-group-create-console). Les données affichées sur la page changent pour correspondre à l'expression de filtre définie dans le groupe.
------
## Modifier un groupe
------
#### [ CloudWatch console ]
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Paramètres** dans le volet de navigation de gauche.
1. Choisissez **Afficher les paramètres** sous **Groupes** dans la section **X-Ray Traces**.
1. Choisissez un groupe dans la section **Groupes**, puis sélectionnez **Modifier**.
1. Bien que vous ne puissiez pas renommer un groupe, vous pouvez mettre à jour l'expression du filtre. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md). Dans l'exemple suivant, le groupe filtre les traces d'erreur provenant du service`api.example.com`, où figure l'adresse URL de la demande`example/game`, et le temps de réponse des demandes était supérieur ou égal à cinq secondes.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Dans **Insights**, activez ou désactivez l'accès aux insights pour le groupe. Pour en savoir plus sur les informations, consultez [Utilisation des informations issues de X-Ray](xray-console-insights.md).
![\[Cases à cocher Insights sur la page Groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-insights-cw.png)
1. Dans **Balises**, choisissez **Ajouter une nouvelle balise** pour saisir une clé de balise et, éventuellement, une valeur de balise. Continuez à ajouter des balises supplémentaires si vous le souhaitez. Les clés de tag doivent être uniques. Pour supprimer un tag, choisissez **Supprimer** en dessous de chaque tag. Pour en savoir plus sur les identifications, consultez [Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
![\[Marquer les champs sur la page du groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-tags-cw.png)
1. Lorsque vous avez terminé de mettre à jour le groupe, choisissez **Mettre à jour le groupe**.
------
#### [ X-Ray console ]
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Procédez de l'une des manières suivantes pour ouvrir la page **Modifier le groupe**.
1. Sur la page **Groupes**, choisissez le nom d'un groupe pour le modifier.
1. Dans le menu des groupes de l'une des pages suivantes, pointez sur un groupe, puis choisissez **Modifier**.
+ **Carte de suivi**
+ **Suivis**
+ **Analyse**
1. Bien que vous ne puissiez pas renommer un groupe, vous pouvez mettre à jour l'expression du filtre. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md). Dans l'exemple suivant, le groupe filtre les traces d'erreur provenant du service`api.example.com`, où figure l'adresse URL de la demande`example/game`, et le temps de réponse des demandes était supérieur ou égal à cinq secondes.
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. Dans **Insights**, activez ou désactivez les informations et les notifications d'informations pour le groupe. Pour en savoir plus sur les informations, consultez [Utilisation des informations issues de X-Ray](xray-console-insights.md).
![\[Cases à cocher Insights sur la page Groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-insights.png)
1. Dans **Balises**, modifiez les clés et les valeurs des balises. Les clés de tag doivent être uniques. Les valeurs des balises sont facultatives ; vous pouvez supprimer des valeurs si vous le souhaitez. Pour supprimer un tag, choisissez **X** à la fin de la ligne du tag. Pour en savoir plus sur les identifications, consultez [Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
![\[Marquer les champs sur la page du groupe\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/group-tags.png)
1. Lorsque vous avez terminé de mettre à jour le groupe, choisissez **Mettre à jour le groupe**.
------
## Cloner un groupe
Le clonage d'un groupe crée un nouveau groupe qui possède l'expression de filtre et les balises d'un groupe existant. Lorsque vous clonez un groupe, le nouveau groupe porte le même nom que le groupe à partir duquel il a été cloné, avec un `-clone` ajout au nom.
------
#### [ CloudWatch console ]
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Paramètres** dans le volet de navigation de gauche.
1. Choisissez **Afficher les paramètres** sous **Groupes** dans la section **X-Ray Traces**.
1. Choisissez un groupe dans la section **Groupes**, puis cliquez sur **Cloner**.
1. Sur la page **Créer un groupe**, le nom du groupe est *group-name*`-clone`. Entrez éventuellement un nouveau nom pour le groupe. Le nom d'un groupe peut comporter un maximum de 32 caractères, dont des caractères alphanumériques et des tirets. Les noms de groupes distinguent les majuscules et minuscules.
1. Vous pouvez conserver l'expression de filtre du groupe existant ou éventuellement entrer une nouvelle expression de filtre. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md). Dans l'exemple suivant, le groupe filtre les traces d'erreur provenant du service `api.example.com` et les demandes adressées au service dont le temps de réponse était supérieur ou égal à cinq secondes.
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. Dans **Balises**, modifiez les clés et les valeurs des balises, si nécessaire. Les clés de tag doivent être uniques. Les valeurs des balises sont facultatives ; vous pouvez supprimer des valeurs si vous le souhaitez. Pour supprimer un tag, choisissez **X** à la fin de la ligne du tag. Pour en savoir plus sur les identifications, consultez [Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
1. Choisissez **Créer un groupe**.
------
#### [ X-Ray console ]
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Ouvrez la page **Groupes** dans le volet de navigation de gauche, puis choisissez le nom du groupe que vous souhaitez cloner.
1. Choisissez le **groupe Cloner** dans le menu **Actions**.
1. Sur la page **Créer un groupe**, le nom du groupe est *group-name*`-clone`. Entrez éventuellement un nouveau nom pour le groupe. Le nom d'un groupe peut comporter un maximum de 32 caractères, dont des caractères alphanumériques et des tirets. Les noms de groupes distinguent les majuscules et minuscules.
1. Vous pouvez conserver l'expression de filtre du groupe existant ou éventuellement entrer une nouvelle expression de filtre. Pour plus d'informations sur la création d'une expression de filtre, consultez[Utilisation d'expressions de filtre](xray-console-filters.md). Dans l'exemple suivant, le groupe filtre les traces d'erreur provenant du service `api.example.com` et les demandes adressées au service dont le temps de réponse était supérieur ou égal à cinq secondes.
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. Dans **Balises**, modifiez les clés et les valeurs des balises, si nécessaire. Les clés de tag doivent être uniques. Les valeurs des balises sont facultatives ; vous pouvez supprimer des valeurs si vous le souhaitez. Pour supprimer un tag, choisissez **X** à la fin de la ligne du tag. Pour en savoir plus sur les identifications, consultez [Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
1. Choisissez **Créer un groupe**.
------
## Supprimer un groupe
Suivez les étapes décrites dans cette section pour supprimer un groupe. Vous ne pouvez pas supprimer le groupe **par défaut**.
------
#### [ CloudWatch console ]
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Paramètres** dans le volet de navigation de gauche.
1. Choisissez **Afficher les paramètres** sous **Groupes** dans la section **X-Ray Traces**.
1. Choisissez un groupe dans la section **Groupes**, puis sélectionnez **Supprimer**.
1. Lorsque vous êtes invité à confirmer, choisissez **Supprimer**.
------
#### [ X-Ray console ]
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Ouvrez la page **Groupes** dans le volet de navigation de gauche, puis choisissez le nom du groupe que vous souhaitez supprimer.
1. Dans le menu **Actions**, choisissez **Supprimer le groupe**.
1. Lorsque vous êtes invité à confirmer, choisissez **Supprimer**.
------
## Afficher les statistiques du groupe sur Amazon CloudWatch
Après la création d'un groupe, les traces entrantes sont vérifiées par rapport à l'expression du filtre du groupe lorsqu'elles sont stockées dans le service X-Ray. Les statistiques relatives au nombre de traces correspondant à chaque critère sont publiées sur Amazon CloudWatch toutes les minutes. Choisir **Afficher la métrique** sur la page **Modifier le groupe** ouvre la CloudWatch console sur la page **Métrique**. Pour plus d'informations sur l'utilisation des CloudWatch métriques, consultez la section [Utilisation d'Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) dans le *guide de CloudWatch l'utilisateur Amazon*.
------
#### [ CloudWatch console ]
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Paramètres** dans le volet de navigation de gauche.
1. Choisissez **Afficher les paramètres** sous **Groupes** dans la section **X-Ray Traces**.
1. Choisissez un groupe dans la section **Groupes**, puis sélectionnez **Modifier**.
1. Sur la page **Modifier le groupe**, choisissez **Afficher la métrique**.
La page **Metrics** de la CloudWatch console s'ouvre dans un nouvel onglet.
------
#### [ X-Ray console ]
1. Connectez-vous à la console X-Ray AWS Management Console et ouvrez-la [https://console.aws.amazon.com/xray/chez](https://console.aws.amazon.com/xray/home) vous.
1. Ouvrez la page **Groupes** dans le volet de navigation de gauche, puis choisissez le nom du groupe dont vous souhaitez consulter les métriques.
1. Sur la page **Modifier le groupe**, choisissez **Afficher la métrique**.
La page **Metrics** de la CloudWatch console s'ouvre dans un nouvel onglet.
------
# Configuration de règles d'échantillonnage
Vous pouvez utiliser la AWS X-Ray console pour configurer les règles d'échantillonnage pour vos services. Les kits de développement AWS Distro for OpenTelemetry, X-Ray et ceux Services AWS qui prennent en charge le [traçage actif](xray-services.md) avec des configurations d'échantillonnage utilisent des règles d'échantillonnage pour déterminer les demandes à enregistrer.
**Topics**
+ [Configuration de règles d'échantillonnage](#xray-console-config)
+ [Personnalisation des règles d'échantillonnage](#xray-console-custom)
+ [Options de règle d'échantillonnage](#xray-console-sampling-options)
+ [Exemples de règles d'échantillonnage](#xray-console-sampling-examples)
+ [Configuration de votre service afin d'utiliser les règles d'échantillonnage](#xray-console-sampling-service)
+ [Affichage des résultats d'échantillonnage](#xray-console-sampling-results)
+ [Étapes suivantes](#xray-console-sampling-nextsteps)
## Configuration de règles d'échantillonnage
Vous pouvez configurer l'échantillonnage pour les cas d'utilisation suivants :
+ **API Gateway Entrypoint** : API Gateway prend en charge l'échantillonnage et le suivi actif. Pour activer le suivi actif sur une étape d'API, consultez [Support de suivi actif d'Amazon API Gateway pour AWS X-Ray](xray-services-apigateway.md).
+ **AWS AppSync**— AWS AppSync prend en charge l'échantillonnage et le traçage actif. Pour activer le suivi actif des AWS AppSync demandes, consultez la section [Tracing with AWS X-Ray](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html).
+ **AWS Step Functions**— AWS Step Functions prend en charge l'échantillonnage et le traçage actif. Pour activer le suivi actif sur les machines à AWS Step Functions états, consultez la section [X-Ray tracing dans Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html).
+ **Instrument AWS Distro pour OpenTelemetry les plateformes informatiques** : lorsque vous utilisez des plateformes de calcul telles qu'Amazon EC2, Amazon ECS ou AWS Elastic Beanstalk, l'échantillonnage est pris en charge lorsque l'application a été instrumentée avec le dernier SDK AWS Distro for ou OpenTelemetry X-Ray.
## Personnalisation des règles d'échantillonnage
En personnalisant les règles d'échantillonnage, vous pouvez contrôler la quantité de données que vous enregistrez. Vous pouvez également modifier le comportement d'échantillonnage sans modifier ni redéployer votre code. Les règles d'échantillonnage indiquent au AWS Distro for OpenTelemetry (ADOT) ou au SDK X-Ray le nombre de demandes à enregistrer pour un ensemble de critères. Par défaut, le SDK enregistre la première demande chaque seconde, et 5 % des demandes supplémentaires. Une demande par seconde est le *réservoir*. Ceci garantit qu'au moins une trace est enregistrée chaque seconde aussi longtemps que le service traite les demandes. 5 % est la *fréquence* à laquelle les demandes supplémentaires au-delà du réservoir sont échantillonnées.
Vous pouvez configurer le SDK X-Ray pour lire les règles d'échantillonnage à partir d'un document JSON que vous incluez dans votre code. Cependant, lorsque vous exécutez plusieurs instances de votre service, chaque instance exécute l'échantillonnage de manière indépendante. Ceci entraîne une augmentation du pourcentage global des demandes échantillonnées, car les réservoirs de toute les instances sont effectivement additionnés. En outre, pour mettre à jour les règles d'échantillonnage locales, vous devez redéployer votre code.
En définissant des règles d'échantillonnage dans la console X-Ray et en [configurant le SDK](#xray-console-sampling-service) pour lire les règles du service X-Ray, vous pouvez éviter ces deux problèmes. Le service gère le réservoir pour chaque règle et attribue les quotas à chaque instance de votre service pour distribuer le réservoir de façon uniforme, en fonction du nombre d'instances qui sont en cours d'exécution. La limite de réservoir est calculée selon les règles que vous avez définies. Les règles étant configurées dans le service, vous pouvez les gérer sans effectuer de déploiements supplémentaires.
**Note**
Lors de la configuration des règles d'échantillonnage, il est essentiel de comprendre que l'échantillonnage par rayons X est « basé sur les parents ». Cela signifie que la décision d'échantillonnage n'est prise qu'une seule fois, généralement par le premier X-Ray-enabled service qui traite la demande (le service « racine »).
Si un service en aval reçoit une demande pour laquelle un parent en amont a déjà pris une décision d'échantillonnage, il honorera cette décision indépendamment de ses propres règles d'échantillonnage correspondantes.
Quand les règles s'appliquent : Vos règles d'échantillonnage personnalisées ne s'appliquent qu'aux services pour lesquels aucune décision d'échantillonnage n'a encore été prise. Cela s'applique généralement à :
Le point d'entrée de votre application (par exemple, une API Gateway, un Load Balancer ou le premier microservice instrumenté).
Des processus ou des travailleurs asynchrones qui démarrent une toute nouvelle trace.
Écueil courant : si vous créez une règle d'échantillonnage stricte pour le « service B », mais que le « service B » est toujours appelé par « service A », votre règle pour le service B ne sera probablement jamais appliquée car elle suit simplement la décision prise par le service A. Pour modifier l'échantillonnage des traces pour ce flux de travail, vous devez configurer la règle d'échantillonnage pour le service racine (service A).
**Note**
X-Ray applique les règles d'échantillonnage dans la mesure du possible et, dans certains cas, le taux d'échantillonnage effectif peut ne pas correspondre exactement aux règles d'échantillonnage configurées. Cependant, au fil du temps, le nombre de demandes échantillonnées devrait être proche du pourcentage configuré.
Vous pouvez désormais configurer les règles d'échantillonnage X-Ray depuis la CloudWatch console Amazon.
**Pour configurer les règles d'échantillonnage dans la CloudWatch console**
1. Connectez-vous à la CloudWatch console AWS Management Console et ouvrez-la à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Choisissez **Paramètres** dans le volet de navigation de gauche, sous **Configuration**.
1. Choisissez **Afficher les paramètres** sous **Règles d'échantillonnage** dans la section **X-Ray Traces**.
1. Pour créer une règle, choisissez **Create sampling rule (Créer une règle d’échantillonnage)**.
Pour modifier une règle, choisissez-en une, puis cliquez sur **Modifier** pour la modifier.
Pour supprimer une règle, choisissez-en une, puis cliquez **sur Supprimer** pour la supprimer.
## Options de règle d'échantillonnage
Les options suivantes sont disponibles pour chaque règle. Les valeurs de chaîne peuvent comporter des caractères génériques correspondant à un seul caractère (`?`) ou à zéro caractère ou plus (`*`).
**Options de règle d'échantillonnage**
+ **Nom de la règle** (chaîne) : nom unique de la règle.
+ **Priorité** (entier compris entre 1 et 9999) : priorité de la règle d'échantillonnage. Les services évaluent les règles dans l’ordre croissant de priorité, et prennent une décision d’échantillonnage avec la première règle correspondante.
+ **Réservoir** (entier non négatif) — Nombre fixe de demandes correspondantes à l'instrument par seconde, avant l'application du taux fixe. Le réservoir n’est pas utilisé directement par les services, mais s’applique à tous les services qui utilisent la règle collectivement.
+ **Taux** (entier compris entre 0 et 100) : pourcentage de demandes correspondantes à l'instrument, une fois le réservoir épuisé. Lorsque vous configurez une règle d'échantillonnage dans la console, choisissez un pourcentage compris entre 0 et 100. Lorsque vous configurez une règle d'échantillonnage dans un SDK client à l'aide d'un document JSON, fournissez une valeur en pourcentage comprise entre 0 et 1.
+ **Nom du service** (chaîne) : nom du service instrumenté, tel qu'il apparaît sur la carte de suivi.
+ X-Ray SDK : nom du service que vous configurez sur l'enregistreur.
+ Amazon API Gateway —`api-name/stage`.
+ **Type de service** (chaîne) : type de service tel qu'il apparaît sur la carte de suivi. Pour le SDK X-Ray, définissez le type de service en appliquant le plug-in approprié :
+ `AWS::ElasticBeanstalk::Environment`— Un AWS Elastic Beanstalk environnement (plugin).
+ `AWS::EC2::Instance`— Une EC2 instance Amazon (plugin).
+ `AWS::ECS::Container`— Un conteneur Amazon ECS (plugin).
+ `AWS::EKS::Container`— Un conteneur Amazon EKS (plugin).
+ `AWS::APIGateway::Stage`— Une étape Amazon API Gateway.
+ `AWS::AppSync::GraphQLAPI `— Une demande AWS AppSync d'API.
+ `AWS::StepFunctions::StateMachine`— Une machine AWS Step Functions étatique.
+ **Host** (chaîne) — Le nom d'hôte indiqué dans l'en-tête de l'hôte HTTP.
+ **Méthode HTTP** (chaîne) — Méthode de la requête HTTP.
+ **Chemin de l'URL** (chaîne) — Le chemin URL de la demande.
+ X-Ray SDK : partie du chemin de l'URL de la requête HTTP.
+ **ARN de la ressource** (chaîne) — L'ARN de la AWS ressource exécutant le service.
+ X-Ray SDK — Non pris en charge. Le kit SDK peut uniquement utiliser des règles avec les **ressources ARN** définies sur `*`.
+ Amazon API Gateway — L'ARN du stage.
+ (Facultatif) **Attributs** (clé et valeur) — Attributs de segment connus lorsque la décision d'échantillonnage est prise.
+ X-Ray SDK — Non pris en charge. Le kit SDK ignore les règles qui spécifient les attributs.
+ Amazon API Gateway — En-têtes issus de la requête HTTP d'origine.
+ (Facultatif) **SamplingRateBoost**(objet) — Contrôle le comportement d'amplification de l'échantillonnage induit par des anomalies.
+ MaxRate (entier compris entre 0 et 100) — La fréquence d'échantillonnage maximale (0,0-1,0) X-Ray peut augmenter en cas d'anomalie
+ CooldownWindowMinutes (entier supérieur à 0) — Fenêtre temporelle (minutes) pendant laquelle un seul boost peut être déclenché, empêchant les boosts continus
## Exemples de règles d'échantillonnage
**Example — Règle par défaut sans réservoir et faible taux**
Vous pouvez modifier le réservoir et la fréquence de la règle par défaut. Par défaut, la règle s'applique à toutes les demandes qui ne correspond à aucune autre règle.
+ **Réservoir** : **0**
+ **Taux** : **5** (**0.05**si configuré à l'aide d'un document JSON)
**Example — Règle de débogage pour suivre toutes les demandes relatives à un itinéraire problématique**
Une règle prioritaire est appliquée temporairement pour le débogage.
+ **Nom de la règle** : **DEBUG – history updates**
+ **Priorité** : **1**
+ **Réservoir** : **1**
+ **Taux** : **100** (**1**si configuré à l'aide d'un document JSON)
+ **Nom du service** : **Scorekeep**
+ **Type de service :** **\$1**
+ **Hôte** : **\$1**
+ **Méthode HTTP** : **PUT**
+ **Chemin de l'URL** : **/history/\$1**
+ **ARN de la ressource** : **\$1**
**Example — Taux minimum plus élevé pour POSTs**
+ **Nom de la règle** : **POST minimum**
+ **Priorité** : **100**
+ **Réservoir** : **10**
+ **Taux** : **10** (**.1**si configuré à l'aide d'un document JSON)
+ **Nom du service** : **\$1**
+ **Type de service :** **\$1**
+ **Hôte** : **\$1**
+ **Méthode HTTP** : **POST**
+ **Chemin de l'URL** : **\$1**
+ **ARN de la ressource** : **\$1**
**Example Activez le boost basé sur les anomalies**
Configurez une règle qui déclenche une augmentation de l'échantillonnage allant jusqu'à 50 % en cas d'anomalie, avec un temps de recharge de 10 minutes.
+ **Nom de la règle** : **MyAdaptiveRule**
+ **Priorité** : **100**
+ **Réservoir** : **1**
+ **FixedRate**: **0.0510**
+ **Nom du service** : **\$1**
+ **Type de service :** **\$1**
+ **Hôte** : **\$1**
+ **Méthode HTTP** : **POST**
+ **Chemin de l'URL** : **\$1**
+ **Taux maximum** : **0.5**
+ **cooldownWindowMinutes**: **10**
## Configuration de votre service afin d'utiliser les règles d'échantillonnage
Le SDK AWS Distro for OpenTelemetry (ADOT) et X-Ray nécessite une configuration supplémentaire pour utiliser les règles d'échantillonnage que vous configurez dans la console. Consultez la rubrique de configuration de votre langage pour en savoir plus sur la configuration d'une stratégie d'échantillonnage :
+ Java : [Utilisation de l'échantillonnage à distance X-Ray](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr#using-x-ray-remote-sampling) avec ADOT Java
+ Go : [Configuration de l'échantillonnage](https://aws-otel.github.io/docs/getting-started/go-sdk/manual-instr#configuring-sampling) avec ADOT Go
+ Node.js : [Utilisation de l'échantillonnage à distance X-Ray](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling) avec ADOT JavaScript
+ Python : [Utilisation de l'échantillonnage à distance X-Ray](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr#using-x-ray-remote-sampling) avec ADOT Python
+ Rubis : [Règles d'échantillonnage](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-sampling)
+ .NET : [Utilisation de l'échantillonnage à distance X-Ray](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling) avec ADOT .NET
Pour API Gateway, consultez[Support de suivi actif d'Amazon API Gateway pour AWS X-Ray](xray-services-apigateway.md).
## Affichage des résultats d'échantillonnage
La page **d'échantillonnage** de la console X-Ray affiche des informations détaillées sur la manière dont vos services utilisent chaque règle d'échantillonnage.
La colonne **Trend (Tendance)** montre comment la règle a été utilisé au cours des dernières minutes. Chaque colonne indique les statistiques pour une fenêtre de 10 secondes.
**Échantillonnage des statistiques**
+ **Règle correspondante totale** : nombre de demandes correspondant à cette règle. Ce nombre n'inclut pas les demandes qui pourraient avoir une correspondance avec cette règle, mais celles qui ont en premier une règle de priorité.
+ **Total échantillonné** : nombre de demandes enregistrées.
+ **Échantillonné avec un taux fixe** : nombre de demandes échantillonnées en appliquant le taux fixe de la règle.
+ **Échantillonné avec limite de réservoir** : nombre de demandes échantillonnées à l'aide d'un quota attribué par X-Ray.
+ **Emprunté au réservoir** : nombre de demandes échantillonnées en empruntant auprès du réservoir. La première fois qu'un service fait correspondre une demande à une règle, aucun quota ne lui a encore été attribué par X-Ray. Toutefois, si le réservoir est d'au moins 1, le service emprunte une trace par seconde jusqu'à ce que X-Ray attribue un quota.
Pour plus d'informations sur l'échantillonnage des statistiques et la façon dont les services utilisent les règles d'échantillonnage, consultez [Utilisation de règles d'échantillonnage avec l'API X-Ray](xray-api-sampling.md).
## Étapes suivantes
Vous pouvez utiliser l'API X-Ray pour gérer les règles d'échantillonnage. Avec l'API, vous pouvez créer et mettre à jour les règles par programmation ou en fonction d'une planification, en réponse à des alarmes ou à des notifications. Consultez [Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec l' AWS X-Ray API](xray-api-configuration.md) pour obtenir des instructions et des exemples de règles supplémentaires.
The AWS Distro for OpenTelemetry, X-Ray SDK et utilisez Services AWS également l'API X-Ray pour lire les règles d'échantillonnage, communiquer les résultats d'échantillonnage et obtenir des cibles d'échantillonnage. Les services doivent suivre la fréquence à laquelle ils appliquent chaque règle, évaluer les règles en fonction de leur priorité et emprunter auprès du réservoir lorsqu'une demande correspond à une règle pour laquelle X-Ray n'a pas encore attribué de quota au service. Pour plus de détails sur la façon dont un service utilise l'API pour l'échantillonnage, reportez-vous à la section [Utilisation de règles d'échantillonnage avec l'API X-Ray](xray-api-sampling.md).
Lorsque le AWS Distro for OpenTelemetry ou le SDK X-Ray appellent Sampling APIs, ils utilisent l' CloudWatch agent comme proxy. Si vous utilisez déjà le port TCP 2000, vous pouvez configurer l'agent pour exécuter le proxy sur un autre port. Consultez le [guide d'installation de l'CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) pour plus de détails.
# Configuration de l'échantillonnage adaptatif
L'absence de traces critiques lors de pics d'anomalies peut compliquer l'analyse des causes profondes. Cependant, le maintien de taux d'échantillonnage élevés coûte cher. L'échantillonnage adaptatif X-Ray fournit une visibilité complète des anomalies et contrôle les coûts pendant les opérations normales. Avec l'échantillonnage adaptatif, vous définissez une fréquence d'échantillonnage maximale, et X-Ray s'ajuste automatiquement dans cette limite. X-Ray calcule le boost minimum nécessaire pour capturer les traces d'erreur. Si votre taux de référence capture suffisamment de données, aucune augmentation ne se produit. Vous ne payez pour un échantillonnage supplémentaire qu'en cas de besoin.
Avantages de l'utilisation de l'échantillonnage adaptatif :
+ Visibilité complète des incidents — Obtenez des traces complètes des incidents sans intervention manuelle. X-Ray ajuste automatiquement les taux d'échantillonnage pour capturer les traces d'erreur, puis revient à des taux normaux.
+ Visibilité des causes premières : identifiez toujours la source des problèmes. X-Ray capture les données d'erreur critiques même lorsque l'échantillonnage complet des traces n'est pas déclenché.
+ Optimisation des coûts — De brèves périodes d'échantillonnage (jusqu'à 1 minute) et des périodes de refroidissement automatique évitent le suréchantillonnage. Vous ne payez que pour les données dont vous avez besoin pour diagnostiquer les problèmes.
**Topics**
+ [Plateformes SDKs et plateformes prises en charge](#adaptive-sampling-supported-sdks)
+ [Choisissez votre approche d'échantillonnage adaptatif](#adaptive-sampling-features)
+ [Configuration du SDK local](#local-sdk-configuration)
## Plateformes SDKs et plateformes prises en charge
**SDK pris en charge** — L'échantillonnage adaptatif nécessite la dernière version du SDK ADOT.
**Langage pris en charge** : Java (version [v2.11.5 ou supérieure)](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5)
Votre application doit être instrumentée avec le SDK ADOT pris en charge et exécutée conjointement avec l'Amazon CloudWatch Agent ou le Collector. OpenTelemetry
Par exemple, Amazon EC2, Amazon ECS et Amazon EKS sont des plateformes courantes sur lesquelles AWS Application Signals fournit des conseils pour activer le SDK ADOT et Amazon CloudWatch Agent.
## Choisissez votre approche d'échantillonnage adaptatif
L'échantillonnage adaptatif prend en charge deux approches, Sampling Boost et Anomaly Span Capture. Ils peuvent être appliqués indépendamment ou combinés ensemble.
### Amélioration de l'échantillonnage
L'amplification adaptative de l'échantillonnage est basée sur des règles d'échantillonnage et fonctionne avec le modèle d'échantillonnage basé sur la tête X-Ray existant. L'échantillonnage basé sur la tête signifie que les décisions d'échantillonnage sont prises au niveau du service racine et que l'indicateur d'échantillonnage est transmis en aval à tous les services de la chaîne d'appels.
+ **Boost basé sur des règles** — Le boost est toujours lié à une règle d'échantillonnage X-Ray spécifique. Chaque règle peut définir son propre taux d'augmentation maximal et son propre comportement de refroidissement.
+ **Échantillonnage basé sur la tête** : les décisions d'échantillonnage sont prises au niveau du service racine, et l'indicateur d'échantillonnage est transmis en aval à tous les services de la chaîne d'appels.
+ Géré **par les anomalies — X-Ray** s'appuie sur le SDK pour signaler les statistiques relatives aux anomalies. Lorsque X-Ray détecte des anomalies telles que des erreurs ou une latence élevée, il utilise ces statistiques pour calculer un taux d'augmentation approprié (jusqu'au maximum configuré).
**Signalement d'anomalies**
Chaque service applicatif de la chaîne d'appels peut émettre des statistiques sur les anomalies via le SDK requis :
+ **Service racine** : doit être exécuté sur un SDK et une plate-forme compatibles pour permettre l'augmentation de l'échantillonnage. Si le service root n'est pas pris en charge, aucun boost ne sera effectué.
+ **Services en aval** : les services en aval signalent uniquement les anomalies ; ils ne peuvent pas prendre de décisions d'échantillonnage. Lorsqu'un service en aval exécute un SDK compatible, les anomalies détectées peuvent déclencher une augmentation de l'échantillonnage. Lorsqu'un service en aval n'est pas pris en charge (par exemple, l'exécution d'un ancien SDK), les anomalies sur ce service ne déclenchent pas de boost. Ces services peuvent toujours propager le contexte en aval lorsqu'ils suivent une propagation de contexte standard (comme le contexte de trace et les bagages du W3C). Cela garantit que les services pris SDKs en charge par d'autres services en aval peuvent signaler les anomalies qui déclenchent un boost.
**Améliorez le calendrier et la portée**
+ **Délai de déclenchement** : vous pouvez vous attendre à ce que l'augmentation de l'échantillonnage commence 10 secondes seulement après la détection d'une anomalie par X-Ray.
+ **Période d'amplification** — Une fois que X-Ray a déclenché un boost, celui-ci dure jusqu'à 1 minute avant de revenir à la fréquence d'échantillonnage de base.
+ **Accélérer le temps de refroidissement** — Une fois qu'un boost a été activé, X-Ray n'en déclenchera pas un autre pour la même règle tant que la fenêtre de refroidissement n'est pas passée.
Par exemple, lorsque vous réglez sur `cooldown` 10 minutes, une fois qu'un boost est terminé, aucun nouveau boost ne peut être déclenché avant la fenêtre de 10 minutes suivante.
Cas particulier : lorsque vous réglez `cooldown` sur 1 minute, et comme un boost lui-même peut durer jusqu'à 1 minute, les boosts peuvent effectivement être déclenchés en continu si l'anomalie persiste.
**Note**
Utilisez des plateformes SDKs et des plateformes prises en charge pour votre service racine. Sampling Boost ne fonctionne qu'avec SDKs les plateformes prises en charge. Bien que le boost d'échantillonnage ait une forte probabilité de capturer des traces d'anomalies, il se peut qu'il ne capture pas toutes les traces d'anomalie.
**Améliorez la visibilité**
Lorsqu'une règle d'échantillonnage est configurée avec un boost d'échantillonnage adaptatif, X-Ray émet automatiquement des métriques automatiques qui vous permettent de surveiller l'activité du boost.
+ **Nom de la métrique** — `SamplingRate`
+ **Dimension** — `RuleName` (définie sur le nom réel de la règle)
Chaque règle `SamplingRateBoost` activée publiera son taux d'échantillonnage effectif, y compris le taux de référence et toute augmentation temporaire. Cela vous permet de :
+ Suivez le moment où les boosts sont déclenchés
+ Surveillez le taux d'échantillonnage effectif pour chaque règle
+ Corrélez les boosters avec les anomalies de l'application (telles que les pics d'erreur ou les événements de latence)
Vous pouvez consulter ces statistiques dans **Amazon CloudWatch Metrics, sous l'espace de noms AWS/X-Ray. La valeur métrique est un nombre à virgule flottante compris entre 0 et 1, représentant le taux d'échantillonnage effectif**.
**Configurer l'amplification de l'échantillonnage à l'aide des règles d'échantillonnage X-Ray**
Vous pouvez activer l'échantillonnage adaptatif directement dans vos règles d'échantillonnage X-Ray existantes en ajoutant un nouveau `SamplingRateBoost` champ. Pour plus d'informations, consultez la section [Personnalisation des règles d'échantillonnage](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom). Cela fournit un moyen centralisé d'activer l'échantillonnage adaptatif sans modifier le code de l'application ni appliquer le déploiement de l'application. Lorsque vous activez l'échantillonnage adaptatif, X-Ray augmente automatiquement l'échantillonnage en cas d'anomalies telles que les pics d'erreur ou les valeurs aberrantes de latence, tout en maintenant les taux d'échantillonnage dans les limites de votre maximum configuré. `SamplingRateBoost`peut être appliqué à n'importe quelle règle d'échantillonnage personnalisée, à l'exception de la règle `Default` d'échantillonnage.
Le `SamplingRateBoost` champ définit la limite supérieure et le comportement de l'échantillonnage basé sur les anomalies.
```
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
```
`MaxRate`Définit le taux d'échantillonnage maximal que X-Ray appliquera lorsqu'il détectera des anomalies. La plage de valeurs est `0.0` de`1.0`. Par exemple, `"MaxRate": 0.25` permet à l'échantillonnage d'augmenter jusqu'à 25 % des demandes pendant une fenêtre d'anomalie. X-Ray détermine le taux approprié entre votre valeur de référence et le maximum, en fonction de l'activité anormale.
Il `CooldownWindowMinutes` définit la fenêtre temporelle (en minutes) dans laquelle une seule augmentation de la fréquence d'échantillonnage peut être déclenchée. Après un boost, aucun autre boost n'est autorisé jusqu'à la fenêtre suivante. Le type de valeur est *entier (minutes)*.
**Exemple de règle avec échantillonnage adaptatif**
```
{
"RuleName": "MyAdaptiveRule",
"Priority": 1,
"ReservoirSize": 1,
"FixedRate": 0.05,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
}
```
Dans cet exemple, l'échantillonnage de référence est de 5 % (`FixedRate: 0.05`). Lors d'anomalies, X-Ray peut augmenter l'échantillonnage jusqu'à 25 % (`MaxRate: 0.25`). Boostez uniquement une fois toutes les 10 minutes.
**Configuration des conditions d'anomalie**
Lorsqu'aucune configuration de condition d'anomalie n'est fournie, le SDK ADOT utilise les **codes d'erreur HTTP 5xx** comme condition d'anomalie par défaut pour déclencher l'augmentation de l'échantillonnage.
Vous pouvez également affiner les conditions d'anomalie localement dans le SDK ADOT pris en charge à l'aide de variables d'environnement. Pour de plus amples informations, veuillez consulter [Configuration du SDK local](#local-sdk-configuration).
### L'anomalie s'étend sur toute la durée de capture
La capture de la plage d'anomalies garantit que les plages critiques représentant des anomalies sont toujours enregistrées, même si la trace complète n'est pas échantillonnée. Cette fonctionnalité complète l'amélioration de l'échantillonnage en se concentrant sur la capture de l'anomalie elle-même, plutôt que sur l'augmentation de l'échantillonnage pour les futures traces.
Lorsque le SDK ADOT détecte une anomalie, il émet cette plage immédiatement, quelle que soit la décision d'échantillonnage. Étant donné que le SDK émet uniquement des intervalles liés à l'anomalie, ces traces sont des traces partielles et non des transactions complètes. end-to-end
Une fois que le SDK ADOT détecte une plage d'anomalies, il tente d'émettre autant de plages que possible à partir de la même trace. Toutes les plages émises sous cette fonctionnalité sont étiquetées avec l'attribut,`aws.trace.flag.sampled = 0`. Cela vous permet de distinguer facilement les traces partielles (capture des anomalies) des traces complètes (échantillonnage normal) lors de la recherche et de l'analyse des transactions.
Nous vous recommandons d'intégrer [Transaction Search](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html) pour consulter et interroger des traces partielles. L'exemple suivant montre une page Service dans la console [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). ServiceC est configuré avec la capture de l'intervalle d'anomalie et fait partie d'une chaîne d'appels où l'augmentation de l'échantillonnage s'applique. Cette configuration génère des traces complètes et partielles. Vous pouvez utiliser `aws.trace.flag.sampled` cet attribut pour distinguer les types de traces.
![\[L'anomalie s'étend sur toute la durée de capture\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/adaptive-sampling.png)
La capture des plages d'anomalies ne peut être activée ou personnalisée que via le. [Configuration du SDK local](#local-sdk-configuration)
## Configuration du SDK local
Vous pouvez configurer les fonctionnalités d'échantillonnage adaptatif dans le SDK ADOT en fournissant une configuration YAML via une variable d'environnement. La configuration locale permet un contrôle précis des conditions d'anomalie et des seuils.
Cela est nécessaire pour la *capture de la plage d'anomalies* et facultatif pour personnaliser les conditions d'amplification de l'*échantillonnage*. Voici un exemple de configuration :
```
version: 1.0
anomalyConditions:
- errorCodeRegex: "^5\\d\\d$"
usage: both
- operations:
- "/api"
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
usage: sampling-boost
- highLatencyMs: 1000
usage: anomaly-span-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 1
```
Les définitions des champs sont indiquées ci-dessous :
+ `version`— Version du schéma pour le fichier de configuration
+ `anomalyConditions`— Définit les conditions dans lesquelles les anomalies sont détectées et comment elles sont utilisées
+ `errorCodeRegex`— Expression régulière définissant quels codes d'état HTTP sont considérés comme des anomalies
+ `operations`— Liste des opérations ou des points finaux auxquels s'applique la condition
+ `highLatencyMs`— Seuil de latence (en millisecondes) au-dessus duquel les intervalles sont considérés comme des anomalies
+ `usage`— Définit à quelle fonctionnalité la condition s'applique :
+ `both`— S'applique à l'**augmentation de l'échantillonnage** et à la **capture de la plage d'anomalies** (par défaut si l'utilisation n'est pas spécifiée)
+ `sampling-boost`— Utilisé uniquement pour déclencher des amplifications d'échantillonnage
+ `anomaly-span-capture`— Utilisé uniquement pour la capture de l'étendue des anomalies
+ `anomalyCaptureLimit`— Définit les limites du nombre de traces présentant des plages d'anomalies émises.
`anomalyTracesPerSecond`— Nombre maximal de traces présentant des intervalles d'anomalie capturés par seconde, afin d'éviter un volume d'intervalle excessif (la valeur par défaut est 1 en l' anomalyCaptureLimit absence).
**Note**
`AnomalyConditions`**remplace** la condition d'anomalie par défaut pour l'augmentation de l'échantillonnage (HTTP 5xx). Si vous souhaitez conserver la condition par défaut lors de l'utilisation de la configuration locale, vous devez l'inclure explicitement dans n'importe quel élément de`AnomalyConditions`.
Pour chaque `anomalyConditions` article :
Lorsque le `operations` champ est **omis**, la condition s'applique à **toutes les opérations** (niveau de service)
Lorsque le `operations` champ est présent mais défini sur une **liste vide**, la condition s'applique à l'**absence d'opérations**, ce qui rend cet élément non opérationnel
Lorsque `errorCodeRegex` les deux `highLatencyMs` sont omis, la condition n'a aucun critère d'anomalie à évaluer, ce qui rend cet élément non opérationnel
Relations logiques :
Entre les éléments`anomalyConditions`, la relation est **OR**.
Au sein d'un même élément, plusieurs champs (par exemple, `errorCodeRegex` et`highLatencyMs`) sont combinés avec **AND**.
Par exemple :
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
```
Cette condition signifie que le **code d'état correspond à 429 ou 5xx ET que la latence est supérieure ou égale à 300 ms.**
### Appliquer la configuration locale au SDK ADOT
Vous pouvez appliquer la configuration locale au SDK ADOT en définissant la variable d'environnement. `AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG` La valeur doit être un document YAML valide (en ligne ou imbriqué).
Par exemple, Amazon EC2 et Amazon ECS, définissez directement la variable d'environnement :
```
AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"
```
Pour Amazon EKS, définissez la variable d'environnement dans la spécification du pod en tant que YAML imbriqué :
```
apiVersion: v1
kind: Pod
metadata:
name: adot-sample
spec:
containers:
- name: adot-app
image: my-app:latest
env:
- name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
value: |
version: 1.0
anomalyConditions:
- errorCodeRegex: "^500$"
usage: sampling-boost
- errorCodeRegex: "^501$"
usage: anomaly-trace-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 10
```
# Liens profonds sur console
Vous pouvez utiliser des itinéraires et des requêtes pour créer des liens profonds vers des traces spécifiques, ou des vues filtrées des traces et de la carte des traces.
**Pages de console**
+ Page d'accueil — [xray/home\$1/welcome](https://console.aws.amazon.com/xray/home#/welcome)
+ Commencer [xray/home\$1/getting—](https://console.aws.amazon.com/xray/home#/getting-started) démarrer
+ Tracer la carte — [xray/home\$1/service-map](https://console.aws.amazon.com/xray/home#/service-map)
+ Des traces — [xray/home\$1/traces](https://console.aws.amazon.com/xray/home#/traces)
## Suivis
Vous pouvez générer des liens pour des vues chronologiques, brutes et de cartographie de suivis individuels.
**Tracez la chronologie** — `xray/home#/traces/trace-id`
Données de **trace brutes** — `xray/home#/traces/trace-id/raw`
**Example — données de trace brutes**
```
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
```
## Expressions de filtrage
Lien vers une liste filtrée de suivis.
**Affichage des traces filtrées** — `xray/home#/traces?filter=filter-expression`
**Example — expression de filtre**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar"
```
**Example — expression de filtre (encodée en URL)**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22
```
Pour plus d'informations sur les expressions de filtrage, consultez [Utilisation d'expressions de filtre](xray-console-filters.md).
## Plage horaire
Spécifiez une durée ou une heure de début et de fin au format ISO86 01. Les plages horaires sont exprimées en UTC et peuvent durer jusqu'à 6 heures.
**Durée** — `xray/home#/page?timeRange=range-in-minutes`
**Example — carte de trace de la dernière heure**
```
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
```
**Heure de début et de fin** — `xray/home#/page?timeRange=start~end`
**Example — plage de temps précise en secondes**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00:00~2023-7-01T22:00:00
```
**Example — plage de temps précise en minutes**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00~2023-7-01T22:00
```
## Région
Spécifiez un lien Région AWS vers les pages de cette région. Si vous n'indiquez pas de région, la console vous redirige vers la dernière région visitée.
**Région** — `xray/home?region=region#/page`
**Example — carte de traçage dans l'ouest des États-Unis (Oregon) (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map
```
Lorsque vous incluez une région avec d'autres paramètres de requête, la requête de région précède le hachage et les X-Ray-specific requêtes suivent le nom de page.
**Example — carte de suivi de la dernière heure dans l'ouest des États-Unis (Oregon) (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
```
## Combiné
**Example — traces récentes avec filtre de durée**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208
```
**Sortie**
+ Page — Traces
+ Plage de temps — 15 dernières minutes
+ Filtre — durée >= 5 ET durée <= 8
# Utiliser l'API X-Ray
Si le SDK X-Ray ne prend pas en charge votre langage de programmation, vous pouvez utiliser le X-Ray APIs directement ou le AWS Command Line Interface (AWS CLI) pour appeler les commandes de l'API X-Ray. Suivez les instructions suivantes pour choisir la manière dont vous interagissez avec l'API :
+ Utilisez le AWS CLI pour une syntaxe plus simple à l'aide de commandes préformatées ou d'options dans votre requête.
+ Utilisez directement l'API X-Ray pour une flexibilité et une personnalisation maximales des demandes que vous envoyez à X-Ray.
Si vous utilisez directement l'[API X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) au lieu du AWS CLI, vous devez paramétrer votre demande dans le format de données approprié et vous devrez peut-être également configurer l'authentification et la gestion des erreurs.
Le schéma suivant indique comment choisir le mode d'interaction avec l'API X-Ray :
![\[X-Ray affiche des informations détaillées sur les demandes de candidature.\]](http://docs.aws.amazon.com/fr_fr/xray/latest/devguide/images/api-vs-cli.png)
Utilisez l'API X-Ray pour envoyer les données de suivi directement à X-Ray. L'API X-Ray prend en charge toutes les fonctions disponibles dans le SDK X-Ray, y compris les actions courantes suivantes :
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)— Télécharge les documents segmentés sur X-Ray.
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html)— Récupère une liste de traces dans une liste de traces IDs. Chaque trace récupérée est une collection de documents segmentés provenant d'une seule demande.
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)— Récupère IDs et annote les traces. Vous pouvez spécifier a `FilterExpression` pour récupérer un sous-ensemble de résumés de traces.
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html)— Récupère un graphique de service pour un ID de trace spécifique.
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)— Récupère un JSON document formaté qui décrit les services qui traitent les demandes entrantes et appellent les demandes en aval.
Vous pouvez également utiliser le AWS Command Line Interface (AWS CLI) dans le code de votre application pour interagir par programmation avec X-Ray. Il AWS CLI prend en charge toutes les fonctions disponibles dans le SDK X-Ray, y compris celles pour les autres Services AWS. Les fonctions suivantes sont des versions des opérations d'API répertoriées précédemment dans un format plus simple :
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html)— Télécharge les documents segmentés sur X-Ray.
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html)— Récupère une liste de traces dans une liste de traces IDs. Chaque trace récupérée est une collection de documents segmentés provenant d'une seule demande.
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html)— Récupère IDs et annote les traces. Vous pouvez spécifier a `FilterExpression` pour récupérer un sous-ensemble de résumés de traces.
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html)— Récupère un graphique de service pour un ID de trace spécifique.
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html)— Récupère un document `JSON` formaté qui décrit les services qui traitent les demandes entrantes et appellent les demandes en aval.
Pour commencer, vous devez installer le [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)pour votre système d'exploitation. AWS soutient Linux, macOS and Windows systèmes d'exploitation. Pour plus d'informations sur la liste des commandes X-Ray, consultez le [guide AWS CLI Command Reference pour X-Ray](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html).
**Topics**
+ [Utilisation de l' AWS X-Ray API avec la AWS CLI](xray-api-tutorial.md)
+ [Envoi de données de suivi à AWS X-Ray](xray-api-sendingdata.md)
+ [Obtenir des données à partir de AWS X-Ray](xray-api-gettingdata.md)
+ [Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec l' AWS X-Ray API](xray-api-configuration.md)
+ [Utilisation de règles d'échantillonnage avec l'API X-Ray](xray-api-sampling.md)
+ [AWS X-Ray documents segmentés](xray-api-segmentdocuments.md)
# Utilisation de l' AWS X-Ray API avec la AWS CLI
La AWS CLI vous permet d'accéder directement au service X-Ray et d'utiliser le même APIs que celui utilisé par la console X-Ray pour récupérer le graphe du service et les données de trace brutes. L'exemple d'application inclut des scripts qui montrent comment les utiliser APIs avec la AWS CLI.
## Prérequis
Ce didacticiel utilise l'exemple d'application Scorekeep et inclut des scripts pour générer des données de suivi et une cartographie des services. Suivez les instructions du [didacticiel de mise en route](xray-gettingstarted.md) pour lancer l'application.
Ce didacticiel utilise le AWS CLI pour montrer l'utilisation de base de l'API X-Ray. La AWS CLI, [disponible pour Windows, Linux et OS-X](https://docs.aws.amazon.com/cli/latest/userguide/installing.html), fournit un accès en ligne de commande au public APIs pour tous. Services AWS
**Note**
Vous devez vérifier que vous êtes AWS CLI configuré dans la même région que celle dans laquelle votre exemple d'application Scorekeep a été créé.
Les scripts inclus pour tester l'exemple d'application utilisent `cURL` pour envoyer le trafic vers l'API et `jq` pour analyser la sortie. Vous pouvez télécharger l' exécutable à`jq` partir de [stedolan.github.io](https://stedolan.github.io/jq/) et l' exécutable `curl` à partir de [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html). La plupart des installations Linux et OS X incluent cURL.
## Génération de données de suivi
L'application web continue de générer du trafic vers l'API à intervalles réguliers de quelques secondes pendant que le jeu est en cours, mais elle génère uniquement un type de demande. Utilisez le script `test-api.sh` pour exécuter des scénarios de bout en bout et générer plusieurs autres données de suivi pendant que vous testez l'API.
**Pour utiliser le script `test-api.sh`**
1. Ouvrez la [console Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Accédez à la [console de gestion](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) de votre environnement.
1. Copiez l'**URL** de l'environnement à partir de l'en-tête de page.
1. Ouvrez `bin/test-api.sh` et remplacez la valeur pour l'API par l'URL de votre environnement.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. Exécutez le script pour générer du trafic vers l'API.
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating users,
session,
game,
configuring game,
playing game,
ending game,
game complete.
{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
```
## Utiliser l'API X-Ray
La AWS CLI fournit des commandes pour toutes les actions d'API proposées par X-Ray, y compris [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)et [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Consultez le document [Référence d'API AWS X-Ray](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) pour plus d'informations sur toutes les actions prises en charge et les types de données utilisés.
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
Le script récupère un graphique de services pour les 10 dernières minutes.
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
Le script récupère les URLs traces générées il y a une à deux minutes.
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
Le script récupère les suivis entiers générés il y a une et deux minutes.
```
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
```
## Nettoyage
Mettez fin à votre environnement Elastic Beanstalk pour arrêter les instances EC2 Amazon, les tables DynamoDB et les autres ressources.
**Pour arrêter votre environnement Elastic Beanstalk**
1. Ouvrez la [console Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk).
1. Accédez à la [console de gestion](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) de votre environnement.
1. Choisissez **Actions**.
1. Choisissez **Terminate Environment (Terminer l'environnement)**.
1. Sélectionnez **Résilier**.
Les données de suivi sont automatiquement supprimées de X-Ray au bout de 30 jours.
# Envoi de données de suivi à AWS X-Ray
Vous pouvez envoyer des données de suivi à X-Ray sous forme de documents segmentés. Un document de segment est une chaîne au format JSON contenant des informations sur les tâches effectuées par votre application pour répondre à une demande. Votre application peut enregistrer des données sur les tâches qu'elle effectue elle-même dans les segments, ou sur celles qui font appel à des ressources et services en aval dans les sous-segments.
Les segments enregistrent les informations sur les tâches effectuées par votre application. Au minimum, un segment enregistre le temps passé sur une tâche, un nom, IDs etc. L'ID de suivi permet de suivre la demande lors de son cheminement entre les différents services. L'ID de segment permet de suivre les tâches effectuées par un service en particulier pour répondre à la demande.
**Example Segment terminé minimal**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Lors de la réception d'une demande, vous pouvez envoyer un segment en cours comme espace réservé en attendant la réponse.
**Example Segment en cours**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
Vous pouvez envoyer des segments à X-Ray directement [`PutTraceSegments`](#xray-api-segments), avec ou [via le daemon X-Ray](#xray-api-daemon).
La plupart des applications appellent d'autres services ou accèdent à des ressources à l'aide du AWS SDK. Enregistrez les informations relatives aux appels en aval dans des *sous-segments*. X-Ray utilise des sous-segments pour identifier les services en aval qui n'envoient pas de segments et créer des entrées pour eux sur le graphique des services.
Un sous-segment peut être intégré dans un document de segment entier, ou envoyé séparément. Envoyez des sous-segments séparément pour suivre de manière asynchrone les appels en aval pour les demandes de longue durée ou pour éviter de dépasser la taille maximale du document de segment (64 kB).
**Example Sous-segment**
Un sous-segment possède un `type` de `subsegment` et un `parent_id` qui identifie le segment parent.
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
Pour plus d'informations sur les champs et les valeurs que vous pouvez inclure dans les segments et les sous-segments, consultez [AWS X-Ray documents segmentés](xray-api-segmentdocuments.md).
**Topics**
+ [Génération d'une trace IDs](#xray-api-traceids)
+ [En utilisant PutTraceSegments](#xray-api-segments)
+ [Envoi de documents segmentés au daemon X-Ray](#xray-api-daemon)
## Génération d'une trace IDs
Pour envoyer des données à X-Ray, vous devez générer un identifiant de trace unique pour chaque demande.
**Format d'identification X-Ray Trace**
Un X-Ray `trace_id` est composé de trois chiffres séparés par des tirets. Par exemple, `1-58406520-a006649127e371903a2de979`. Cela inclut notamment les éléments suivants :
+ Le numéro de version, qui est`1`.
+ L'heure de la demande d'origine sous Unix Epoch Time en utilisant **8 chiffres hexadécimaux**.
Par exemple, le 1er décembre 2016 à 10 h 00 PST est exprimé en `1480615200` secondes ou `58406520` en chiffres hexadécimaux.
+ Identifiant 96 bits unique au monde pour la trace en **24 chiffres hexadécimaux**.
**Note**
X-Ray prend désormais en charge IDs les traces créées à OpenTelemetry l'aide de tout autre framework conforme à la spécification [W3C Trace Context](https://www.w3.org/TR/trace-context/). Un ID de trace W3C doit être formaté au format X-Ray Trace ID lors de son envoi à X-Ray. Par exemple, l'ID de trace du W3C `4efaaf4d1e8720b39541901950019ee5` doit être formaté comme `1-4efaaf4d-1e8720b39541901950019ee5` lorsqu'il est envoyé à X-Ray. X-Ray Trace IDs inclut l'horodatage de la demande d'origine dans Unix Epoch Time, mais cela n'est pas obligatoire lors de l'envoi de la trace W3C au format IDs X-Ray.
Vous pouvez écrire un script pour générer un tracé X-Ray à des IDs fins de test. Voici deux exemples :
**Python**
```
import time
import os
import binascii
START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
```
**Bash**
```
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
```
Consultez l'exemple d'application Scorekeep pour découvrir les scripts qui créent des traces IDs et envoient des segments au daemon X-Ray.
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash — [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## En utilisant PutTraceSegments
Vous pouvez charger des documents relatifs aux segments avec l'API [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html). L'API possède un seul paramètre, `TraceSegmentDocuments`, qui accepte une liste de documents de segment au format JSON.
Avec l'AWS CLI, utilisez la `aws xray put-trace-segments` commande pour envoyer les documents de segment directement à X-Ray.
```
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
"UnprocessedTraceSegments": []
}
```
**Note**
Le processeur de commandes Windows et Windows PowerShell ont des exigences différentes en matière de guillemets et d'échappements aux guillemets dans les chaînes JSON. Pour plus d'informations, consultez [Indication des chaînes entre guillemets](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings) dans le Guide de l'utilisateur de l' AWS CLI .
La sortie répertorie tous les segments dont le traitement a échoué. Par exemple, si la date qui figure dans l'ID de suivi remonte à trop loin, une erreur similaire à la suivante s'affiche :
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
Vous pouvez indiquer plusieurs documents de segment à la suite, en les séparant par des espaces.
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## Envoi de documents segmentés au daemon X-Ray
Au lieu d'envoyer des documents de segment à l'API X-Ray, vous pouvez envoyer des segments et des sous-segments au daemon X-Ray, qui les mettra en mémoire tampon et les téléchargera par lots vers l'API X-Ray. Le SDK X-Ray envoie des documents segmentés au daemon afin d'éviter de passer des appels directs à AWS celui-ci.
**Note**
Consultez [Exécution du daemon X-Ray en local](xray-daemon-local.md) pour obtenir des instructions sur l'exécution du démon.
Envoyez le segment au format JSON sur le port UDP 2000, en ajoutant en préfixe l'en-tête du démon, `{"format": "json", "version": 1}\n`
```
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
```
Sous Linux, vous pouvez envoyer des documents de segment au démon depuis un terminal Bash. Enregistrez l'en-tête et le document de segment comme fichier texte et placez-les dans `/dev/udp` avec `cat`.
```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```
**Example segment.txt**
```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```
Consultez le [journal du démon](xray-daemon.md#xray-daemon-logging) pour vérifier qu'il a envoyé le segment à X-Ray.
```
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
```
# Obtenir des données à partir de AWS X-Ray
AWS X-Ray traite les données de suivi que vous lui envoyez pour générer des traces complètes, des résumés de traces et des graphiques de service au format JSON. Vous pouvez récupérer les données générées directement depuis l'API à l'aide de la AWS CLI.
**Topics**
+ [Récupération du graphique de services](#xray-api-servicegraph)
+ [Récupération du graphique des services par groupe](#xray-api-servicegraphgroup)
+ [Récupération des suivis](#xray-api-traces)
+ [Extraction et affinage de l'analyse de la cause racine](#xray-api-analytics)
## Récupération du graphique de services
Vous pouvez utiliser l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) pour récupérer le graphique de services JSON. L'API nécessite une heure de début et de fin, que vous pouvez calculer à partir d'un terminal Linux avec la commande `date`.
```
$ date +%s
1499394617
```
`date +%s` détermine une date en quelques secondes. Utilisez cette valeur comme une heure de fin et déduisez le temps de traitement pour obtenir une heure de début.
**Example Script permettant de récupérer un graphique de services pour les 10 dernières minutes**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
L'exemple suivant montre un graphe de service avec 4 nœuds, dont un nœud client, une EC2 instance, une table DynamoDB et une rubrique Amazon SNS.
**Example GetServiceGraph sortie**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## Récupération du graphique des services par groupe
Pour appeler un graphique des services en fonction du contenu d'un groupe, incluez un élément `groupName` ou `groupARN`. L'exemple suivant illustre un appel de graphique des services à un groupe nommé Example1.
**Example Script permettant de récupérer un graphique des services par nom pour le groupe Example1**
```
aws xray get-service-graph --group-name "Example1"
```
## Récupération des suivis
Vous pouvez utiliser l'API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) pour obtenir la liste des synthèses de suivi. Les résumés de traces incluent des informations que vous pouvez utiliser pour identifier les traces que vous souhaitez télécharger dans leur intégralité, notamment les annotations, les informations de demande et de réponse, et. IDs
Il y a deux indicateurs `TimeRangeType` disponibles lors de l'appel de `aws xray get-trace-summaries` :
+ **TraceId**— La `GetTraceSummaries` recherche par défaut utilise l'heure de TraceID et renvoie les traces démarrées dans la plage calculée`[start_time, end_time)`. Cette plage d'horodatages est calculée en fonction du codage de l'horodatage dans le TraceId, ou peut être définie manuellement.
+ **Durée de l'événement** : pour rechercher les événements tels qu'ils se produisent au fil du temps, AWS X-Ray permet de rechercher des traces à l'aide des horodatages des événements. L'heure de l'événement renvoie les traces actives au cours de la plage `[start_time, end_time)`, quel que soit le moment où la trace a commencé.
Utilisez la commande `aws xray get-trace-summaries` pour obtenir la liste des synthèses de suivi. Les commandes suivantes permettent d'obtenir une liste de résumés de traces réalisés il y a 1 à 2 minutes en utilisant l' TraceIdheure par défaut.
**Example Script permettant d'obtenir des synthèses de suivi**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries sortie**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
Utilisez l'ID de suivi de la sortie pour obtenir un suivi complet avec l'API [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html).
**Example BatchGetTraces commande**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces sortie**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
Le suivi complet inclut un document pour chaque segment, compilé à partir de l'ensemble des documents de segments reçus pour le même ID de suivi. Ces documents ne représentent pas les données telles qu'elles ont été envoyées à X-Ray par votre application. Ils représentent plutôt les documents traités générés par le service X-Ray. X-Ray crée le document de trace complet en compilant les documents de segment envoyés par votre application et en supprimant les données non conformes au [schéma du document de segment](xray-api-segmentdocuments.md).
X-Ray crée également des *segments déduits* pour les appels en aval vers des services qui n'envoient pas de segments eux-mêmes. Par exemple, lorsque vous appelez DynamoDB avec un client instrumenté, le SDK X-Ray enregistre un sous-segment contenant des détails sur l'appel du point de vue de celui-ci. Cependant, DynamoDB n'envoie pas de segment correspondant. X-Ray utilise les informations du sous-segment pour créer un segment inféré représentant la ressource DynamoDB dans la carte de trace, et l'ajoute au document de trace.
Pour obtenir plusieurs traces à partir de l'API, vous avez besoin d'une liste de traces IDs, que vous pouvez extraire du résultat à l'`get-trace-summaries`aide d'une [AWS CLI requête](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter). Redirigez la liste vers l'entrée de `batch-get-traces` pour obtenir des traces complètes pour une période spécifique.
**Example Script permettant d'obtenir les suivis complets pour une période d'une minute**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
## Extraction et affinage de l'analyse de la cause racine
Lors de la génération d'un résumé de trace avec l'[GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html), les résumés de suivi partiels peuvent être réutilisés dans leur format JSON pour créer une expression de filtre affinée basée sur les causes premières. Consultez les exemples ci-dessous pour connaître les étapes d’affinage.
**Example Exemple GetTraceSummaries de sortie : section sur la cause première du temps de réponse**
```
{
"Services": [
{
"Name": "GetWeatherData",
"Names": ["GetWeatherData"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetWeatherData",
"Coverage": 1.0,
'Remote": false
},
{
"Name": "get_temperature",
"Coverage": 0.8,
"Remote": false
}
]
},
{
"Name": "GetTemperature",
"Names": ["GetTemperature"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetTemperature",
"Coverage": 0.7,
"Remote": false
}
]
}
]
}
```
En modifiant la sortie ci-dessus ou en lui appliquant des omissions, ce fichier JSON peut devenir un filtre pour les entités de cause racine correspondantes. Pour chaque champ de cette sortie JSON, les correspondances de candidat doivent être exactes pour que le suivi soit renvoyé. Les champs supprimés deviennent des valeurs de caractères génériques, ce qui correspond à un format compatible avec la structure de requête de l’expression de filtre.
**Example Cause racine des temps de réponse reformatée**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
Ce format JSON est ensuite utilisé en tant que partie d’une expression de filtre via un appel à `rootcause.json = #[{}]`. Consultez le chapitre sur les [expressions de filtre](xray-console-filters.md) pour en savoir plus sur l’exécution de requêtes avec des expressions de filtre.
**Example Exemple de filtre JSON**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# Configuration des paramètres d'échantillonnage, de groupes et de chiffrement avec l' AWS X-Ray API
AWS X-Ray permet APIs de configurer les [règles d'échantillonnage, les](xray-console-sampling.md) règles de groupe et les [paramètres de chiffrement](xray-console-encryption.md).
**Topics**
+ [Paramètres de chiffrement](#xray-api-configuration-encryption)
+ [Règles d'échantillonnage](#xray-api-configuration-sampling)
+ [Groupes](#xray-api-configuration-groups)
## Paramètres de chiffrement
Permet [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)de spécifier une clé AWS Key Management Service (AWS KMS) à utiliser pour le chiffrement.
**Note**
X-Ray ne prend pas en charge les clés KMS asymétriques.
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
Pour l'ID de clé, vous pouvez utiliser un alias (comme illustré dans l'exemple), un ID de clé ou un ARN.
Utilisez [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) pour obtenir la configuration actuelle. Lorsque X-Ray a fini d'appliquer vos paramètres, le statut passe de `UPDATING` à`ACTIVE`.
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
Pour arrêter d'utiliser une clé KMS et utiliser le chiffrement par défaut, définissez le type de chiffrement sur`NONE`.
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## Règles d'échantillonnage
Vous pouvez gérer les [règles d'échantillonnage](xray-console-sampling.md) de votre compte à l'aide de l'API X-Ray. Pour plus d'informations sur l'ajout et la gestion de balises, consultez[Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
Obtenez toutes les règles d'échantillonnage avec [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
Par défaut, la règle s'applique à toutes les demandes qui ne correspond à aucune autre règle. Elle est la règle avec la plus faible priorité et ne peut pas être supprimée. Toutefois, vous pouvez modifier la fréquence et la taille du réservoir avec [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html).
**Example Entrée d'API pour [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
L'exemple suivant utilise le fichier précédente en tant qu'entrée pour modifier la règle par défaut sur un pour cent (1 %) sans réservoir. Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives. Pour supprimer des balises existantes d'une règle d'échantillonnage, utilisez [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
Créez les règles d'échantillonnage supplémentaires avec [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html). Lorsque vous créez une règle, la plupart des champs de la règle sont obligatoires. L'exemple suivant crée deux règles. Cette première règle définit un taux de base pour l'exemple d'application Scorekeep. Elle correspond à toutes les demandes servies par l'API qui ne correspond pas à la priorité de la règle.
**Example Entrée d'API pour [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 9000-base-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
La deuxième règle s'applique également à Scorekeep, mais elle a une priorité plus élevée et est plus spécifique. Cette règle définit un très faible taux d'échantillonnage pour les demandes d'interrogation. Il s'agit de demandes GET effectuées par le client toutes les deux ou trois secondes pour rechercher les modifications apportées à l'état du jeu.
**Example Entrée d'API pour [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 5000-polling-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives.
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
Pour supprimer une règle d'échantillonnage, utilisez [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html).
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## Groupes
Vous pouvez utiliser l'API X-Ray pour gérer les groupes de votre compte. Les groupes sont un ensemble de traces définies par une expression de filtre. Vous pouvez utiliser des groupes pour générer des graphiques de service supplémentaires et fournir CloudWatch des statistiques Amazon. Consultez [Obtenir des données à partir de AWS X-Ray](xray-api-gettingdata.md) pour plus de détails sur l'utilisation des graphiques et des métriques de service via l'API X-Ray. Pour plus d'informations sur les groupes, consultez[Configuration des groupes](xray-console-groups.md). Pour plus d'informations sur l'ajout et la gestion de balises, consultez[Étiquetage des règles et des groupes d'échantillonnage aux rayons X](xray-tagging.md).
Création d'un groupe avec `CreateGroup` Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives.
```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Obtenez tous les groupes existants à l'aide de `GetGroups`.
```
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}
```
Mettez à jour un groupe à l'aide de `UpdateGroup`. Les balises sont facultatives. Si vous choisissez d'ajouter des balises, une clé de balise est requise et les valeurs des balises sont facultatives. Pour supprimer des balises existantes d'un groupe, utilisez [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html).
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
Supprimez un groupe à l'aide de `DeleteGroup`.
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# Utilisation de règles d'échantillonnage avec l'API X-Ray
Le AWS X-Ray SDK utilise l'API X-Ray pour obtenir des règles d'échantillonnage, communiquer les résultats d'échantillonnage et obtenir des quotas. Vous pouvez les utiliser APIs pour mieux comprendre le fonctionnement des règles d'échantillonnage ou pour implémenter l'échantillonnage dans un langage non pris en charge par le kit de développement X-Ray.
Commencez par obtenir toutes les règles d'échantillonnage avec [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html).
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
La sortie inclut la règle par défaut et les règles personnalisées. Consultez [Règles d'échantillonnage](xray-api-configuration.md#xray-api-configuration-sampling) si vous n'avez pas encore créé de règles d'échantillonnage.
Evaluez les règles par rapport aux demandes entrantes par ordre croissant de priorité. Lorsqu'une règle correspond, utilisez la fréquence et la taille de réservoir fixées pour prendre une décision d'échantillonnage. Enregistrez les demandes échantillonnées et ignorez (à des fins de suivi) les demandes non échantillonnées. Arrêtez l'évaluation des règles lorsqu'une décision d'échantillonnage est prise.
Une taille de réservoir de règles est le nombre cible de suivis à enregistrer par seconde avant d'appliquer la fréquence fixe. Le réservoir s'applique à tous les services cumulativement. Vous ne pouvez donc pas l'utiliser directement. Toutefois, s'il est différent de zéro, vous pouvez emprunter une trace par seconde dans le réservoir jusqu'à ce que X-Ray vous assigne un quota. Avant de recevoir un quota, enregistrez la première demande chaque seconde et appliquez le taux fixe aux demandes additionnelles. La fréquence fixe est un nombre décimal compris entre 0 et 1,00 (100 %).
L'exemple suivant illustre un appel à [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) avec les détails sur les décisions d'échantillonnage effectuées au cours des 10 dernières secondes.
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
La réponse de X-Ray inclut un quota à utiliser au lieu d'emprunter au réservoir. Dans cet exemple, le service a emprunté 10 suivis au réservoir sur 10 secondes et appliqué la fréquence fixe de 10 % aux 100 autres demandes, ce qui se traduit par un total de 20 demandes échantillonnées. Le quota est valable pendant cinq minutes (indiqué par l'heure de vie) ou jusqu'à ce qu'un nouveau quota soit attribué. X-Ray peut également attribuer un intervalle de rapport plus long que celui par défaut, bien que ce ne soit pas le cas ici.
**Note**
La réponse de X-Ray n'inclut peut-être pas de quota la première fois que vous l'appelez. Continuez à emprunter au réservoir jusqu'à ce qu'un quota vous sot attribué.
Les deux autres champs de la réponse peuvent indiquer des problèmes avec l'entrée. Vérifiez `LastRuleModification` par rapport à votre dernier appel de [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html). S'il est plus récent, obtenez une nouvelle copie des règles. `UnprocessedStatistics` peut inclure des erreurs qui indiquent qu'une règle a été supprimée, que les statistiques de document dans l'entrée étaient trop anciennes ou qu'elle comportait des erreurs d'autorisation.
# AWS X-Ray documents segmentés
Un **segment de suivi** est une représentation JSON d'une demande que sert votre application. Un segment de trace enregistre des informations sur la demande d'origine, des informations sur le travail effectué localement par votre application et des **sous-segments contenant** des informations sur les appels en aval que votre application effectue vers les AWS ressources, les bases de données HTTP APIs et SQL.
Un **document de segment** transmet des informations sur un segment à X-Ray. Un document segmenté peut peser jusqu'à 64 kB et contenir un segment entier avec des sous-segments, un fragment de segment indiquant qu'une demande est en cours ou un sous-segment unique envoyé séparément. Vous pouvez envoyer des documents de segment directement à X-Ray à l'aide de l'[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)API.
X-Ray compile et traite des documents segmentés pour générer des **résumés de traces interrogeables et des** **traces complètes auxquels** vous pouvez accéder en utilisant respectivement le [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)et. [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) APIs Outre les segments et sous-segments que vous envoyez à X-Ray, le service utilise les informations contenues dans les sous-segments pour générer des **segments déduits** et les ajouter à la trace complète. Les segments déduits représentent les services et les ressources en aval sur la carte de suivi.
X-Ray fournit un **schéma JSON** pour les documents segmentés. Vous pouvez télécharger le schéma ici : [xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip). Les champs et les objets figurant dans le schéma sont décrits plus en détail dans les sections suivantes.
Un sous-ensemble de champs de segment est indexé par X-Ray pour être utilisé avec des expressions de filtre. Par exemple, si vous attribuez un identifiant unique au `user` champ d'un segment, vous pouvez rechercher des segments associés à des utilisateurs spécifiques dans la console X-Ray ou à l'aide de l'`GetTraceSummaries`API. Pour de plus amples informations, veuillez consulter [Utilisation d'expressions de filtre](xray-console-filters.md).
Lorsque vous instrumentez votre application avec le SDK X-Ray, celui-ci génère des documents segmentés pour vous. Au lieu d'envoyer les documents segmentés directement à X-Ray, le SDK les transmet via un port UDP local au daemon [X-Ray](xray-daemon.md). Pour de plus amples informations, veuillez consulter [Envoi de documents segmentés au daemon X-Ray](xray-api-sendingdata.md#xray-api-daemon).
**Topics**
+ [Champs de segment](#api-segmentdocuments-fields)
+ [Sous-segments](#api-segmentdocuments-subsegments)
+ [Données de demande HTTP](#api-segmentdocuments-http)
+ [Annotations](#api-segmentdocuments-annotations)
+ [Métadonnées](#api-segmentdocuments-metadata)
+ [AWS données sur les ressources](#api-segmentdocuments-aws)
+ [Erreurs et exceptions](#api-segmentdocuments-errors)
+ [Requêtes SQL](#api-segmentdocuments-sql)
## Champs de segment
Un segment enregistre les informations de suivi d'une demande que votre application sert. Au minimum, un segment enregistre le nom, l'ID, l'heure de début, l'ID de suivi et l'heure de fin de la demande.
**Example Segment terminé minimal**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
Les champs suivants sont obligatoires, ou soumis à condition, pour les segments.
**Note**
Les valeurs doivent être des chaînes (jusqu'à 250 caractères), sauf mention contraire.
**Champs de segment obligatoires**
+ `name`— Nom logique du service qui a traité la demande, **200 caractères** maximum. Par exemple, le nom de votre application ou le nom de domaine. Les noms peuvent contenir des lettres en Unicode, des nombres et des espaces, ainsi que les symboles suivants : `_`, `.`, `:`, `/`, `%`, `&`, `#`, `=`, `+`, `\`, `-`, `@`
+ `id`— Un identifiant 64 bits pour le segment, unique parmi les segments d'une même trace, en **16 chiffres hexadécimaux**.
+ `trace_id`— Un identifiant unique qui connecte tous les segments et sous-segments issus d'une seule demande client.
**Format d'identification X-Ray Trace**
Un X-Ray `trace_id` est composé de trois chiffres séparés par des tirets. Par exemple, `1-58406520-a006649127e371903a2de979`. Cela consiste notamment à :
+ Le numéro de version, qui est`1`.
+ L'heure de la demande initiale sous Unix Epoch Time en utilisant **8 chiffres hexadécimaux**.
Par exemple, le 1er décembre 2016 à 10 h 00 PST est exprimé en `1480615200` secondes ou `58406520` en chiffres hexadécimaux.
+ Identifiant 96 bits unique au monde pour la trace en **24 chiffres hexadécimaux**.
**Note**
X-Ray prend désormais en charge IDs les traces créées à OpenTelemetry l'aide de tout autre framework conforme à la spécification [W3C Trace Context](https://www.w3.org/TR/trace-context/). Un identifiant de trace W3C doit être formaté au format X-Ray trace ID lors de son envoi à X-Ray. Par exemple, l'ID de trace du W3C `4efaaf4d1e8720b39541901950019ee5` doit être formaté comme `1-4efaaf4d-1e8720b39541901950019ee5` lorsqu'il est envoyé à X-Ray. X-Ray Trace IDs inclut l'horodatage de la demande d'origine dans Unix Epoch Time, mais cela n'est pas obligatoire lors de l'envoi de la trace W3C au format IDs X-Ray.
**Sécurité de l'ID de suivi**
IDs Les traces sont visibles dans les [en-têtes de réponse](xray-concepts.md#xray-concepts-tracingheader). Générez des traces IDs à l'aide d'un algorithme aléatoire sécurisé pour empêcher les attaquants de calculer les traces futures IDs et d'envoyer des demandes avec celles-ci IDs à votre application.
+ `start_time`— **nombre correspondant** à l'heure à laquelle le segment a été créé, en secondes à virgule flottante par rapport à l'époque. Par exemple, `1480615200.010` ou `1.480615200010E9`. Utilisez autant de décimales que nécessaire. La résolution en microsecondes est recommandée si elle est disponible.
+ `end_time`— **numéro correspondant** à l'heure à laquelle le segment a été fermé. Par exemple, `1480615200.090` ou `1.480615200090E9`. Spécifiez une `end_time` ou `in_progress`.
+ `in_progress`— **booléen**, défini sur au `true` lieu de spécifier un `end_time` pour enregistrer qu'un segment est démarré mais qu'il n'est pas terminé. Envoyez un segment en cours lorsque votre application reçoit une demande longue à servir, pour suivre la réception de la demande. Lorsque la réponse est envoyée, envoyez le segment terminé pour remplacer le segment en cours. N'envoyez qu'un segment complet, et un ou zéro segment en cours, par demande.
**Noms des services**
Un segment `name` 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 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)peut envoyer des segments sous n'importe quel nom.
Les champs suivants sont facultatifs pour les segments.
**Champs de segment facultatifs**
+ `service`— Un objet contenant des informations sur votre application.
+ `version`— Chaîne identifiant la version de votre application qui a répondu à la demande.
+ `user`— Chaîne identifiant l'utilisateur qui a envoyé la demande.
+ `origin`— Type de AWS ressource exécutant votre application.
**Valeurs prises en charge**
+ `AWS::EC2::Instance`— Une EC2 instance Amazon.
+ `AWS::ECS::Container`— Un conteneur Amazon ECS.
+ `AWS::ElasticBeanstalk::Environment`— Un environnement Elastic Beanstalk.
Lorsque plusieurs valeurs sont applicables à votre application, utilisez celle qui est la plus spécifique. Par exemple, un environnement Docker Elastic Beanstalk multicontainer exécute votre application sur un conteneur Amazon ECS, qui s'exécute à son tour sur une instance Amazon. EC2 Dans ce cas, vous devez définir l'origine sur `AWS::ElasticBeanstalk::Environment` car l'environnement est le parent des deux autres ressources.
+ `parent_id`— Un ID de sous-segment que vous spécifiez si la demande provient d'une application instrumentée. Le SDK X-Ray ajoute l'ID du sous-segment parent à l'[en-tête de suivi](xray-concepts.md#xray-concepts-tracingheader) pour les appels HTTP en aval. Dans le cas de sous-segments imbriqués, un sous-segment peut avoir un segment ou un sous-segment comme parent.
+ `http`— [`http`](#api-segmentdocuments-http)objets contenant des informations sur la requête HTTP d'origine.
+ `aws`— [`aws`](#api-segmentdocuments-aws)objet contenant des informations sur la AWS ressource sur laquelle votre application a envoyé la demande.
+ `error`,`throttle`,`fault`, et `cause` — champs [d'erreur](#api-segmentdocuments-errors) qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception à l'origine de l'erreur.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)objet avec des paires clé-valeur que vous souhaitez que X-Ray indexe pour la recherche.
+ `metadata`: [`metadata`](#api-segmentdocuments-metadata)objet contenant toutes les données supplémentaires que vous souhaitez stocker dans le segment.
+ `subsegments`— **ensemble** d'[`subsegment`](#api-segmentdocuments-subsegments)objets.
## Sous-segments
Vous pouvez créer des sous-segments pour enregistrer les appels Services AWS et les ressources que vous effectuez avec le AWS SDK, les appels vers le Web APIs HTTP interne ou externe ou les requêtes de base de données SQL. Vous pouvez également créer des sous-segments pour déboguer ou annoter les blocs de code de votre application. Comme les sous-segments peuvent contenir d'autres sous-segments, un sous-segment personnalisé qui enregistre les métadonnées relatives à un appel de fonction interne peut contenir d'autres sous-segments personnalisés et les sous-segments d'appels en aval.
Un sous-segment enregistre un appel en aval du point de vue du service qui l'appelle. X-Ray utilise des sous-segments pour identifier les services en aval qui n'envoient pas de segments et créer des entrées pour eux sur le graphique des services.
Un sous-segment peut être intégré dans un document de segment entier, ou envoyé séparément. Envoyez des sous-segments séparément aux appels en aval de suivi de manière asynchrone pour les demandes de longue durée, ou pour éviter de dépasser la taille du document de segment maximum.
**Example Segment avec sous-segment intégré**
Un sous-segment indépendant possède `type` comme `subsegment` et un `parent_id` qui identifie le segment parent.
```
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}
```
Pour les demandes de longue durée, vous pouvez envoyer un segment en cours pour informer X-Ray de la réception de la demande, puis envoyer des sous-segments séparément pour les suivre avant de terminer la demande initiale.
**Example Segment en cours**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example Sous-segment indépendant**
Un sous-segment indépendant possède `type` comme `subsegment`, un `trace_id` et un `parent_id` qui identifie le segment parent.
```
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
```
Lorsque la demande est terminée, fermez le segment en le renvoyant avec un `end_time`. Le segment complet remplace le segment en cours.
Vous pouvez également envoyer des sous-segments séparément pour les demandes complètes qui ont déclenché des workflows asynchrones. Par exemple, une API Web peut renvoyer une réponse `OK 200` juste avant de démarrer le travail que l'utilisateur demandé. Vous pouvez envoyer un segment complet à X-Ray dès que la réponse est envoyée, suivi de sous-segments pour le travail terminé ultérieurement. Comme pour les segments, vous pouvez aussi envoyer un fragment de sous-segment pour enregistrer le démarrage du sous-segment, puis le remplacer par un sous-segment complet une fois que l'appel en aval est terminé.
Les champs suivants sont obligatoires, ou soumis à condition, pour les sous-segments.
**Note**
Les valeurs doivent être des chaînes (jusqu'à 250 caractères), sauf mention contraire.
**Champs de sous-segment obligatoires**
+ `id`— Un identifiant de 64 bits pour le sous-segment, unique parmi les segments d'une même trace, en **16 chiffres hexadécimaux**.
+ `name`— Nom logique du sous-segment. Pour les appels en aval, nommez le sous-segment après l'appel de la ressource ou du service. Pour les sous-segments personnalisés, nommez le sous-segment après le code qu'il instrumente (par exemple, un nom de fonction).
+ `start_time`— **nombre correspondant** à l'heure à laquelle le sous-segment a été créé, en secondes à virgule flottante par rapport à l'époque, avec une précision de quelques millisecondes. Par exemple, `1480615200.010` ou `1.480615200010E9`.
+ `end_time`— **numéro correspondant** à l'heure à laquelle le sous-segment a été fermé. Par exemple, `1480615200.090` ou `1.480615200090E9`. Spécifiez une `end_time` ou `in_progress`.
+ `in_progress`— **booléen** défini sur `true` au lieu de spécifier un `end_time` pour enregistrer qu'un sous-segment est démarré, mais qu'il n'est pas terminé. Envoyez uniquement un sous-segment complet, et un ou zéro sous-segment en cours, par demande en aval.
+ `trace_id`— ID de trace du segment parent du sous-segment. Obligatoire uniquement en cas d'envoi séparé d'un sous-segment.
**Format d'identification X-Ray Trace**
Un X-Ray `trace_id` est composé de trois chiffres séparés par des tirets. Par exemple, `1-58406520-a006649127e371903a2de979`. Cela consiste notamment à :
+ Le numéro de version, qui est`1`.
+ L'heure de la demande initiale sous Unix Epoch Time en utilisant **8 chiffres hexadécimaux**.
Par exemple, le 1er décembre 2016 à 10 h 00 PST est exprimé en `1480615200` secondes ou `58406520` en chiffres hexadécimaux.
+ Identifiant 96 bits unique au monde pour la trace en **24 chiffres hexadécimaux**.
**Note**
X-Ray prend désormais en charge IDs les traces créées à OpenTelemetry l'aide de tout autre framework conforme à la spécification [W3C Trace Context](https://www.w3.org/TR/trace-context/). Un identifiant de trace W3C doit être formaté au format X-Ray trace ID lors de son envoi à X-Ray. Par exemple, l'ID de trace du W3C `4efaaf4d1e8720b39541901950019ee5` doit être formaté comme `1-4efaaf4d-1e8720b39541901950019ee5` lorsqu'il est envoyé à X-Ray. X-Ray Trace IDs inclut l'horodatage de la demande d'origine dans Unix Epoch Time, mais cela n'est pas obligatoire lors de l'envoi de la trace W3C au format IDs X-Ray.
+ `parent_id`— ID de segment du segment parent du sous-segment. Obligatoire uniquement en cas d'envoi séparé d'un sous-segment. Dans le cas de sous-segments imbriqués, un sous-segment peut avoir un segment ou un sous-segment comme parent.
+ `type`—`subsegment`. Obligatoire uniquement si vous envoyez un sous-segment séparément.
Les champs suivants sont facultatifs pour les sous-segments.
**Champs de sous-segment facultatifs**
+ `namespace`— `aws` pour les appels du SDK AWS ; `remote` pour les autres appels en aval.
+ `http`— [`http`](#api-segmentdocuments-http)objet contenant des informations relatives à un appel HTTP sortant.
+ `aws`: [`aws`](#api-segmentdocuments-aws)objet contenant des informations sur la AWS ressource en aval appelée par votre application.
+ `error`,`throttle`,`fault`, et `cause` — champs [d'erreur](#api-segmentdocuments-errors) qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception à l'origine de l'erreur.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)objet avec des paires clé-valeur que vous souhaitez que X-Ray indexe pour la recherche.
+ `metadata`: [`metadata`](#api-segmentdocuments-metadata)objet contenant toutes les données supplémentaires que vous souhaitez stocker dans le segment.
+ `subsegments`— **ensemble** d'[`subsegment`](#api-segmentdocuments-subsegments)objets.
+ `precursor_ids`— **tableau** de sous-segments identifiant IDs les sous-segments ayant le même parent que ceux terminés avant ce sous-segment.
## Données de demande HTTP
Utilisez un bloc HTTP pour enregistrer les détails relatifs à une demande HTTP que votre application a servie (dans un segment) ou que votre application a effectuée auprès d'une API HTTP en aval (dans un sous-segment). La plupart des champs de cet objet correspondent aux informations disponibles dans une demande et une réponse HTTP.
**`http`**
Tous les champs sont facultatifs.
+ `request`— Informations relatives à une demande.
+ `method`— La méthode de demande. Par exemple, `GET`.
+ `url`— L'URL complète de la demande, compilée à partir du protocole, du nom d'hôte et du chemin de la demande.
+ `user_agent`— La chaîne d'agent utilisateur du client du demandeur.
+ `client_ip`— L'adresse IP du demandeur. Peut être récupérée depuis la `Source Address` du paquet IP ou, pour les demandes acheminées, à partir d'un en-tête `X-Forwarded-For`.
+ `x_forwarded_for`— (segments uniquement) **booléen** indiquant que le `client_ip` a été lu à partir d'un `X-Forwarded-For` en-tête et qu'il n'est pas fiable car il aurait pu être falsifié.
+ `traced`— (sous-segments uniquement) **booléen** indiquant que l'appel en aval concerne un autre service suivi. Si ce champ est défini sur`true`, X-Ray considère que la trace est interrompue jusqu'à ce que le service en aval télécharge un segment dont le `parent_id` nom correspond à celui `id` du sous-segment contenant ce bloc.
+ `response`— Informations relatives à une réponse.
+ `status`— **entier** indiquant le statut HTTP de la réponse.
+ `content_length`— **entier** indiquant la longueur du corps de la réponse en octets.
Lorsque vous instrumentez un appel à une API Web en aval, enregistrez un sous-segment contenant des informations sur la requête et la réponse HTTP. X-Ray utilise le sous-segment pour générer un segment inféré pour l'API distante.
**Example Segment pour un appel HTTP envoyé par une application exécutée sur Amazon EC2**
```
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
**Example Sous-segment pour un appel HTTP en aval**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segment déduit pour un appel HTTP en aval**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
## Annotations
Les segments et sous-segments peuvent inclure un `annotations` objet contenant un ou plusieurs champs indexés par X-Ray pour une utilisation avec des expressions de filtre. Les champs peuvent avoir des valeurs de type chaîne, numérique ou booléen (ni objet ni tableau). X-Ray indexe jusqu'à 50 annotations par trace.
**Example Segment pour appel HTTP avec annotations**
```
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
Les clés doivent être au format alphanumérique pour fonctionner avec les filtres. Les traits de soulignement sont autorisés. Les autres symboles et les espaces ne sont pas autorisés.
## Métadonnées
Les segments et sous-segments peuvent inclure un `metadata` objet contenant un ou plusieurs champs avec des valeurs de n'importe quel type, y compris des objets et des tableaux. X-Ray n'indexe pas les métadonnées et les valeurs peuvent être de n'importe quelle taille, tant que le document segmenté ne dépasse pas la taille maximale (64 kB). Vous pouvez consulter les métadonnées dans le document de segment complet retourné par l'API [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html). Les clés de champ (`debug`dans l'exemple suivant) commençant par `AWS.` sont réservées à l'utilisation par AWS-provided SDKs et par les clients.
**Example Sous-segment personnalisé avec métadonnées**
```
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}
```
## AWS données sur les ressources
Pour les segments, l'objet `aws` contient les informations relatives à la ressource sur laquelle votre application est en cours d'exécution. Plusieurs champs peuvent s'appliquer à une même ressource. Par exemple, une application exécutée dans un environnement Docker multiconteneur sur Elastic Beanstalk peut contenir des informations sur l'instance Amazon, le conteneur EC2 Amazon ECS exécuté sur l'instance et l'environnement Elastic Beanstalk lui-même.
**`aws` (Segments)**
Tous les champs sont facultatifs.
+ `account_id`— Si votre application envoie des segments à un autre Compte AWS, enregistrez l'identifiant du compte qui exécute votre application.
+ `cloudwatch_logs`— Tableau d'objets décrivant un seul groupe de CloudWatch logs.
+ `log_group`— Le nom du groupe de CloudWatch journaux.
+ `arn`— L'ARN du groupe de CloudWatch logs.
+ `ec2`— Informations sur une EC2 instance Amazon.
+ `instance_id`— L'ID d'instance de l' EC2 instance.
+ `instance_size`— Type d' EC2 instance.
+ `ami_id`— L'identifiant Amazon Machine Image.
+ `availability_zone`— La zone de disponibilité dans laquelle l'instance est exécutée.
+ `ecs`— Informations sur un conteneur Amazon ECS.
+ `container`— Le nom d'hôte de votre conteneur.
+ `container_id`— L'identifiant complet de votre conteneur.
+ `container_arn`— L'ARN de votre instance de conteneur.
+ `eks`— Informations sur un cluster Amazon EKS.
+ `pod`— Le nom d'hôte de votre pod EKS.
+ `cluster_name`— Le nom du cluster EKS.
+ `container_id`— L'identifiant complet de votre conteneur.
+ `elastic_beanstalk`— Informations sur un environnement Elastic Beanstalk. Vous trouverez ces informations dans un fichier nommé `/var/elasticbeanstalk/xray/environment.conf` sur les dernières plateformes Elastic Beanstalk.
+ `environment_name` : Nom de l'environnement.
+ `version_label`— Nom de la version de l'application actuellement déployée sur l'instance qui a répondu à la demande.
+ `deployment_id`— **numéro** indiquant l'ID du dernier déploiement réussi sur l'instance qui a répondu à la demande.
+ `xray`— Des métadonnées sur le type et la version de l'instrumentation utilisée.
+ `auto_instrumentation`— Booléen indiquant si l'instrumentation automatique a été utilisée (par exemple, l'agent Java).
+ `sdk_version`— Version du SDK ou de l'agent utilisé.
+ `sdk`— Le type de SDK.
**Example AWS bloc avec plugins**
```
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
```
Pour les sous-segments, enregistrez les informations relatives aux ressources Services AWS et aux ressources auxquelles votre application accède. X-Ray utilise ces informations pour créer des segments déduits qui représentent les services en aval dans votre carte des services.
**`aws` (Sous-segments)**
Tous les champs sont facultatifs.
+ `operation`— Le nom de l'action d'API invoquée contre une ressource Service AWS or.
+ `account_id`— Si votre application accède aux ressources d'un autre compte ou envoie des segments vers un autre compte, enregistrez l'ID du compte propriétaire de la AWS ressource à laquelle votre application a accédé.
+ `region`— Si la ressource se trouve dans une région différente de celle de votre application, enregistrez la région. Par exemple, `us-west-2`.
+ `request_id`— Identifiant unique de la demande.
+ `queue_url`— Pour les opérations sur une file d'attente Amazon SQS, l'URL de la file d'attente.
+ `table_name`— Pour les opérations sur une table DynamoDB, nom de la table.
**Example Sous-segment pour un appel à DynamoDB pour enregistrer un élément**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
## Erreurs et exceptions
Lorsqu'une erreur se produit, vous pouvez enregistrer les détails de l'erreur et les exceptions qui ont été générées. Enregistrez les erreurs dans les segments lorsque votre application renvoie une erreur à l'utilisateur et dans les sous-segments lorsqu'un appel en aval renvoie une erreur.
**types d'erreur**
Définissez un ou plusieurs des champs suivants sur `true` pour indiquer qu'une erreur s'est produite. Plusieurs types peuvent s'appliquer en cas d'erreurs composites. Par exemple, une erreur `429 Too Many Requests` d'un appel en aval peut contraindre votre application à renvoyer `500 Internal Server Error`, auquel cas les trois types s'appliquent.
+ `error`— **booléen** indiquant qu'une erreur client s'est produite (le code d'état de la réponse était 4XX Client Error).
+ `throttle`— **booléen** indiquant qu'une demande a été limitée (le code d'état de la réponse était *429 demandes trop nombreuses*).
+ `fault`— **booléen** indiquant qu'une erreur de serveur s'est produite (le code d'état de réponse était 5XX Server Error).
Indiquez la cause de l'erreur en incluant un objet **cause** dans le segment ou le sous-segment.
**`cause`**
Une cause peut être un ID d'exception sur **16 caractères** ou un objet avec les champs suivants :
+ `working_directory`— Le chemin complet du répertoire de travail lorsque l'exception s'est produite.
+ `paths`— Le **tableau** des chemins d'accès aux bibliothèques ou aux modules utilisés lorsque l'exception s'est produite.
+ `exceptions`— Le **tableau** des objets d'**exception**.
Incluez les informations détaillées sur l'erreur dans un ou plusieurs objets **exception**.
**`exception`**
Tous les champs sont facultatifs.
+ `id`— Un identifiant de 64 bits pour l'exception, unique parmi les segments d'une même trace, en **16 chiffres hexadécimaux**.
+ `message`— Le message d'exception.
+ `type`— Le type d'exception.
+ `remote`— **booléen** indiquant que l'exception a été provoquée par une erreur renvoyée par un service en aval.
+ `truncated`— **entier** indiquant le nombre de cadres de pile qui sont omis dans le`stack`.
+ `skipped`— **entier** indiquant le nombre d'exceptions ignorées entre cette exception et son enfant, c'est-à-dire l'exception qu'elle a provoquée.
+ `cause`— ID d'exception du parent de l'exception, c'est-à-dire l'exception à l'origine de cette exception.
+ `stack`— **tableau d'**objets **StackFrame**.
Le cas échéant, enregistrez les informations relatives à la pile des appels dans les objets **stackFrame**.
**`stackFrame`**
Tous les champs sont facultatifs.
+ `path`— Le chemin relatif du fichier.
+ `line`— La ligne du fichier.
+ `label`— Le nom de la fonction ou de la méthode.
## Requêtes SQL
Vous pouvez créer des sous-segments pour les requêtes que votre application effectue auprès d'une base de données SQL.
**`sql`**
Tous les champs sont facultatifs.
+ `connection_string`— Pour les connexions à SQL Server ou à d'autres bases de données qui n'utilisent pas de chaînes de connexion URL, enregistrez la chaîne de connexion, à l'exception des mots de passe.
+ `url`— Pour une connexion à une base de données utilisant une chaîne de connexion URL, enregistrez l'URL, à l'exception des mots de passe.
+ `sanitized_query`— La requête de base de données, avec toutes les valeurs fournies par l'utilisateur supprimées ou remplacées par un espace réservé.
+ `database_type`— Nom du moteur de base de données.
+ `database_version`— Numéro de version du moteur de base de données.
+ `driver_version`— Le nom et le numéro de version du pilote du moteur de base de données utilisé par votre application.
+ `user`— Le nom d'utilisateur de la base de données.
+ `preparation`— `call` si la requête a utilisé un `PreparedCall` ; `statement` si la requête a utilisé `PreparedStatement` a.
**Example Sous-segment avec une requête SQL**
```
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}
```