Invio dei dati di tracciamento a AWS X-Ray

È possibile inviare dati di traccia a X-Ray sotto forma di documenti di segmento. Un documento di segmento è una stringa in formato JSON che contiene le informazioni sull'attività eseguita dalla tua applicazione per il soddisfacimento di una richiesta. La tua applicazione può memorizzare i dati sull'attività che svolge in segmenti, oppure le attività che utilizzano i servizi e le risorse a valle possono creare dei sottosegmenti.

I segmenti registrano le informazioni sull'attività svolta dalla tua applicazione. Un segmento, come minimo, memorizza il tempo speso per un'attività, un nome e due identificativi. L'ID di tracciamento monitora la richiesta durante il suo passaggio tra i servizi. L'ID segmento monitora l'attività svolta per la richiesta proveniente da uno specifico servizio.

Esempio Segmento completo minimale

{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Quando ricevi una richiesta, puoi inviare un segmento in esecuzione come segnaposto fino al completamento della richiesta.

Esempio Segmento in esecuzione

{
  "name" : "Scorekeep",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  “in_progress”: true
}

È possibile inviare segmenti a X-Ray direttamente, PutTraceSegmentscon o tramite il demone X-Ray.

La maggior parte delle applicazioni richiama altri servizi o accede a risorse con l'SDK. AWS Registra le informazioni sulle chiamate downstream in sottosegmenti. X-Ray utilizza i sottosegmenti per identificare i servizi a valle che non inviano segmenti e creare le relative voci nel grafico dei servizi.

Un sottosegmento può essere incorporato in un documento di segmento completo oppure può essere inviato in modo separato. Invia i sottosegmenti separatamente per tracciare in modo asincrono le chiamate downstream per richieste di lunga durata o per evitare di superare la dimensione massima del documento del segmento (64 kB).

Esempio Segmento secondario

Un sottosegmento presenta un type valorizzato a subsegment e un parent_id che identifica il segmento padre.

{
  "name" : "www2.example.com",
  "id" : "70de5b6f19ff9a0c",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  “end_time” : 1.478293361449E9,
  “type” : “subsegment”,
  “parent_id” : “70de5b6f19ff9a0b”
}

Per ulteriori informazioni sui campi e i valori che puoi includere in segmenti e sottosegmenti, consulta AWS X-Ray segmentare i documenti.

Generazione degli ID di tracciamento

Per inviare dati a X-Ray, è necessario generare un ID di traccia univoco per ogni richiesta.

Formato ID di traccia X-Ray

Una radiografia trace_id è composta da tre numeri separati da trattini. Ad esempio, 1-58406520-a006649127e371903a2de979. Questo include:

• Il numero di versione, che è. 1

• L'ora della richiesta originale in Unix epoch time utilizzando 8 cifre esadecimali.

  Ad esempio, il fuso orario PST delle 10:00 del 1° dicembre 2016 è espresso in secondi o in cifre esadecimali. 1480615200 58406520

• Un identificatore globale unico a 96 bit per la traccia in 24 cifre esadecimali.

Nota

X-Ray ora supporta gli ID di traccia creati utilizzando OpenTelemetry e qualsiasi altro framework conforme alla specifica W3C Trace Context. Un ID di traccia W3C deve essere formattato nel formato X-Ray Trace ID quando viene inviato a X-Ray. Ad esempio, l'ID di traccia W3C 4efaaf4d1e8720b39541901950019ee5 deve essere formattato come 1-4efaaf4d-1e8720b39541901950019ee5 quando si invia a X-Ray. Gli ID di traccia X-Ray includono il timestamp originale della richiesta in Unix epoch time, ma questo non è necessario quando si inviano gli ID di traccia W3C in formato X-Ray.

È possibile scrivere uno script per generare ID di traccia X-Ray per i test. Qui di seguito sono riportati due esempi.

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"

Vedi l'applicazione di esempio Scorekeep per gli script che creano ID di traccia e inviano segmenti al demone X-Ray.

• Python: xray_start.py

• Bash — xray_start.sh

Usando PutTraceSegments

Puoi caricare i documenti di segmento tramite l'API PutTraceSegments. L'API dispone di un singolo parametro, TraceSegmentDocuments, che richiede un elenco di documenti di segmento in formato JSON.

Con l'AWS CLI, usa il aws xray put-trace-segments comando per inviare documenti di segmento direttamente a 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": []
}

Nota

Windows Command Processor e Windows PowerShell hanno requisiti diversi per la citazione e l'escape delle virgolette nelle stringhe JSON. Per i dettagli, consulta Utilizzo delle virgolette nelle stringhe nella Guida per l'utente della AWS CLI .

L'output elenca tutti i segmenti per i quali l'elaborazione non è riuscita. Ad esempio, se la data nell'ID di tracciamento è troppo remota nel passato, verrà visualizzato un errore come il seguente.

{
    "UnprocessedTraceSegments": [
        {
            "ErrorCode": "InvalidTraceId",
            "Message": "Invalid segment. ErrorCode: InvalidTraceId",
            "Id": "6226467e3f845502"
        }
    ]
}

Puoi passare più documenti di segmento insieme, separati da spazi.

$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"

Invio di documenti di segmento al demone X-Ray

Invece di inviare documenti di segmento all'API X-Ray, puoi inviare segmenti e sottosegmenti al demone X-Ray, che li memorizzerà nel buffer e li caricherà sull'API X-Ray in batch. L'X-Ray SDK invia i documenti dei segmenti al demone per evitare di effettuare chiamate dirette. AWS

Nota

Per istruzioni sull'esecuzione del daemon, consulta Esecuzione locale del demone X-Ray.

Invia il segmento in formato JSON tramite la porta UDP 2000, anteponendo l'intestazione per il daemon, {"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"}

Su Linux, puoi inviare documenti di segmento al daemon tramite un terminale Bash. Salva l'intestazione e il documento di segmento in un file di testo e reindirizzalo verso /dev/udp con cat.

$ cat segment.txt > /dev/udp/127.0.0.1/2000

Esempio 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"}

Controlla il registro del demone per verificare che abbia inviato il segmento a 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)