Puede enviar datos de rastro a X-Ray en forma de documentos de segmento. Un documento de segmento es una cadena con formato JSON que contiene información sobre el trabajo que su aplicación realiza en respuesta a una solicitud. La aplicación puede registrar en segmentos los datos sobre el trabajo que realiza o bien registrar en subsegmentos los datos sobre el trabajo que utiliza servicios y recursos posteriores.
Los segmentos contienen información sobre el trabajo que realiza su aplicación. Un segmento, como mínimo, registra el tiempo empleado en una tarea, un nombre y dos ID. El ID de rastro permite controlar la solicitud mientras va de un servicio a otro. El ID de segmento permite controlar el trabajo que realiza un único servicio para la solicitud.
ejemplo Segmento completo mínimo
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
Cuando se recibe una solicitud, puede enviar un segmento en curso como marcador hasta que se complete la solicitud.
ejemplo Segmento en curso
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
Puede enviar los segmentos a X-Ray directamente con PutTraceSegments o a través del daemon de X-Ray.
La mayoría de las aplicaciones llaman a otros servicios u obtienen acceso a los recursos con el SDK de AWS. Registre información acerca de las llamadas posteriores en subsegmentos. X-Ray utiliza subsegmentos para identificar los servicios posteriores que no envían segmentos y crean entradas para segmentos en el gráfico de servicios.
Un subsegmento puede incrustarse en un documento de segmentos completos o enviarse por separado. Envíe subsegmentos por separado para realizar un rastreo asíncrono de las llamadas posteriores para realizar solicitudes de larga ejecución o para evitar superar el tamaño máximo del documento de segmentos (64 kB).
ejemplo Subsegmento
Un subsegmento tiene un type
de subsegment
y una parent_id
que identifica el segmento de origen.
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
Para obtener más información acerca de los campos y valores que puede incluir en los segmentos y subsegmentos, consulte Documentos de segmentos de AWS X-Ray.
Secciones
Generación de identificadores de seguimiento
Para enviar datos a X-Ray, debe generar un ID de rastro único para cada solicitud.
Formato de ID de rastro de X-Ray
Un trace_id
de X-Ray consta de tres números separados por guiones. Por ejemplo, 1-58406520-a006649127e371903a2de979
. Esto incluye:
-
El número de versión, que es
1
. -
La hora en que se realizó la solicitud original, en formato de tiempo Unix, en 8 dígitos hexadecimales.
Por ejemplo, las 10:00 del 1 de diciembre de 2016, PST en formato de tiempo Unix es
1480615200
segundos o58406520
en formato hexadecimal. -
Un identificador 96 bits del rastro, único a nivel global, en 24 dígitos hexadecimales.
nota
Ahora X-Ray admite ID de rastro creados mediante OpenTelemetry o cualquier otro marco que se ajuste a la especificación Trace Context de W3C4efaaf4d1e8720b39541901950019ee5
conforme a la especificación de W3C debe tener el formato 1-4efaaf4d-1e8720b39541901950019ee5
cuando se envíe a X-Ray. Si bien los ID de rastro de X-Ray incluyen la marca de tiempo de la solicitud original en formato de tiempo Unix, no es obligatorio cuando se envían ID de rastro conforme a la especificación de W3C en el formato de X-Ray.
Puede escribir un script con el fin de generar ID de rastro para pruebas. A continuación se incluyen dos ejemplos.
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"
Consulte la aplicación de muestra de Scorekeep para scripts que crean ID de rastro y envían segmentos al daemon de X-Ray.
-
Python:
xray_start.py
-
Bash:
xray_start.sh
Uso de PutTraceSegments
Puede cargar documentos de segmento con la API de PutTraceSegments
. La API tiene un único parámetro, TraceSegmentDocuments
, que obtiene una lista de documentos de segmento JSON.
Con la CLI de AWS, utilice el comando aws xray put-trace-segments
para enviar documentos de segmento directamente 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
El procesador de comandos de Windows y Windows PowerShell tienen requisitos diferentes para añadir comillas o comillas con caracteres de escape en cadenas JSON. Consulte Entrecomillado de cadenas en la Guía del usuario de la AWS CLI para obtener más información.
En la salida se indican los segmentos que no se han procesado correctamente; por ejemplo, si la fecha del ID de rastro es demasiado antigua, verá un error como el siguiente.
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
Puede transferir varios documentos de segmento al mismo tiempo, separados por espacios.
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
Envío de documentos de segmento al daemon de X-Ray
En lugar de enviar documentos de segmento a la API de X-Ray, puede enviar segmentos y subsegmentos al daemon de X-Ray, que se encargará de almacenarlos en búfer y cargarlos en la API de X-Ray en lotes. El SDK de X-Ray envía documentos de segmento al daemon para evitar llamar directamente a AWS.
nota
Consulte Ejecución del daemon de X-Ray localmente para obtener instrucciones sobre cómo ejecutar el demonio.
Envíe el segmento en formato JSON a través del puerto UDP 2000, anteponiéndole el encabezado del demonio, {"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"}
En Linux, puede enviar documentos de segmento al demonio desde un terminal Bash. Guarde el encabezado y el documento de segmento en un archivo de texto y envíelo a /dev/udp
con cat
.
$ cat segment.txt > /dev/udp/127.0.0.1/2000
ejemplo 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"}
Consulte el registro del daemon para comprobar que ha enviado el 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)