Configuration de règles d'échantillonnage - AWS X-Ray
Configuration de règles d'échantillonnage Personnalisation des règles d'échantillonnageOptions de règle d'échantillonnageExemples de règles d'échantillonnageConfiguration de votre service afin d'utiliser les règles d'échantillonnageAffichage des résultats d'échantillonnageÉtapes suivantes

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.

Configuration de règles d'échantillonnage

Vous pouvez utiliser la AWS X-Ray console pour configurer les règles d'échantillonnage pour vos services. Le SDK X-Ray et ceux services AWS qui prennent en charge le traçage actif avec configuration d'échantillonnage utilisent des règles d'échantillonnage pour déterminer les demandes à enregistrer.

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.

  • 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.

  • SDK Instrument X-Ray sur des plateformes informatiques : lorsque vous utilisez des plateformes de calcul telles qu'Amazon EC2, Amazon ECS AWS Elastic Beanstalk ou, l'échantillonnage est pris en charge lorsque l'application a été instrumentée avec le dernier SDK 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 SDK X-Ray le nombre de demandes à enregistrer pour un ensemble de critères. Par défaut, le SDK X-Ray 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 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

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. Vous pouvez également continuer à utiliser la console X-Ray.

CloudWatch console
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/.

  2. Choisissez Paramètres dans le volet de navigation de gauche.

  3. Choisissez Afficher les paramètres sous Règles d'échantillonnage dans la section X-Ray Traces.

  4. 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.

X-Ray console
Pour configurer les règles d'échantillonnage dans la console X-Ray

  1. Ouvrez la console X-Ray.

  2. Choisissez Sampling dans le volet de navigation de gauche.

  3. Pour créer une règle, choisissez Create sampling rule (Créer une règle d’échantillonnage).

    Pour modifier une règle, choisissez le nom d'une règle.

    Pour supprimer une règle, choisissez une règle et utilisez le menu Actions 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 instance Amazon EC2 (plugin).

    • AWS::ECS::Container— Un conteneur Amazon ECS (plugin).

    • AWS::APIGateway::Stage— Une étape Amazon API Gateway.

    • AWS::AppSync::GraphQLAPI — Une demande AWS AppSync d'API.

  • 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 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.

Exemples de règles d'échantillonnage

Exemple — 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.05si configuré à l'aide d'un document JSON)

Exemple — 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 (1si configuré à l'aide d'un document JSON)

  • Nom du service : Scorekeep

  • Type de service : *

  • Hôte : *

  • Méthode HTTP : PUT

  • Chemin de l'URL : /history/*

  • ARN de la ressource : *

Exemple — Taux minimum plus élevé pour les POST

  • Nom de la règle : POST minimum

  • Priorité : 100

  • Réservoir : 10

  • Taux : 10 (.1si configuré à l'aide d'un document JSON)

  • Nom du service : *

  • Type de service : *

  • Hôte : *

  • Méthode HTTP : POST

  • Chemin de l'URL : *

  • ARN de la ressource : *

Configuration de votre service afin d'utiliser les règles d'échantillonnage

Le SDK 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 :

Pour API Gateway, consultezSupport de suivi actif d'Amazon API Gateway pour AWS X-Ray.

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.

É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 de l'échantillonnage, des groupes et des paramètres de chiffrement avec l'API AWS X-Ray pour obtenir des instructions et des exemples de règles supplémentaires.

Le SDK X-Ray peut services AWS également utiliser 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.

Lorsque le SDK X-Ray appelle des API d'échantillonnage, il utilise le démon X-Ray comme proxy. Si vous utilisez déjà le port TCP 2000, vous pouvez configurer le démon pour exécuter le proxy sur un autre port. Consultez Configuration du AWS X-Ray daemon pour plus de détails.