AWS X-Ray documents segmentés

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

  • 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 les identifiants de trace créés à OpenTelemetry l'aide de tout autre framework conforme à la spécification W3C 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. Les identifiants de trace X-Ray incluent l'horodatage de la demande d'origine à l'époque Unix, mais cela n'est pas obligatoire lors de l'envoi des identifiants de trace du W3C au format X-Ray.

  Sécurité de l'ID de suivi

  Les ID de suivi sont visibles dans les en-têtes de réponse. Générez des ID de suivi avec un algorithme aléatoire sécurisé pour garantir que les attaquants ne puissent pas calculer vos futurs ID de suivi et envoyer des demandes à votre application avec ces ID.

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

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 instance Amazon EC2.

  • 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 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— httpobjets contenant des informations sur la requête HTTP d'origine.

• aws— awsobjet contenant des informations sur la AWS ressource sur laquelle votre application a envoyé la demande.

• error,throttle,fault, et cause — champs d'erreur qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception à l'origine de l'erreur.

• annotations— annotationsobjet avec des paires clé-valeur que vous souhaitez que X-Ray indexe pour la recherche.

• metadata: metadataobjet contenant toutes les données supplémentaires que vous souhaitez stocker dans le segment.

• subsegments— ensemble d'subsegmentobjets.

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

  • 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 les identifiants de trace créés à OpenTelemetry l'aide de tout autre framework conforme à la spécification W3C 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. Les identifiants de trace X-Ray incluent l'horodatage de la demande d'origine à l'époque Unix, mais cela n'est pas obligatoire lors de l'envoi des identifiants de trace du W3C au format 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.

Champs de sous-segment facultatifs

• namespace— aws pour les appels du SDK AWS ; remote pour les autres appels en aval.

• http— httpobjet contenant des informations relatives à un appel HTTP sortant.

• aws: awsobjet contenant des informations sur la AWS ressource en aval appelée par votre application.

• error,throttle,fault, et cause — champs d'erreur qui indiquent qu'une erreur s'est produite et qui incluent des informations sur l'exception à l'origine de l'erreur.

• annotations— annotationsobjet avec des paires clé-valeur que vous souhaitez que X-Ray indexe pour la recherche.

• metadata: metadataobjet contenant toutes les données supplémentaires que vous souhaitez stocker dans le segment.

• subsegments— ensemble d'subsegmentobjets.

• precursor_ids— tableau d'identifiants de sous-segments identifiant les sous-segments ayant le même parent que ceux terminés avant ce sous-segment.

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 est destiné à un autre service suivi. Si ce champ est défini surtrue, 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.

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 instance Amazon EC2.

  • instance_id— L'ID d'instance de l'instance EC2.

  • instance_size— Type d'instance EC2.

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

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.

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

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.

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— 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 lestack.

• 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 de l'exception à l'origine de cette exception.

• stack— tableau d'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.

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