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

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

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)