Senden von Ablaufverfolgungsdaten an AWS X-Ray

Sie können Ablaufverfolgungsdaten in Form von Segmentdokumenten an X-Ray senden. Ein Segmentdokument ist eine JSON-formatierte Zeichenfolge mit Informationen über die Arbeit, die Ihre Anwendung im Dienste einer Anforderung verrichtet. Ihre Anwendung kann Daten über die Arbeit, die sie selbst in Segmenten verrichtet, oder über Arbeit, die Downstream-Services und -Ressourcen in Untersegmenten verrichtet, aufzeichnen.

Segmente zeichnen Informationen über die Arbeit auf, die Ihre Anwendung verrichtet. Ein Segment zeichnet mindestens die für eine Aufgabe aufgewendete zeit, ihren Namen sowie zwei IDs auf. Die Nachverfolgungs-ID zeichnet die Anforderung auf Ihrem Weg zwischen den Services auf. Die Segment-ID verfolgt die für die Anforderung durch einen einzelnen Service verrichtete Arbeit.

Beispiel Minimales vollständiges Segment

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

Wenn eine Anfrage empfangen wird, können Sie eine In-Progress-Segment als Platzhalter senden, bis die Anforderung abgeschlossen ist.

Beispiel In Bearbeitung befindliches Segment

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

Sie können Segmente direkt, mit PutTraceSegmentsoder über den X-Ray-Daemon an X-Ray senden.

Die meisten Anwendungen rufen andere -Services auf oder greifen mit dem AWS SDK auf -Ressourcen zu. Aufzeichnen von Informationen zu nachgelagerten Aufrufen in Teilsegmenten . X-Ray verwendet Teilsegmente, um nachgelagerte Services zu identifizieren, die keine Segmente senden, und um Einträge für sie im Servicediagramm zu erstellen.

Ein Untersegment kann in einem vollständigen Segmentdokument eingebettet oder separat gesendet werden. Senden Sie Teilsegmente separat, um nachgelagerte Aufrufe für lang andauernde Anforderungen asynchron nachzuverfolgen oder um zu vermeiden, dass die maximale Segmentdokumentgröße (64 kB) überschritten wird.

Beispiel Untersegment

Ein Untersegment hat den type subsegment und eine parent_id, mit der das übergeordnete Segment identifiziert wird.

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

Weitere Informationen über die Felder und Werte, die in Segmente und Untersegmente eingegeben werden können, finden Sie unter AWS X-Ray Dokumente segmentieren.

Erzeugen von Ablaufverfolgungs-IDs

Um Daten an X-Ray zu senden, müssen Sie für jede Anforderung eine eindeutige Ablaufverfolgungs-ID generieren.

X-Ray-Trace-ID-Format

Ein X-Ray trace_id besteht aus drei Zahlen, die durch Bindestriche getrennt sind. Beispiel: 1-58406520-a006649127e371903a2de979 Dies umfasst:

• Die Versionsnummer, 1.

• Die Uhrzeit der ursprünglichen Anforderung in Unix-Epochenzeit mit 8 Hexadezimalziffern.

  Beispielsweise beträgt 10:00 Uhr am 1. Dezember 2016 PST in der Epochenzeit 1480615200 Sekunden oder 58406520 Hexadezimalziffern.

• Eine global eindeutige 96-Bit-Kennung für die Ablaufverfolgung in 24 Hexadezimalziffern.

Anmerkung

X-Ray unterstützt jetzt Ablaufverfolgungs-IDs, die mit erstellt werden, OpenTelemetry und jedes andere Framework, das der W3C Trace Context-Spezifikation entspricht. Eine W3C-Trace-ID muss beim Senden an X-Ray im X-Ray-Trace-ID-Format formatiert werden. Beispielsweise 4efaaf4d1e8720b39541901950019ee5 sollte die W3C-Trace-ID beim 1-4efaaf4d-1e8720b39541901950019ee5 Senden an X-Ray so formatiert sein wie . X-Ray-Trace-IDs enthalten den ursprünglichen Anforderungszeitstempel in Unix-Epochenzeit, dies ist jedoch nicht erforderlich, wenn W3C-Trace-IDs im X-Ray-Format gesendet werden.

Sie können ein Skript schreiben, um X-Ray-Ablaufverfolgungs-IDs zu Testzwecken zu generieren. Nachfolgend finden Sie zwei Beispiele.

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"

Weitere Informationen finden Sie in der Scorekeep-Beispielanwendung für Skripts, die Ablaufverfolgungs-IDs erstellen und Segmente an den X-Ray-Daemon senden.

• Python – xray_start.py

• Bash – xray_start.sh

Verwenden von PutTraceSegments

Sie können Segmentdokumente mit der PutTraceSegments-API hochladen. Die API hat einen einzelnen Parameter, TraceSegmentDocuments, der eine Liste von JSON-Segmentdokumenten aufnimmt.

Verwenden Sie mit der AWS CLI den aws xray put-trace-segments Befehl , um Segmentdokumente direkt an X-Ray zu senden.

$ 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": []
}

Anmerkung

Windows Command Processor und Windows PowerShell haben unterschiedliche Anforderungen für Anführungszeichen und Escape-Anführungszeichen in JSON-Zeichenfolgen. Weitere Details finden Sie unter Setzen von Anführungszeichen für Zeichenfolgen im AWS CLI -Benutzerhandbuch.

Die Ausgabe führt alle Segmente auf, deren Verarbeitung fehlgeschlagen ist. Beispiel: Wenn das Datum in der Nachverfolgungs-ID zu weit in der Vergangenheit liegt, sehen Sie eine Fehlermeldung wie die folgende.

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

Sie können mehrere Segmentdokumente gleichzeitig, durch Leerräume getrennt, weitergeben.

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

Senden von Segmentdokumenten an den X-Ray-Daemon

Anstatt Segmentdokumente an die X-Ray-API zu senden, können Sie Segmente und Untersegmente an den X-Ray-Daemon senden, der sie puffert und in Batches auf die X-Ray-API hochlädt. Das X-Ray SDK sendet Segmentdokumente an den Daemon, um direkte Aufrufe von zu AWS vermeiden.

Anmerkung

Informationen zur Ausführung des Daemons finden Sie unter Lokales X-Ray -Daemon.

Senden Sie das Segment in JSON über den UDP-Port 2000 mit dem vorangestellten Daemon-Kopf {"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"}

Unter Linux können Sie Segmentdokumente von einem Bash-Terminal aus an den Daemon senden. Speichern Sie den Kopf und das Segmentdokument in einer Textdatei, und senden Sie sie an /dev/udp mit cat.

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

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

Überprüfen Sie das Daemon-Protokoll, um zu überprüfen, ob es das Segment an X-Ray gesendet hat.

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)