Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
Verwenden Sie die X-Ray-API
Wenn das X-Ray-SDK Ihre Programmiersprache nicht unterstützt, können Sie entweder die X-Ray-APIs direkt oder die AWS Command Line Interface (AWS CLI) verwenden, um X-Ray-API-Befehle aufzurufen. Wählen Sie anhand der folgenden Anleitung aus, wie Sie mit der API interagieren möchten:
-
Verwenden Sie die AWS CLI einfachere Syntax mit vorformatierten Befehlen oder mit Optionen in Ihrer Anfrage.
-
Verwenden Sie die X-Ray-API direkt für maximale Flexibilität und Anpassung bei Anfragen, die Sie an X-Ray stellen.
Wenn Sie die X-Ray-API direkt anstelle von verwenden AWS CLI, müssen Sie Ihre Anfrage im richtigen Datenformat parametrisieren und möglicherweise auch die Authentifizierung und Fehlerbehandlung konfigurieren.
Das folgende Diagramm zeigt eine Anleitung zur Auswahl der Interaktion mit der X-Ray-API:
Verwenden Sie die X-Ray-API, um Trace-Daten direkt an X-Ray zu senden. Die X-Ray-API unterstützt alle im X-Ray-SDK verfügbaren Funktionen, einschließlich der folgenden allgemeinen Aktionen:
-
PutTraceSegments— Lädt Segmentdokumente auf X-Ray hoch.
-
BatchGetTraces— Ruft eine Liste von Traces in einer Liste von Trace-IDs ab. Jeder abgerufene Trace ist eine Sammlung von Segmentdokumenten aus einer einzigen Anfrage.
-
GetTraceSummaries— Ruft IDs und Anmerkungen für Traces ab. Sie können a angeben
FilterExpression, um eine Teilmenge der Trace-Zusammenfassungen abzurufen. -
GetTraceGraph— Ruft ein Service-Diagramm für eine bestimmte Trace-ID ab.
-
GetServiceGraph— Ruft ein JSON formatiertes Dokument ab, das Dienste beschreibt, die eingehende Anfragen verarbeiten und nachgelagerte Anfragen aufrufen.
Sie können auch das AWS Command Line Interface (AWS CLI) in Ihrem Anwendungscode verwenden, um programmgesteuert mit X-Ray zu interagieren. Das AWS CLI unterstützt alle Funktionen, die im X-Ray SDK verfügbar sind, einschließlich der Funktionen für andere AWS-Services. Die folgenden Funktionen sind Versionen der zuvor aufgeführten API-Operationen mit einem einfacheren Format:
-
put-trace-segments
— Lädt Segmentdokumente auf X-Ray hoch. -
batch-get-traces
— Ruft eine Liste von Traces in einer Liste von Trace-IDs ab. Jeder abgerufene Trace ist eine Sammlung von Segmentdokumenten aus einer einzigen Anfrage. -
get-trace-summaries
— Ruft IDs und Anmerkungen für Traces ab. Sie können a angeben FilterExpression, um eine Teilmenge der Trace-Zusammenfassungen abzurufen. -
get-trace-graph
— Ruft ein Service-Diagramm für eine bestimmte Trace-ID ab. -
get-service-graph
— Ruft ein JSONformatiertes Dokument ab, das Dienste beschreibt, die eingehende Anfragen verarbeiten und nachgelagerte Anfragen aufrufen.
Um zu beginnen, müssen Sie das AWS CLIfür Ihr Betriebssystem installieren. AWS LinuxUnterstützungen macOS und Windows Betriebssysteme. Weitere Informationen zur Liste der X-Ray-Befehle finden Sie in der AWS CLI Befehlsreferenz für X-Ray
Erkunden Sie die X-Ray-API
Die X-Ray-API bietet Zugriff auf alle X-Ray-Funktionen über das AWS SDK oder direkt über HTTPS. AWS Command Line Interface Die X-Ray-API-Referenz dokumentiert Eingabeparameter für jede API-Aktion sowie die Felder und Datentypen, die sie zurückgeben.
Sie können das AWS SDK verwenden, um Programme zu entwickeln, die die X-Ray-API verwenden. Die X-Ray-Konsole und der X-Ray-Daemon verwenden beide das AWS SDK, um mit X-Ray zu kommunizieren. Das AWS SDK für jede Sprache enthält ein Referenzdokument für Klassen und Methoden, die X-Ray-API-Aktionen und -Typen zugeordnet sind.
AWS SDK-Referenzen
-
Java — AWS SDK for Java
-
JavaScript – AWS SDK for JavaScript
-
.NET – AWS SDK for .NET
-
Ruby – AWS SDK for Ruby
-
Go — AWS SDK for Go
-
PHP – AWS SDK for PHP
-
Python – AWS SDK for Python (Boto)
Das AWS Command Line Interface ist ein Befehlszeilentool, das das SDK für Python verwendet, um AWS APIs aufzurufen. Wenn Sie sich zum ersten Mal mit einer AWS API vertraut AWS CLI machen, können Sie auf einfache Weise die verfügbaren Parameter erkunden und die Serviceausgabe in JSON- oder Textform anzeigen.
Einzelheiten zu aws xray Unterbefehlen finden Sie in der AWS CLI Befehlsreferenz.
Über die AWS CLI können Sie direkt auf den X-Ray-Dienst zugreifen und dieselben APIs verwenden, die die X-Ray-Konsole zum Abrufen des Service-Graphen und der Trace-Rohdaten verwendet. Die Beispielanwendung enthält Skripts, die zeigen, wie diese APIs mit der AWS CLI verwendet werden.
Voraussetzungen
In diesem Tutorial werden die Scorekeep-Beispielanwendung und darin enthaltene Skripts verwendet, um Ablaufverfolgungsdaten und eine Service-Übersicht zu erstellen. Folgen Sie den Anweisungen im Tutorial zur Beispielanwendung, um die Anwendung zu starten.
In diesem Tutorial wird AWS CLI die grundlegende Verwendung der X-Ray-API veranschaulicht. Die AWS CLI, verfügbar für Windows, Linux und OS-X, bietet Befehlszeilenzugriff auf die öffentlichen APIs für alle AWS-Services.
Anmerkung
Sie müssen sicherstellen, dass Ihre für dieselbe Region konfiguriert AWS CLI ist, in der Ihre Beispielanwendung erstellt wurde.
Die enthaltenen Skripts zum Testen der Beispielanwendung verwenden cURL, um Datenverkehr zur API zu senden, und jq zum Analysieren der Ausgabe. Sie können die ausführbare jq-Datei von stedolan.github.iocurl-Datei von https://curl.haxx.se/download.html
Generieren von Ablaufverfolgungsdaten
Die Web-App generiert weiterhin alle paar Sekunden Datenverkehr zur API, während das Spiel fortgesetzt wird, es wird aber nur eine Art der Anforderung generiert. Verwenden Sie das Skript test-api.sh, um End-to-End-Szenarien auszuführen und um während der Prüfung der API vielfältigere Ablaufverfolgungsdaten zu generieren.
So verwenden Sie das test-api.sh-Skript
In der Elastic-Beanstalk-Konsole
öffnen. Navigieren Sie zur Managementkonsole für Ihre Umgebung.
-
Kopieren Sie die Umgebungs-URL aus dem Header der Seite.
-
Öffnen Sie
bin/test-api.shund ersetzen Sie den Wert für die API mit der URL Ihrer Umgebung.#!/bin/bash API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api -
Führen Sie das Skript aus, um Datenverkehr zur API zu generieren.
~/debugger-tutorial$./bin/test-api.shCreating users, session, game, configuring game, playing game, ending game, game complete. {"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
Verwenden Sie die X-Ray-API
Die AWS CLI stellt Befehle für alle API-Aktionen bereit, die X-Ray bereitstellt, einschließlich GetServiceGraphund GetTraceSummaries. Weitere Informationen über alle unterstützten Aktionen und die von ihnen verwendeten Datentypen finden Sie in der AWS X-Ray -API-Referenz.
Beispiel bin/service-graph.sh
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCHDas Skript ruft ein Service-Diagramm für die letzten 10 Minuten ab.
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...Beispiel bin/trace-urls.sh
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'Das Skript ruft die URLs der Ablaufverfolgungen ab, die ein bis zwei Minuten zuvor generiert wurden.
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]Beispiel bin/full-traces.sh
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'Das Skript ruft die vollständigen Ablaufverfolgungsdaten ab, die ein bis zwei Minuten zuvor generiert wurden.
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
Bereinigen
Beenden Sie Ihre Elastic Beanstalk Beanstalk-Umgebung, um die Amazon EC2 EC2-Instances, DynamoDB-Tabellen und andere Ressourcen herunterzufahren.
So beenden Sie die Elastic Beanstalk-Umgebung
In der Elastic-Beanstalk-Konsole
öffnen. Navigieren Sie zur Management-Konsole für Ihre Umgebung.
-
Wählen Sie Aktionen.
-
Wählen Sie Terminate Environment.
-
Wähen Sie Beenden.
Trace-Daten werden nach 30 Tagen automatisch aus X-Ray gelöscht.
Sie können Trace-Daten 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 oder über den PutTraceSegmentsX-Ray-Daemon an X-Ray senden.
Die meisten Anwendungen rufen mit dem AWS SDK andere Dienste auf oder greifen auf Ressourcen zu. Zeichnen Sie Informationen über Downstream-Aufrufe in Untersegmenten auf. X-Ray verwendet Untersegmente, um Downstream-Services zu identifizieren, die keine Segmente senden, und Einträge für sie im Service-Graph zu erstellen.
Ein Untersegment kann in einem vollständigen Segmentdokument eingebettet oder separat gesendet werden. Senden Sie Untersegmente separat, um Downstream-Aufrufe für lang andauernde Anfragen asynchron zu verfolgen oder um zu verhindern, 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 Dokumente für Röntgensegmente.
Um Daten an X-Ray zu senden, müssen Sie für jede Anfrage eine eindeutige Trace-ID generieren.
Röntgen-Trace-ID-Format
Ein X-Ray trace_id besteht aus drei Zahlen, die durch Bindestriche getrennt sind. z. B. 1-58406520-a006649127e371903a2de979. Dies umfasst:
-
Die Versionsnummer, die ist.
1 -
Die Uhrzeit der ursprünglichen Anfrage in Unix-Epochenzeit unter Verwendung von 8 Hexadezimalziffern.
Zum Beispiel ist 10:00 Uhr am 1. Dezember 2016 PST in Epochenzeit
1480615200Sekunden oder58406520in Hexadezimalziffern. -
Eine weltweit eindeutige 96-Bit-ID für den Trace mit 24 Hexadezimalziffern.
Anmerkung
X-Ray unterstützt jetzt Trace-IDs, die mit OpenTelemetry und jedem anderen Framework erstellt wurden, das der W3C Trace Context-Spezifikation4efaaf4d1e8720b39541901950019ee5 sollte die W3C-Trace-ID wie 1-4efaaf4d-1e8720b39541901950019ee5 beim Senden an X-Ray formatiert werden. X-Ray-Trace-IDs enthalten den ursprünglichen Anforderungszeitstempel in der 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-Trace-IDs für Tests 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"In der Beispielanwendung Scorekeep finden Sie Skripte, die Trace-IDs erstellen und Segmente an den X-Ray-Daemon senden.
-
Python –
xray_start.py -
Bash —
xray_start.sh
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 das Anführungszeichen und das Maskieren von Anführungszeichen in JSON-Zeichenketten. 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"Anstatt Segmentdokumente an die X-Ray-API zu senden, können Sie Segmente und Untersegmente an den X-Ray-Daemon senden, der sie zwischenspeichert und stapelweise auf die X-Ray-API hochlädt. Das X-Ray-SDK sendet Segmentdokumente an den Daemon, um AWS direkte Aufrufe zu vermeiden.
Anmerkung
Informationen zur Ausführung des Daemons finden Sie unter Lokales Ausführen des X-Ray-Daemons.
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/2000Beispiel 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 sicherzustellen, dass das Segment an X-Ray gesendet wurde.
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)X-Ray verarbeitet die Trace-Daten, die Sie an X-Ray senden, um vollständige Traces, Trace-Zusammenfassungen und Service-Diagramme in JSON zu generieren. Sie können die generierten Daten mit der AWS CLI direkt von der API abrufen.
Sie können die API GetServiceGraph verwenden, um das JSON-Service-Diagramm abzurufen. Die API erfordert eine Start- und Endzeit. Sie können diese mit dem date-Befehl an einem Linux-Terminal berechnen.
$ date +%s
1499394617date +%s druckt ein Datum in Sekunden. Verwenden Sie diese Zahl als Endzeit. Ziehen Sie Zeit ab, um eine Startzeit zu erhalten.
Beispiel Script, um ein Service-Diagramm für die letzten 10 Minuten abzurufen
EPOCH=$(date +%s) aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
Das folgende Beispiel zeigt ein Service-Diagramm mit 4 Knoten, darunter einen Client-Knoten, eine EC2-Instance, eine DynamoDB-Tabelle und ein Amazon SNS SNS-Thema.
Beispiel GetServiceGraph Ausgabe
{ "Services": [ { "ReferenceId": 0, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Type": "client", "State": "unknown", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 2, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "Aliases": [] } ] }, { "ReferenceId": 1, "Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA", "Names": [ "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA" ], "Type": "AWS::DynamoDB::Table", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "DurationHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ] }, { "ReferenceId": 2, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Root": true, "Type": "AWS::EC2::Instance", "State": "active", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 1, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "Aliases": [] }, { "ReferenceId": 3, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "Aliases": [] } ], "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "DurationHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ] }, { "ReferenceId": 3, "Name": "SNS", "Names": [ "SNS" ], "Type": "AWS::SNS", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "DurationHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ] } ] }
Zum Abrufen eines Service-Diagramms basierend auf dem Inhalt einer Gruppe geben Sie einen groupName oder groupARN an. Das folgende Beispiel zeigt einen Service-Diagrammaufruf einer Gruppe mit dem Namen Example1.
Beispiel Skript zum Abrufen eines Service-Diagramms nach Name für die Gruppe Example1
aws xray get-service-graph --group-name "Example1"
Sie können die API GetTraceSummaries verwenden, um eine Liste von Ablaufverfolgungsübersichten abzurufen. Ablaufverfolgungsübersichten enthalten Informationen, mit denen Sie Ablaufverfolgungen identifizieren können, die Sie vollständig herunterladen möchten, einschließlich Anmerkungen, Informationen zu Anforderung und Reaktion sowie IDs.
Beim Aufruf von aws xray
get-trace-summaries stehen zwei TimeRangeType- Flags zur Verfügung:
-
TraceId— Die
GetTraceSummariesStandardsuche verwendet die TraceID-Zeit und gibt Traces zurück, die innerhalb des berechneten[start_time, end_time)Bereichs gestartet wurden. Dieser Bereich von Zeitstempeln wird auf der Grundlage der Kodierung des Zeitstempels innerhalb von berechnet oder kann TraceId manuell definiert werden. -
Ereigniszeit — Um nach Ereignissen zu suchen, die sich im Laufe der Zeit ereignen, ermöglicht AWS X-Ray die Suche nach Spuren mithilfe von Ereigniszeitstempeln. Die Ereigniszeit gibt Traces zurück, die während des
[start_time, end_time)-Bereichs aktiv sind, unabhängig davon, wann der Trace begonnen hat.
Mit dem Befehl aws xray get-trace-summaries können Sie eine Liste von Ablaufverfolgungsübersichten abrufen. Die folgenden Befehle rufen unter Verwendung der TraceId Standardzeit eine Liste von Trace-Zusammenfassungen ab, die zwischen 1 und 2 Minuten zurückliegen.
Beispiel Skript zum Abrufen von Ablaufverfolgungsübersichten
EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
Beispiel GetTraceSummaries Ausgabe
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}Mithilfe der Ablaufverfolgungs-ID aus der Ausgabe können Sie mit der API BatchGetTraces eine vollständige Ablaufverfolgung abrufen.
Beispiel BatchGetTraces Befehl
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6bBeispiel BatchGetTraces Ausgabe
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}Die vollständige Ablaufverfolgung umfasst ein Dokument für jedes Segment, das aus allen Segmentdokumenten kompiliert wurde, die mit der gleichen Ablaufverfolgungs-ID erhalten wurden. Diese Dokumente stellen nicht die Daten dar, wie sie durch Ihre Anwendung an X-Ray gesendet wurden. Stattdessen stellen sie die verarbeiteten Dokumente dar, die vom X-Ray-Dienst generiert wurden. X-Ray erstellt das vollständige Trace-Dokument, indem es die von Ihrer Anwendung gesendeten Segmentdokumente kompiliert und Daten entfernt, die nicht dem Segmentdokumentschema entsprechen. Weitere Informationen finden Sie unter Dokumente für Röntgensegmente.
X-Ray erstellt auch abgeleitete Segmente für Downstream-Aufrufe an Dienste, die selbst keine Segmente senden. Wenn Sie DynamoDB beispielsweise mit einem instrumentierten Client aufrufen, zeichnet das X-Ray-SDK ein Untersegment mit Details zum Aufruf aus seiner Sicht auf. DynamoDB sendet jedoch kein entsprechendes Segment. X-Ray verwendet die Informationen im Untersegment, um ein abgeleitetes Segment zu erstellen, das die DynamoDB-Ressource in der Trace-Map darstellt, und fügt es dem Trace-Dokument hinzu.
Um mehrere Traces von der API abzurufen, benötigen Sie eine Liste von Trace-IDs, die Sie mit einer Abfrage aus der get-trace-summaries Ausgabe extrahieren können.AWS CLI Leiten Sie die Liste zur Eingabe von batch-get-traces um, um vollständige Traces für einen bestimmten Zeitraum zu erhalten.
Beispiel Script, um vollständige Ablaufverfolgungen für den Zeitraum von einer Minute zu erhalten
EPOCH=$(date +%s) TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text) aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
Nach der Generierung einer Trace-Zusammenfassung mit der GetTraceSummaries API können unvollständige Trace-Zusammenfassungen in ihrem JSON-Format wiederverwendet werden, um einen verfeinerten Filterausdruck zu erstellen, der auf den Grundursachen basiert. In den nachstehenden Beispielen finden Sie eine exemplarische Vorgehensweise für die Optimierungsschritte.
Beispiel GetTraceSummaries Beispielausgabe — Abschnitt zur Hauptursache bei der Antwortzeit
{ "Services": [ { "Name": "GetWeatherData", "Names": ["GetWeatherData"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [ { "Name": "GetWeatherData", "Coverage": 1.0, 'Remote": false }, { "Name": "get_temperature", "Coverage": 0.8, "Remote": false } ] }, { "Name": "GetTemperature", "Names": ["GetTemperature"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [ { "Name": "GetTemperature", "Coverage": 0.7, "Remote": false } ] } ] }
Durch das Bearbeiten und Vornehmen von Auslassungen der oben genannten Ausgaben kann dieses JSON-Objekt ein Filter für übereinstimmende Ursachenentitäten werden. Für jedes Feld im JSON-Objekt müssen alle Bewerberabgleiche exakt erfolgen. Andernfalls wird die Nachverfolgung nicht zurückgegeben. Entfernte Felder werden zu Platzhalterwerten, ein Format, das mit der Abfragestruktur des Filterausdrucks kompatibel ist.
Beispiel Reaktionszeit „Ursache“ neu formatiert
{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [ { "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }
Dieses JSON-Objekt wird dann als Teil eines Filterausdrucks durch einen Aufruf von rootcause.json = #[{}] verwendet. Weitere Informationen zur Abfrage mit Filterausdrücken finden Sie im Abschnitt Verwenden von Filterausdrücken unter Erkunden der X-Ray-Konsole.
Beispiel für JSON-Filter
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
X-Ray bietet APIs für die Konfiguration von Sampling-Regeln, Gruppenregeln und Verschlüsselungseinstellungen.
Verschlüsselungseinstellungen
Dient PutEncryptionConfigzur Angabe eines AWS Key Management Service (AWS KMS) -Schlüssels, der für die Verschlüsselung verwendet werden soll.
Anmerkung
X-Ray unterstützt keine asymmetrischen KMS-Schlüssel.
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}Für die Schlüssel-ID können Sie einen Alias verwenden (wie im Beispiel gezeigt), eine Schlüssel-ID oder einen Amazon-Ressourcennamen (ARN).
Verwenden Sie GetEncryptionConfig, um die aktuelle Konfiguration abzurufen. Wenn X-Ray die Übernahme Ihrer Einstellungen abgeschlossen hat, ändert sich der Status von UPDATING zuACTIVE.
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}Um die Verwendung eines KMS-Schlüssels zu beenden und die Standardverschlüsselung zu verwenden, setzen Sie den Verschlüsselungstyp aufNONE.
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}Sie können die Sampling-Regeln in Ihrem Konto mit der X-Ray-API verwalten. Weitere Informationen zur Probenahme finden Sie unterKonfigurieren Sie Stichprobenregeln. Weitere Informationen zum Hinzufügen und Verwalten von Tags finden Sie unterKennzeichnen von Regeln und Gruppen für die Röntgenprobenahme.
Sie können alle Samplingregeln mit GetSamplingRules abrufen.
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}Die Standardregel gilt für alle Anfragen, die nicht mit einer anderen Regel übereinstimmen. Es ist die Regel mit der niedrigsten Priorität, die nicht gelöscht werden kann. Sie können jedoch die Rate und die Reservoirgröße mit UpdateSamplingRule ändern.
Beispiel API-Eingabe für UpdateSamplingRule— 10000-default.json
{ "SamplingRuleUpdate": { "RuleName": "Default", "FixedRate": 0.01, "ReservoirSize": 0 } }
Das folgende Beispiel verwendet die vorherige Datei als Eingabe, um die Standardregel in ein Prozent ohne Reservoir zu ändern. Tags sind optional. Wenn Sie Tags hinzufügen möchten, ist ein Tag-Schlüssel erforderlich, und Tag-Werte sind optional. Um vorhandene Tags aus einer Stichprobenregel zu entfernen, verwenden Sie UntagResource.
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
Erstellen Sie zusätzliche Samplingregeln mit CreateSamplingRule. Wenn Sie eine Regel erstellen, sind die meisten Regelfelder erforderlich. Das folgende Beispiel erstellt zwei Regeln. Diese erste Regel legt einen Basissatz für die Scorekeep-Beispielanwendung fest. Er entspricht allen Anforderungen, die von der API bereitgestellt werden, die nicht mit einer höheren Priorität übereinstimmen.
Beispiel API-Eingabe für UpdateSamplingRule— 9000-base-scorekeep.json
{ "SamplingRule": { "RuleName": "base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1 } }
Die zweite Regel gilt auch für Scorekeep, hat aber eine höhere Priorität und ist spezifischer. Diese Regel enthält eine sehr niedrige Samplingrate für Polling-Anfragen. Dies sind GET-Anfragen, die der Client alle paar Sekunden sendet, um eine Prüfung auf Änderungen am Spielstatus durchzuführen.
Beispiel API-Eingabe für UpdateSamplingRule— 5000-polling-scorekeep.json
{ "SamplingRule": { "RuleName": "polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1 } }
Tags sind optional. Wenn Sie Tags hinzufügen möchten, ist ein Tag-Schlüssel erforderlich, und Tag-Werte sind optional.
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}Um eine Samplingregel zu löschen, verwenden Sie DeleteSamplingRule.
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}Sie können die X-Ray-API verwenden, um Gruppen in Ihrem Konto zu verwalten. Gruppen sind eine Sammlung von Ablaufverfolgungen, die durch einen Filterausdruck definiert sind. Sie können Gruppen verwenden, um zusätzliche Servicegraphen zu erstellen und CloudWatch Amazon-Metriken bereitzustellen. Weitere Informationen Daten von X-Ray abrufen zur Arbeit mit Servicediagrammen und Metriken über die X-Ray-API finden Sie unter. Weitere Informationen zu Gruppen finden Sie unterGruppen konfigurieren. Weitere Informationen zum Hinzufügen und Verwalten von Stichwörtern finden Sie unterKennzeichnen von Regeln und Gruppen für die Röntgenprobenahme.
Erstellen Sie eine Gruppe mit CreateGroup. Tags sind optional. Wenn Sie Tags hinzufügen möchten, ist ein Tag-Schlüssel erforderlich, und Tag-Werte sind optional.
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
Rufen Sie alle vorhandenen Gruppen mit GetGroups ab.
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}Aktualisieren Sie eine Gruppe mit UpdateGroup. Tags sind optional. Wenn Sie Tags hinzufügen möchten, ist ein Tag-Schlüssel erforderlich, und Tag-Werte sind optional. Um vorhandene Tags aus einer Gruppe zu entfernen, verwenden Sie UntagResource.
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
Löschen Sie eine Gruppe mit DeleteGroup.
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
Das X-Ray SDK verwendet die X-Ray-API, um Probenahmeregeln abzurufen, Probenahmeergebnisse zu melden und Kontingente abzurufen. Sie können diese APIs verwenden, um besser zu verstehen, wie Sampling-Regeln funktionieren, oder um Sampling in einer Sprache zu implementieren, die das X-Ray SDK nicht unterstützt.
Rufen Sie zunächst alle Samplingregeln mit GetSamplingRules ab.
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
Die Ausgabe enthält die Standardregel und benutzerdefinierte Regeln. Weitere Informationen finden Sie unter Konfiguration von Sampling-, Gruppen- und Verschlüsselungseinstellungen mit der X-Ray-API, wenn Sie noch keine Samplingregeln erstellt haben.
Bewerten Sie Regeln anhand eingehender Anfragen in aufsteigender Reihenfolge der Priorität. Wenn eine Regel übereinstimmt, verwenden Sie die feste Rate und eine feste Reservoirgröße, um eine Samplingentscheidung zu treffen. Zeichnen Sie die per Stichprobe geprüften Anforderungen auf und ignorieren Sie (für die Nachverfolgung) nicht geprüfte Anfragen. Beenden Sie die Bewertung der Regeln, wenn eine Samplingentscheidung getroffen wird.
Eine Regel-Reservoirgröße ist die Zielanzahl der Ablaufverfolgungen pro Sekunde, bevor Sie die feste Rate anwenden. Das Reservoir gilt kumulativ für alle Services, sodass Sie es nicht direkt verwenden können. Wenn sie jedoch ungleich Null ist, können Sie eine Spur pro Sekunde aus dem Reservoir ausleihen, bis X-Ray eine Quote zuweist. Vor dem Empfang eines Kontingents zeichnen Sie die erste Anfrage pro Sekunde auf und wenden die feste Rate auf zusätzliche Anfragen an. Die feste Rate ist ein Dezimalwert zwischen 0 und 1,00 (100 %).
Das folgende Beispiel zeigt einen Aufruf von GetSamplingTargets mit Details zu Samplingentscheidungen in den letzten 10 Sekunden.
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
Die Antwort von X-Ray beinhaltet ein Kontingent, das verwendet werden kann, anstatt Kredite aus dem Reservoir aufzunehmen. In diesem Beispiel hat sich der Service aus dem Reservoir 10 Ablaufverfolgungen über 10 Sekunden geliehen und die feste Rate von 10 % auf den anderen 100 Anfragen angewendet. Daraus ergeben sich 20 geprüfte Anfragen. Das Kontingent ist für fünf Minuten gültig (angegeben durch die Gültigkeitsdauer) oder bis ein neues Kontingent zugewiesen wird. X-Ray weist möglicherweise auch ein längeres Berichtsintervall als das Standardintervall zu, obwohl dies hier nicht der Fall war.
Anmerkung
Die Antwort von X-Ray enthält möglicherweise kein Kontingent, wenn Sie sie zum ersten Mal aufrufen. Leihen Sie weiterhin vom Reservoir, bis Sie ein Kontingent zugewiesen bekommen.
Die anderen zwei Felder in der Antwort können möglicherweise Konflikte mit der Eingabe anzeigen. Vergleichen Sie LastRuleModification mit dem letzten Aufruf von GetSamplingRules. Wenn er neuer ist, rufen Sie eine Kopie der Regeln ab. UnprocessedStatistics kann Fehler enthalten, die angeben, dass eine Regel gelöscht wurde, dass das Statistikdokument in der Eingabe zu alt war oder Berechtigungsfehler aufgetreten sind.
Ein Ablaufverfolgungssegment ist eine JSON-Darstellung einer Anfrage, die Ihrer Anwendung dient. Ein Trace-Segment zeichnet Informationen über die ursprüngliche Anfrage, Informationen über die Arbeit auf lokaler Ebene und Untersegmente mit Informationen über Downstream-Aufrufe auf, die Ihre Anwendung an AWS Ressourcen, HTTP-APIs und SQL-Datenbanken durchführt.
Ein Segmentdokument übermittelt Informationen über ein Segment an X-Ray. Ein Segmentdokument kann bis zu 64 kB groß sein und ein ganzes Segment mit Untersegmenten, ein Fragment eines Segments, das angibt, dass eine Anfrage bearbeitet wird, oder ein einzelnes Untersegment, das separat gesendet wird, enthalten. Mithilfe der PutTraceSegmentsAPI können Sie Segmentdokumente direkt an X-Ray senden.
X-Ray kompiliert und verarbeitet Segmentdokumente, um abfragbare Trace-Zusammenfassungen und vollständige Traces zu generieren, auf die Sie mithilfe der APIs bzw. der GetTraceSummariesAPIs zugreifen können. BatchGetTraces Zusätzlich zu den Segmenten und Untersegmenten, die Sie an X-Ray senden, verwendet der Service Informationen in Untersegmenten, um abgeleitete Segmente zu generieren, und fügt sie dem vollständigen Trace hinzu. Abgeleitete Segmente stellen nachgelagerte Dienste und Ressourcen in der Trace-Map dar.
X-Ray bietet ein JSON-Schema für Segmentdokumente. Sie können das Schema hier herunterladen: xray-segmentdocument-schema-v1.0.0. Die im Schema angegebenen Felder und Objekte werden in den folgenden Abschnitten genauer beschrieben.
Eine Teilmenge von Segmentfeldern wird von X-Ray für die Verwendung mit Filterausdrücken indexiert. Wenn Sie beispielsweise das user Feld in einem Segment auf eine eindeutige Kennung festlegen, können Sie in der X-Ray-Konsole oder mithilfe der GetTraceSummaries API nach Segmenten suchen, die bestimmten Benutzern zugeordnet sind. Weitere Informationen finden Sie unter Verwenden Sie Filterausdrücke.
Wenn Sie Ihre Anwendung mit dem X-Ray SDK instrumentieren, generiert das SDK Segmentdokumente für Sie. Anstatt Segmentdokumente direkt an X-Ray zu senden, überträgt das SDK sie über einen lokalen UDP-Port an den X-Ray-Daemon. Weitere Informationen finden Sie unter Segmentdokumente an den X-Ray-Daemon senden.
Ein Segment zeichnet Ablaufverfolgungsinformationen über eine Anforderung auf, die Ihrer Anwendung dient. Ein Segment zeichnet mindestens den Namen, die ID, die Anfangszeit, die Ablaufverfolgungs-ID und die Endzeit der Anforderung auf.
Beispiel Minimales vollständiges Segment
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}Die folgenden Felder sind für Segmente erforderlich oder in einigen Fällen notwendig.
Anmerkung
Der Wert muss aus Zeichenfolgen (bis zu 250 Zeichen) bestehen, soweit nicht anders angegeben.
Erforderliche Segmentfelder
-
name— Der logische Name des Dienstes, der die Anfrage bearbeitet hat, bis zu 200 Zeichen. Beispielsweise der Name der Anwendung oder Domäne. Namen dürfen Unicode-Buchstaben, -Ziffern und -Leerzeichen enthalten sowie die folgenden Symbole:_,.,:,/,%,&,#,=,+,\,-,@ -
id— Eine 64-Bit-ID für das Segment, die unter den Segmenten in derselben Spur eindeutig ist, mit 16 Hexadezimalziffern. -
trace_id— Eine eindeutige Kennung, die alle Segmente und Untersegmente verbindet, die aus einer einzigen Client-Anfrage stammen.Röntgen-Trace-ID-Format
Ein X-Ray
trace_idbesteht aus drei Zahlen, die durch Bindestriche getrennt sind. z. B.1-58406520-a006649127e371903a2de979. Dies umfasst:-
Die Versionsnummer, die ist.
1 -
Die Uhrzeit der ursprünglichen Anfrage in Unix-Epochenzeit unter Verwendung von 8 Hexadezimalziffern.
Zum Beispiel ist 10:00 Uhr am 1. Dezember 2016 PST in Epochenzeit
1480615200Sekunden oder58406520in Hexadezimalziffern. -
Eine weltweit eindeutige 96-Bit-ID für den Trace mit 24 Hexadezimalziffern.
Anmerkung
X-Ray unterstützt jetzt Trace-IDs, die mit OpenTelemetry und jedem anderen Framework erstellt wurden, 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 4efaaf4d1e8720b39541901950019ee5sollte die W3C-Trace-ID wie1-4efaaf4d-1e8720b39541901950019ee5beim Senden an X-Ray formatiert werden. X-Ray-Trace-IDs enthalten den ursprünglichen Anforderungszeitstempel in der Unix-Epochenzeit, dies ist jedoch nicht erforderlich, wenn W3C-Trace-IDs im X-Ray-Format gesendet werden.Sicherheit der Ablaufverfolgungs-ID
Ablaufverfolgungs-IDs sind in Antwortheadern sichtbar. Generieren Sie Ablaufverfolgungs-IDs mit einem sicheren Random-Algorithmus, um sicherzustellen, dass Angreifer zukünftige Ablaufverfolgungs-IDs nicht berechnen und keine Anforderungen mit diesen IDs an Ihre Anwendung senden können.
-
-
start_time— Zahl, die die Zeit angibt, zu der das Segment erstellt wurde, in Fließkommasekunden in Epochenzeit. Zum Beispiel1480615200.010oder1.480615200010E9. Verwenden Sie so viele Dezimalstellen, wie Sie benötigen. Mikrosekundenauflösung ist empfohlen, wenn verfügbar. -
end_time— Zahl, die die Zeit angibt, zu der das Segment geschlossen wurde. Zum Beispiel1480615200.090oder1.480615200090E9. Geben Sie entwederend_timeoderin_progressan. -
in_progress— boolescher Wert, auf gesetzt,trueanstatt anzugebenend_time, dass ein Segment gestartet, aber noch nicht abgeschlossen ist. Wenn Ihre Anwendung eine Anforderung empfängt, die lange dauern wird, senden Sie ein in Bearbeitung befindliches Segment, um den Empfang zu bestätigen. Wenn die Antwort gesendet wird, senden Sie das vollständige Segment zum Überschreiben des in Bearbeitung befindlichen Segments. Senden Sie pro Anforderung nur ein vollständiges Segment und ein oder kein angefangenes Segment.
Namen der Dienste
Der eines Segments name sollte mit dem Domainnamen oder dem logischen Namen des Dienstes übereinstimmen, der das Segment generiert. Dies wird jedoch nicht erzwungen. Jede Anwendung, die über die entsprechende Berechtigung verfügt, PutTraceSegmentskann Segmente mit einem beliebigen Namen senden.
Die folgenden Felder sind für Segmente optional.
Optionale Segmentfelder
-
service— Ein Objekt mit Informationen zu Ihrer Anwendung.-
version— Eine Zeichenfolge, die die Version Ihrer Anwendung identifiziert, die die Anfrage bearbeitet hat.
-
-
user— Eine Zeichenfolge, die den Benutzer identifiziert, der die Anfrage gesendet hat. -
origin— Der Typ der AWS Ressource, auf der Ihre Anwendung ausgeführt wird.Unterstützte Werte
-
AWS::EC2::Instance— Eine Amazon EC2 EC2-Instance. -
AWS::ECS::Container— Ein Amazon ECS-Container. -
AWS::ElasticBeanstalk::Environment— Eine Elastic Beanstalk Beanstalk-Umgebung.
Wenn mehrere Werte für Ihre Anwendung gelten, verwenden Sie den spezifischsten. In einer Multicontainer Docker Elastic Beanstalk Beanstalk-Umgebung wird Ihre Anwendung beispielsweise auf einem Amazon ECS-Container ausgeführt, der wiederum auf einer Amazon EC2 EC2-Instance läuft. In diesem Fall müssen Sie den Ursprung auf
AWS::ElasticBeanstalk::Environmentfestlegen, da die Umgebung das übergeordnete Element der beiden anderen Ressourcen ist. -
-
parent_id— Eine Subsegment-ID, die Sie angeben, wenn die Anfrage von einer instrumentierten Anwendung stammt. Das X-Ray-SDK fügt die ID des übergeordneten Untersegments zum Tracing-Header für Downstream-HTTP-Aufrufe hinzu. Bei verschachtelten Untersegmenten kann ein Untersegment ein Segment oder ein Untersegment als übergeordnetes Element haben. -
http— httpObjekte mit Informationen über die ursprüngliche HTTP-Anfrage. -
aws— awsObjekt mit Informationen über die AWS Ressource, auf der Ihre Anwendung die Anfrage bearbeitet hat. -
error,throttlefault, undcause— Fehlerfelder, die darauf hinweisen, dass ein Fehler aufgetreten ist, und die Informationen über die Ausnahme enthalten, die den Fehler verursacht hat. -
annotations— annotationsObjekt mit Schlüssel-Wert-Paaren, die X-Ray für die Suche indexieren soll. -
metadata— metadataObjekt mit allen zusätzlichen Daten, die Sie in dem Segment speichern möchten. -
subsegments— Anordnung von subsegmentObjekten.
Sie können Untersegmente erstellen, um Aufrufe AWS-Services und Ressourcen, die Sie mit dem AWS SDK tätigen, Aufrufe interner oder externer HTTP-Web-APIs oder SQL-Datenbankabfragen aufzuzeichnen. Sie können auch Untersegmente erstellen, um Code-Blöcke in Ihrer Anwendung zu debuggen oder zu kommentieren. Untersegmente können weitere Untersegmente enthalten, damit ein individuelles Untersegment, das Metadaten über einen internen Funktionsaufruf aufzeichnet, weitere individuelle Untersegmente sowie Untersegmente nachgelagerter Aufrufe umfassen kann.
Ein Untersegment zeichnet einen Downstream-Aufruf aus der Sicht des Dienstes auf, der ihn aufruft. X-Ray verwendet Untersegmente, um Downstream-Services zu identifizieren, die keine Segmente senden, und Einträge für sie im Service-Graph zu erstellen.
Ein Untersegment kann in einem vollständigen Segmentdokument eingebettet oder separat gesendet werden. Senden Sie Untersegmente separat, um nachgelagerte Aufrufe für lange andauernde Anforderungen asynchron nachzuverfolgen oder um zu verhindern, dass die maximale Größe des Segmentdokuments überschritten wird.
Beispiel Segment mit eingebettetem Untersegment
Ein unabhängiges Untersegment hat einen type vom subsegment und einen parent_id, der das übergeordnete Segment identifiziert.
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}Bei Anfragen mit langer Laufzeit können Sie ein Segment in Bearbeitung senden, um X-Ray darüber zu informieren, dass die Anfrage eingegangen ist, und dann Untersegmente separat senden, um sie zu verfolgen, bevor die ursprüngliche Anfrage abgeschlossen wird.
Beispiel In Bearbeitung befindliches Segment
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}Beispiel Unabhängiges Untersegment
Ein unabhängiges Untersegment hat einen type-subsegment, eine trace_id und eine parent_id, die das übergeordnete Segment identifiziert.
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}Schließen Sie das Segment nach Abschluss der Anforderung mit einer end_time. Das vollständige Segment überschreibt das sich in Bearbeitung befindliche Segment.
Sie können außerdem Untersegmente für abgeschlossene Anforderungen, die asynchrone Workflows auslösen, getrennt senden. Beispielsweise kann eine Web-API eine OK 200-Antwort, unmittelbar bevor die vom Benutzer angeforderte Arbeit beginnt, zurücksenden. Sie können ein vollständiges Segment an X-Ray senden, sobald die Antwort gesendet wurde, gefolgt von Untersegmenten für später abgeschlossene Arbeiten. Wie bei Segmenten können Sie auch einen Untersegmentsfragment senden, um den Beginn des Untersegments aufzuzeichnen, und es anschließend mit einem vollständigen Segment überschreiben, sobald ein nachgelagerter Aufruf abgeschlossen ist.
Die folgenden Felder sind für Untersegmente erforderlich oder in einigen Fällen notwendig.
Anmerkung
Werte sind Zeichenfolgen, die aus bis zu 250 Zeichen bestehen, soweit nicht anders angegeben.
Erforderliche Untersegmentsfelder
-
id— Eine 64-Bit-ID für das Untersegment, die unter den Segmenten in derselben Spur eindeutig ist und aus 16 Hexadezimalziffern besteht. -
name— Der logische Name des Untersegments. Benennen Sie bei nachgelagerten Aufrufen das Untersegment, nachdem die Ressource oder der Service aufgerufen wurde. Benennen Sie bei benutzerdefinierten Untersegmenten das Untersegment nach dem genutzten Code (z. B. einem Funktionsnamen). -
start_time— Zahl, die die Zeit angibt, zu der das Untersegment erstellt wurde, in Gleitkommasekunden in der Epochenzeit, auf Millisekunden genau. Zum Beispiel1480615200.010oder1.480615200010E9. -
end_time— Zahl, die die Zeit angibt, zu der das Untersegment geschlossen wurde. Zum Beispiel1480615200.090oder1.480615200090E9. Geben Sie eineend_timeoderin_progressein. -
in_progress— boolescher Wert, der auf gesetzt ist,trueanstatt anzugeben, dass einend_timeUntersegment zwar gestartet, aber noch nicht abgeschlossen ist. Senden Sie pro nachgelagerter Anfrage nur ein vollständiges Untersegment und ein oder kein angefangenes Untersegment. -
trace_id— Trace-ID des übergeordneten Segments des Untersegments. Nur erforderlich, wenn ein Untersegment separat gesendet wird.Röntgen-Trace-ID-Format
Ein X-Ray
trace_idbesteht aus drei Zahlen, die durch Bindestriche getrennt sind. z. B.1-58406520-a006649127e371903a2de979. Dies umfasst:-
Die Versionsnummer, die ist.
1 -
Die Uhrzeit der ursprünglichen Anfrage in Unix-Epochenzeit unter Verwendung von 8 Hexadezimalziffern.
Zum Beispiel ist 10:00 Uhr am 1. Dezember 2016 PST in Epochenzeit
1480615200Sekunden oder58406520in Hexadezimalziffern. -
Eine weltweit eindeutige 96-Bit-ID für den Trace mit 24 Hexadezimalziffern.
Anmerkung
X-Ray unterstützt jetzt Trace-IDs, die mit OpenTelemetry und jedem anderen Framework erstellt wurden, 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 4efaaf4d1e8720b39541901950019ee5sollte die W3C-Trace-ID wie1-4efaaf4d-1e8720b39541901950019ee5beim Senden an X-Ray formatiert werden. X-Ray-Trace-IDs enthalten den ursprünglichen Anforderungszeitstempel in der Unix-Epochenzeit, dies ist jedoch nicht erforderlich, wenn W3C-Trace-IDs im X-Ray-Format gesendet werden. -
-
parent_id— Segment-ID des übergeordneten Segments des Untersegments. Nur erforderlich, wenn ein Untersegment separat gesendet wird. Bei verschachtelten Untersegmenten kann ein Untersegment ein Segment oder ein Untersegment als übergeordnetes Element haben. -
type—subsegment. Nur erforderlich, wenn ein Untersegment separat gesendet wird.
Die folgenden Felder sind für Untersegmente optional.
Optionale Untersegmentsfelder
-
namespace—awsfür AWS-SDK-Aufrufe;remotefür andere Downstream-Aufrufe. -
http— httpObjekt mit Informationen über einen ausgehenden HTTP-Aufruf. -
aws— awsObjekt mit Informationen über die AWS Downstream-Ressource, die Ihre Anwendung aufgerufen hat. -
error,throttlefault, undcause— Fehlerfelder, die darauf hinweisen, dass ein Fehler aufgetreten ist, und die Informationen über die Ausnahme enthalten, die den Fehler verursacht hat. -
annotations— annotationsObjekt mit Schlüssel-Wert-Paaren, die X-Ray für die Suche indexieren soll. -
metadata— metadataObjekt mit allen zusätzlichen Daten, die Sie in dem Segment speichern möchten. -
subsegments— Anordnung von subsegmentObjekten. -
precursor_ids— Array von Untersegment-IDs, das Untersegmente identifiziert, denen dasselbe übergeordnete Objekt zugewiesen wurde, das vor diesem Untersegment abgeschlossen wurde.
Verwenden Sie einen HTTP-Block, um Details zu einer HTTP-Anforderung aufzuzeichnen, die Ihrer Anwendung (in einem Segment) dient oder die Ihre Anwendung (in einem Untersegment) an eine nachgelagerte HTTP-API gestellt hat. Die meisten Felder in dieser Objektübersicht gehören zu Informationen von HTTP-Anforderungen und -Antworten.
http
Alle Felder sind optional.
-
request— Informationen zu einer Anfrage.-
method— Die Anforderungsmethode. z. B.GET. -
url— Die vollständige URL der Anfrage, zusammengestellt aus dem Protokoll, dem Hostnamen und dem Pfad der Anfrage. -
user_agent— Die User-Agent-Zeichenfolge vom Client des Anforderers. -
client_ip— Die IP-Adresse des Anforderers. Kann im IP-PaketSource Addressoder, für weitergeleitete Anforderungen, in einemX-Forwarded-For-Header eingesehen werden. -
x_forwarded_for— (nur Segmente) boolescher Wert, der angibt, dass der aus einemX-Forwarded-ForHeader gelesenclient_ipwurde und nicht zuverlässig ist, da er gefälscht worden sein könnte. -
traced— (nur Untersegmente) boolescher Wert, der angibt, dass der Downstream-Aufruf an einen anderen verfolgten Dienst gerichtet ist. Wenn dieses Feld auf gesetzt isttrue, betrachtet X-Ray den Trace als unterbrochen, bis der Downstream-Service ein Segment hochlädtparent_id, dessen a demiddes Untersegments entspricht, das diesen Block enthält.
-
-
response— Informationen über eine Antwort.-
status— Ganzzahl, die den HTTP-Status der Antwort angibt. -
content_length— Ganzzahl, die die Länge des Antworttextes in Byte angibt.
-
Wenn Sie einen Aufruf einer Downstream-Web-API instrumentieren, zeichnen Sie ein Untersegment mit Informationen zur HTTP-Anfrage und -Antwort auf. X-Ray verwendet das Untersegment, um ein abgeleitetes Segment für die Remote-API zu generieren.
Beispiel Segment für einen HTTP-Aufruf, der von einer Anwendung, die über Amazon EC2 ausgeführt wird, bereitgestellt wird.
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}Beispiel Untersegment für einen nachgelagerten HTTP-Aufruf
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}Beispiel Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}Segmente und Untersegmente können ein annotations Objekt enthalten, das ein oder mehrere Felder enthält, die X-Ray für die Verwendung mit Filterausdrücken indexiert. Felder können eine Zeichenfolge, Zahl oder einen booleschen Werte (keine Objekte oder Arrays) umfassen. X-Ray indexiert bis zu 50 Anmerkungen pro Spur.
Beispiel Segment für HTTP-Aufrufe mit Anmerkungen
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}Die Schlüssel müssen alphanumerisch sein, um mit Filtern funktionieren zu können. Unterstriche sind zulässig. Andere Zeichen und Leerzeichen sind nicht zulässig.
Segmente und Untersegmente können ein metadata Objekt enthalten, das ein oder mehrere Felder mit Werten beliebigen Typs, einschließlich Objekten und Arrays, enthält. X-Ray indexiert keine Metadaten, und Werte können beliebig groß sein, solange das Segmentdokument die maximale Größe (64 kB) nicht überschreitet. Sie können Metadaten im vollständigen Segmentdokument, das von der BatchGetTraces-API zurückgesendet wurde, einsehen. Feldschlüssel (debugim folgenden Beispiel), die mit beginnen, AWS. sind für die Verwendung durch von AWS-bereitgestellte SDKs und Clients reserviert.
Beispiel Individuelles Untersegment mit Metadaten
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}Bei Segmenten enthält das aws-Objekt Informationen zu den Ressourcen, auf denen Ihre Anwendung ausgeführt wird. Mehrere Felder können für eine einzelne Ressource zutreffen. Beispielsweise könnte eine Anwendung, die in einer Docker-Umgebung mit mehreren Containern auf Elastic Beanstalk ausgeführt wird, Informationen über die Amazon EC2 EC2-Instance, den Amazon ECS-Container, der auf der Instance ausgeführt wird, und die Elastic Beanstalk Beanstalk-Umgebung selbst enthalten.
aws (Segmente)
Alle Felder sind optional.
-
account_id— Wenn Ihre Anwendung Segmente an eine andere sendet AWS-Konto, notieren Sie sich die ID des Kontos, auf dem Ihre Anwendung ausgeführt wird. -
cloudwatch_logs— Array von Objekten, die eine einzelne CloudWatch Protokollgruppe beschreiben.-
log_group— Der Name der CloudWatch Protokollgruppe. -
arn— Die CloudWatch Protokollgruppe ARN.
-
-
ec2— Informationen über eine Amazon EC2 EC2-Instance.-
instance_id— Die Instance-ID der EC2-Instance. -
instance_size— Der Typ der EC2-Instance. -
ami_id— Die Amazon Machine Image-ID. -
availability_zone— Die Availability Zone, in der die Instance ausgeführt wird.
-
-
ecs— Informationen über einen Amazon ECS-Container.-
container— Der Hostname Ihres Containers. -
container_id— Die vollständige Container-ID Ihres Containers. -
container_arn— Der ARN Ihrer Container-Instance.
-
-
eks— Informationen über einen Amazon EKS-Cluster.-
pod— Der Hostname Ihres EKS-Pods. -
cluster_name— Der Name des EKS-Clusters. -
container_id— Die vollständige Container-ID Ihres Containers.
-
-
elastic_beanstalk— Informationen über eine Elastic Beanstalk Beanstalk-Umgebung. Sie finden diese Informationen in einer Datei mit dem Namen/var/elasticbeanstalk/xray/environment.confauf den neuesten Elastic Beanstalk-Plattformen.-
environment_name– Der Name der Umgebung. -
version_label— Der Name der Anwendungsversion, die derzeit auf der Instance bereitgestellt wird, die die Anfrage bedient hat. -
deployment_id— Zahl, die die ID der letzten erfolgreichen Bereitstellung auf der Instance angibt, die die Anfrage bedient hat.
-
-
xray— Metadaten über den Typ und die Version der verwendeten Instrumentierung.-
auto_instrumentation— Boolescher Wert, der angibt, ob die automatische Instrumentierung verwendet wurde (z. B. der Java-Agent). -
sdk_version— Die Version des verwendeten SDK oder Agenten. -
sdk— Der Typ des SDK.
-
Beispiel AWS Block mit Plugins
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
Erfassen Sie für Untersegmente Informationen über die Ressourcen AWS-Services und die Ressourcen, auf die Ihre Anwendung zugreift. X-Ray verwendet diese Informationen, um abgeleitete Segmente zu erstellen, die die Downstream-Services in Ihrer Service-Map darstellen.
aws (Untersegmente)
Alle Felder sind optional.
-
operation— Der Name der API-Aktion, die für eine AWS-Service OR-Ressource aufgerufen wurde. -
account_id— Wenn Ihre Anwendung auf Ressourcen in einem anderen Konto zugreift oder Segmente an ein anderes Konto sendet, notieren Sie sich die ID des Kontos, dem die AWS Ressource gehört, auf die Ihre Anwendung zugegriffen hat. -
region— Wenn sich die Ressource in einer anderen Region als Ihre Anwendung befindet, notieren Sie die Region. z. B.us-west-2. -
request_id— Eindeutiger Bezeichner für die Anfrage. -
queue_url— Für Operationen in einer Amazon SQS SQS-Warteschlange die URL der Warteschlange. -
table_name— Für Operationen an einer DynamoDB-Tabelle der Name der Tabelle.
Beispiel Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}Wenn ein Fehler auftritt, können Sie die Einzelheiten zum Fehler und den Ausnahmen, die er generiert, aufzeichnen. Zeichnen Sie Fehler in Segmenten auf, wenn Ihre Anwendung einen Fehler an den Benutzer zurückgibt, sowie in Untersegmenten, wenn ein nachgelagerter Aufruf einen Fehler ausgibt.
Fehlertypen
Stellen Sie ein oder mehrere der folgenden Felder auf true ein, um anzuzeigen, dass ein Fehler aufgetreten ist. Bei schwerwiegenden Fehlern können mehrere Typen ausgewählt werden. Ein 429 Too Many
Requests-Fehler von einem nachgelagerten Aufruf kann beispielsweise dazu führen, dass Ihre Anwendung zu einem 500 Internal Server Error zurückkehrt. In diesem Fall treffen alle drei Typen zu.
-
error— Boolescher Wert, der angibt, dass ein Client-Fehler aufgetreten ist (der Antwortstatuscode lautete 4XX Client Error). -
throttle— boolescher Wert, der angibt, dass eine Anfrage gedrosselt wurde (der Antwortstatuscode lautete 429 Too Many Requests). -
fault— boolescher Wert, der angibt, dass ein Serverfehler aufgetreten ist (der Antwortstatuscode lautete 5XX Server Error).
Geben Sie die Fehlerursache an, indem Sie im Segment oder Untersegment ein Ursachenobjekt einschließen.
cause
Eine Ursache kann entweder eine 16-stellige Ausnahmen-ID oder ein Objekt mit den folgenden Feldern sein:
-
working_directory— Der vollständige Pfad des Arbeitsverzeichnisses, als die Ausnahme auftrat. -
paths— Das Array von Pfaden zu Bibliotheken oder Modulen, die verwendet wurden, als die Ausnahme auftrat. -
exceptions— Das Array von Ausnahmeobjekten.
Geben Sie detaillierte Informationen über die Fehler in einem oder mehreren Ausnahmenobjekten an.
exception
Alle Felder sind optional.
-
id— Eine 64-Bit-ID für die Ausnahme, die unter den Segmenten derselben Spur eindeutig ist und aus 16 Hexadezimalziffern besteht. -
message— Die Ausnahmemeldung. -
type— Der Ausnahmetyp. -
remote— Boolescher Wert, der angibt, dass die Ausnahme durch einen Fehler verursacht wurde, der von einem nachgelagerten Dienst zurückgegeben wurde. -
truncated— Ganzzahl, die die Anzahl der Stack-Frames angibt, die in der weggelassen wurden.stack -
skipped— Ganzzahl, die die Anzahl der Ausnahmen angibt, die zwischen dieser Ausnahme und ihrem untergeordneten Element, d. h. der von ihr verursachten Ausnahme, übersprungen wurden. -
cause— Ausnahme-ID des der Ausnahme übergeordneten Elements, d. h. der Ausnahme, die diese Ausnahme verursacht hat. -
stack— Array von StackFrame-Objekten.
Falls verfügbar, zeichnen Sie Informationen zu dem Aufruf-Stack in stackFrame-Objekten auf.
stackFrame
Alle Felder sind optional.
-
path— Der relative Pfad zur Datei. -
line— Die Zeile in der Datei. -
label— Der Funktions- oder Methodenname.
Für Anfragen, die Ihre Anwendung in eine SQL-Datenbank umwandeln, können Sie Untersegmente erstellen.
sql
Alle Felder sind optional.
-
connection_string— Für SQL Server- oder andere Datenbankverbindungen, die keine URL-Verbindungszeichenfolgen verwenden, notieren Sie sich die Verbindungszeichenfolge, ausgenommen Kennwörter. -
url— Notieren Sie für eine Datenbankverbindung, die eine URL-Verbindungszeichenfolge verwendet, die URL ohne Kennwörter. -
sanitized_query— Die Datenbankabfrage, bei der alle vom Benutzer angegebenen Werte entfernt oder durch einen Platzhalter ersetzt wurden. -
database_type— Der Name der Datenbank-Engine. -
database_version— Die Versionsnummer der Datenbank-Engine. -
driver_version— Der Name und die Versionsnummer des Datenbank-Engine-Treibers, den Ihre Anwendung verwendet. -
user— Der Datenbank-Benutzername. -
preparation—callob die Abfrage eine verwendet hatPreparedCall;statementwenn die Abfrage eine verwendet hatPreparedStatement.
Beispiel Untersegment mit einer SQL-Abfrage
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}