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.
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. Un segment enregistre, au minimum, le temps consacré à une tâche, un nom et deux ID. 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.
Exemple 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.
Exemple 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, avec ou via le daemon X-Ray.
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).
Exemple 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.
Sections
Génération d'ID de suivi
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 consiste notamment à :
-
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 ou58406520
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 Context4efaaf4d1e8720b39541901950019ee5
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.
Vous pouvez écrire un script pour générer des identifiants de trace X-Ray à des 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 identifiants de trace et envoient des segments au daemon X-Ray.
-
Python –
xray_start.py
-
Bash —
xray_start.sh
En utilisant PutTraceSegments
Vous pouvez charger des documents relatifs aux segments avec l'API PutTraceSegments
. 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 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 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
Exemple 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 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)