Comment puis-je résoudre les problèmes liés à l'absence de traces, de segments ou de services X-Ray dans la carte des services ?

Brève description

L'absence de services dans la carte des services est due aux traces manquantes. Causes pouvant expliquer l'absence de traces :

• Instrumentation incorrecte
• Impossibilité pour le kit SDK X-Ray d'atteindre le démon X-Ray via l'adresse ou le numéro de port du démon
• Impossibilité pour le démon X-Ray d'atteindre le point de terminaison du service X-Ray
• Suivi non configuré au niveau du service individuel
• Autorisations AWS Identity and Access Management (IAM) manquantes
• Configuration des règles d'échantillonnage
• Configuration manquante dans OpenTelemetry Collector

Les segments manquants peuvent être dus à une absence de segments parents ouverts dans les sous-segments. Pour en savoir plus, reportez-vous à Résolution des problèmes liés à AWS X-Ray.

Résolution

Instrumentation incorrecte

Instrumentation incorrecte lorsque vous utilisez le kit SDK X-Ray

Si le code de l'application n'est pas correctement instrumenté pour que le kit SDK X-Ray corrige les bibliothèques et les frameworks compatibles, il se peut que des traces soient manquantes. Les identifiants de trace qui ne sont pas transmis aux services en aval peuvent également entraîner une absence de traces.

Pour résoudre ce problème, activez la journalisation au niveau du débogage sur le kit SDK afin de générer des journaux plus détaillés dans le fichier journal de votre application. Cela vous permet de mieux isoler les problèmes liés à l'instrumentation et de suivre le flux de l'ID de trace dans l'application. Les journaux indiquent également si une trace est manquante en raison d'une absence d'échantillonnage ou d'une mauvaise configuration de l'instrumentation. Pour en savoir plus, consultez la journalisation de débogage dans le kit SDK X-Ray pour Java, Node.js, Python , .NET ou Ruby.

Remarque : si l'application utilise un agent d'auto-instrumentation pour Java, elle ne capture pas les traces des requêtes asynchrones. Ces traces seront donc manquantes. En cas de traces manquantes, recourrez à une instrumentation manuelle. Si le kit SDK X-Ray ne dispose pas de certaines fonctionnalités ou présente des problèmes, recherchez l'agent d'instrumentation automatique pour Java dans le kit SDK OpenTelemetry.

Instrumentation incorrecte lorsque vous utilisez le kit SDK OpenTelemetry

Si vous utilisez le kit SDK OpenTelemetry et que le code de l'application n'est pas correctement instrumenté pour corriger les bibliothèques et les frameworks pris en charge, le code peut présenter des traces manquantes. Des identifiants de trace qui ne sont pas transmis aux services en aval peuvent entraîner une absence de segments.

Pour résoudre ce problème, procédez comme suit :

• Activez la journalisation au niveau du débogage sur le kit SDK pour envoyer des journaux plus détaillés vers le fichier journal de votre application. Cela vous permet de mieux isoler les problèmes liés à l'instrumentation et de suivre le flux de l'ID de trace dans l'application. Les journaux indiquent si une trace est manquante en raison d'une absence d'échantillonnage ou en raison d'une mauvaise configuration de l'instrumentation. Pour en savoir plus, consultez la journalisation de débogage dans le kit SDK X-Ray pour Java, Node.js, Python , .NET ou Ruby.
• Assurez-vous que l'instrumentation n'est pas désactivée. Pour en savoir plus, reportez-vous à Suppression d'une instrumentation automatique spécifique sur le site web d'OpenTelemetry.

Remarque : pour enrichir les traces avec des informations sur l'infrastructure AWS, assurez-vous que le détecteur de ressources AWS est compatible avec ce service AWS dans le kit SDK OpenTelemetry. Pour en savoir plus, reportez-vous à Utilisation des détecteurs de ressources AWS.

Impossibilité pour le kit SDK X-Ray d'atteindre le démon X-Ray via l'adresse ou le numéro de port du démon

Si le kit SDK X-Ray ne parvient pas à atteindre le démon X-Ray via le numéro de port et l'adresse du démon par défaut ou configurés, les traces du kit SDK seront manquantes. L'adresse du démon X-Ray est transmise au kit SDK via la variable d'environnement AWS_XRAY_DAEMON_ADDRESS. Par défaut, le démon X-Ray écoute sur le port 2000 UDP. Vous pouvez modifier ce port via l'option de ligne de commande et le fichier de configuration transmis au démon X-ray. Pour en savoir plus, reportez-vous à Utilisation d'un fichier de configuration.

Si vous exécutez le démon X-Ray avec des journaux de débogage, exécutez la commande suivante pour identifier le port UDP configuré pour le démon X-Ray :

./xray -l debug

Remarque : l'exemple suivant identifie le numéro de port 3000.

Exemple de sortie :

2023-03-28T15:15:43-07:00 \[Debug\] Listening on UDP 127.0.0.1:3000

Si vous n'exécutez pas le démon X-Ray avec des journaux de débogage, activez l'option permettant de déboguer les journaux et réexécutez le démon. Pour en savoir plus, reportez-vous à Utilisation d'un fichier de configuration.

Remarque : si le démon X-Ray ne s'exécute pas sur la même machine que votre application et le kit SDK X-Ray, vérifiez la règle entrante et la règle d'entrée. Vérifiez que la règle entrante du groupe de sécurité et la règle d'entrée de la liste de contrôle d'accès au réseau (ACL réseau) autorisent le trafic. Le trafic doit être autorisé pour le kit SDK X-Ray via le port d'écoute du démon X-Ray.

Impossibilité pour le démon X-Ray d'atteindre le point de terminaison du service X-Ray

Si le démon X-Ray ne parvient pas à atteindre le point de terminaison du service X-Ray, vérifiez les points suivants :

• Si vous avez configuré un proxy au point de terminaison source, vérifiez si le proxy autorise ou non le trafic à atteindre le point de terminaison du service X-Ray.
• Si vous utilisez le point de terminaison X-Ray Amazon Virtual Private Cloud (Amazon VPC) com.amazonaws.region.xray pour vous connecter au service X-Ray, vérifiez le groupe de sécurité associé. Assurez-vous que le trafic sortant du groupe de sécurité permet au trafic HTTPS de transmettre des données à l'API du service X-Ray. Assurez-vous également que le groupe de sécurité autorise le trafic entrant sur le port 443 pour autoriser le démon X-Ray.
• Vérifiez que l'ACL réseau associée et le point de terminaison Amazon VPC du service X-Ray disposent d'une règle de sortie qui autorise le trafic sur le port 443 vers toutes les destinations 0.0.0.0/0. Le démon X-Ray doit envoyer des données au point de terminaison du service X-Ray. Vérifiez également que la règle d'entrée de l'ACL réseau autorise le trafic depuis le démon X-Ray vers le point de terminaison Amazon VPC.

Suivi non configuré au niveau du service individuel

Si vous n'activez pas la configuration X-Ray pour certains services AWS, des traces peuvent être manquantes. La liste suivante répertorie les services AWS qui nécessitent l'activation de la configuration X-Ray au niveau du service :

• AWS AppSync
• AWS App Runner
• Amazon API Gateway
• Amazon CloudWatch RUM
• AWS Lambda
• Amazon Simple Notification Service (Amazon SNS)
• AWS Step Functions

Autorisations IAM manquantes

Vérifiez que vous disposez des autorisations IAM requises :

• Si vous recevez des messages d'erreur Accès refusé dans les journaux du démon X-Ray, vérifiez les autorisations IAM. Pour envoyer des traces au point de terminaison du service X-Ray, le rôle IAM du démon X-Ray nécessite des autorisations dans la politique gérée AWSXRAYDaemonWriteAccess. Si vous utilisez une condition basée sur des balises dans votre politique IAM, assurez-vous que la politique IAM fait référence à la balise appropriée. Pour en savoir plus, reportez-vous à Autorisation basée sur les balises X-Ray.
• Si le démon X-Ray s'exécute dans Amazon Elastic Container Service (Amazon ECS) en tant que conteneur sidecar dans la tâche, vérifiez le rôle de tâche Amazon ECS. Assurez-vous que la politique AWSXRayDaemonWriteAccess est associée au rôle de tâche Amazon ECS.
• Si vous déployez le démon X-Ray dans Amazon Elastic Kubernetes Services (Amazon EKS), vérifiez le conteneur sidecar dans le pod. Assurez-vous que le conteneur utilise des rôles IAM pour les comptes de service (IRSA) et que la politique AWSXRayDaemonWriteAccess est associée au rôle IAM.
• Si vous avez configuré le démon X-Ray dans Amazon Elastic Compute Cloud (Amazon EC2), vérifiez le profil d'instance associé. Assurez-vous que la politique AWSXRayDaemonWriteAccess est associée au rôle de profil d'instance de cette instance EC2.
• Si vous avez configuré le démon X-Ray dans AWS Lambda, vérifiez le rôle d'exécution Lambda. Vérifiez si le rôle d'exécution Lambda est associé à la politique AWSXRayDaemonWriteAccess. Assurez-vous que la politique est associée.
• Si vous avez activé le suivi actif dans Amazon SNS et que vous ne pouvez toujours pas voir les traces, configurez une politique de ressources dans X-Ray.

Remarque : pour vérifier les autorisations X-ray, utilisez le simulateur de politiques IAM pour tester le rôle ou la politique IAM associée à la ressource. Vérifiez également les politiques de contrôle des services (SCP) de votre organisation. Les SCP limitent l'accès au niveau du compte pour des appels d'API spécifiques.

Pour obtenir la liste des politiques gérées par IAM pour X-Ray, reportez-vous à Politiques gérées par IAM pour X-Ray.

Configuration des règles d'échantillonnage

Si le kit SDK X-Ray et les services AWS qui prennent en charge le suivi actif avec configuration d'échantillonnage n'échantillonnent pas de traces, les traces seront manquantes. Utilisez des règles d'échantillonnage pour déterminer les demandes à enregistrer. Par défaut, le kit SDK X-Ray enregistre la première demande chaque seconde, puis cinq pour cent des demandes supplémentaires. Vous pouvez modifier le taux d'échantillonnage pour diminuer ou augmenter le nombre de traces enregistrées.

Par exemple, un réservoir est défini sur 1. Un réservoir de 1 indique que la première demande de chaque seconde est prise en compte. Sinon, le taux d'échantillonnage est réglé sur 0,1. Un taux d'échantillonnage de 0,1 indique que 10 % des demandes supplémentaires de chaque seconde sont enregistrées.

Comme le kit SDK X-Ray limite le nombre de demandes enregistrées par le kit SDK, il est possible que les demandes ne soient pas toutes suivies. Pour enregistrer davantage de traces, augmentez les paramètres du réservoir et de la fréquence d'échantillonnage. Pour en savoir plus, reportez-vous à Exemples de règles d'échantillonnage.

Remarque : si vous avez configuré plusieurs règles d'échantillonnage et que le nombre de traces échantillonnées fluctue, vérifiez la règle d'échantillonnage utilisée par le kit SDK X-Ray. Pour en savoir plus, reportez-vous à Affichage des résultats d'échantillonnage.

Configuration manquante dans OpenTelemetry Collector

Si vous utilisez OpenTelemetry Collector au lieu du démon X-Ray, la configuration requise du récepteur et de l'exportateur est peut-être manquante. Si une configuration est manquante, les traces ne sont pas envoyées au point de terminaison du service X-Ray. En fonction de votre récepteur, vérifiez la configuration du récepteur dans le fichier config.yaml pour vérifier qu'aucune configuration n'est manquante.

Consultez les exemples de configuration suivants sur le site web de GitHub :

• Exportateur X-Ray
• Récepteur X-Ray
• Récepteur ZipKin

Remarque : assurez-vous que les autorisations IAM requises figurent dans la politique gérée AWSXRayDaemonWriteAccess.