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 X-Ray APIs direkt oder 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](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) 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:
![\[X-Ray zeigt detaillierte Informationen zu Bewerbungsanfragen an.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/api-vs-cli.png)
Verwenden Sie die X-Ray-API, um Trace-Daten direkt an X-Ray zu senden. Die X-Ray-API unterstützt alle Funktionen, die im X-Ray SDK verfügbar sind, einschließlich der folgenden allgemeinen Aktionen:
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)— Lädt Segmentdokumente auf X-Ray hoch.
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html)— Ruft eine Liste von Traces in einer Trace-Liste ab. IDs Jeder abgerufene Trace ist eine Sammlung von Segmentdokumenten aus einer einzigen Anfrage.
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)— Ruft IDs Traces ab und kommentiert sie. Sie können a angeben`FilterExpression`, um eine Teilmenge der Trace-Zusammenfassungen abzurufen.
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html)— Ruft ein Service-Diagramm für eine bestimmte Trace-ID ab.
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)— Ruft eine ab JSON formatiertes Dokument, 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. Bei den folgenden Funktionen handelt es sich um Versionen der zuvor aufgeführten API-Operationen mit einem einfacheren Format:
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html)— Lädt Segmentdokumente auf X-Ray hoch.
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html)— Ruft eine Liste von Traces in einer Trace-Liste ab. IDs Jeder abgerufene Trace ist eine Sammlung von Segmentdokumenten aus einer einzigen Anfrage.
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html)— Ruft IDs Traces ab und kommentiert sie. Sie können a angeben`FilterExpression`, um eine Teilmenge der Trace-Zusammenfassungen abzurufen.
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html)— Ruft ein Service-Diagramm für eine bestimmte Trace-ID ab.
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html)— Ruft ein `JSON` formatiertes Dokument ab, das Dienste beschreibt, die eingehende Anfragen verarbeiten und nachgelagerte Anfragen aufrufen.
Um zu beginnen, müssen Sie das [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)für Ihr Betriebssystem installieren. AWS unterstützt Linux, macOS and Windows Betriebssysteme. Weitere Informationen zur Liste der X-Ray-Befehle finden Sie in der [AWS CLI Befehlsreferenz für X-Ray](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html).
**Topics**
+ [Verwenden der AWS X-Ray API mit der AWS CLI](xray-api-tutorial.md)
+ [Trace-Daten senden an AWS X-Ray](xray-api-sendingdata.md)
+ [Daten abrufen von AWS X-Ray](xray-api-gettingdata.md)
+ [Konfiguration von Sampling-, Gruppen- und Verschlüsselungseinstellungen mit der AWS X-Ray API](xray-api-configuration.md)
+ [Verwenden von Sampling-Regeln mit der X-Ray-API](xray-api-sampling.md)
+ [AWS X-Ray Dokumente segmentieren](xray-api-segmentdocuments.md)
# Verwenden der AWS X-Ray API mit der AWS CLI
Über die AWS CLI können Sie direkt auf den X-Ray-Dienst zugreifen und denselben Dienst verwenden APIs , den 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 "Erste Schritte"](xray-gettingstarted.md), 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](https://docs.aws.amazon.com/cli/latest/userguide/installing.html), bietet öffentlichen Befehlszeilenzugriff APIs für alle AWS-Services.
**Anmerkung**
Sie müssen überprüfen, ob Ihr System für dieselbe Region konfiguriert AWS CLI ist, in der Ihre Scorekeep-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.io](https://stedolan.github.io/jq/) und die ausführbare `curl`-Datei von [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html) herunterladen. Die meisten Linux- und OS X-Installationen umfassen cURL.
## 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**
1. In der [Elastic-Beanstalk-Konsole](https://console.aws.amazon.com/elasticbeanstalk) öffnen.
1. Navigieren Sie zur [Managementkonsole](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) für Ihre Umgebung.
1. Kopieren Sie die Umgebungs-**URL** aus dem Header der Seite.
1. Öffnen Sie `bin/test-api.sh` und ersetzen Sie den Wert für die API mit der URL Ihrer Umgebung.
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. Führen Sie das Skript aus, um Datenverkehr zur API zu generieren.
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating 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 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)und [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Weitere Informationen über alle unterstützten Aktionen und die von ihnen verwendeten Datentypen finden Sie in der [AWS X-Ray -API-Referenz](https://docs.aws.amazon.com/xray/latest/api/Welcome.html).
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
Das 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",
...
```
**Example 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 Traces ab, die vor einer bis zwei Minuten 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"
]
```
**Example 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 EC2 Amazon-Instances, DynamoDB-Tabellen und andere Ressourcen herunterzufahren.
**So beenden Sie die Elastic Beanstalk-Umgebung**
1. In der [Elastic-Beanstalk-Konsole](https://console.aws.amazon.com/elasticbeanstalk) öffnen.
1. Navigieren Sie zur [Managementkonsole für Ihre Umgebung](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html).
1. Wählen Sie **Aktionen**.
1. Wählen Sie **Terminate Environment**.
1. Wähen Sie **Beenden**.
Trace-Daten werden nach 30 Tagen automatisch aus X-Ray gelöscht.
# Trace-Daten senden an AWS X-Ray
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 Zeit auf, die für eine Aufgabe aufgewendet wurde, einen Namen und zwei IDs. 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.
**Example 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.
**Example 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 [`PutTraceSegments`](#xray-api-segments)X-Ray-Daemon an X-Ray](#xray-api-daemon) 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.
**Example 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](xray-api-segmentdocuments.md).
**Topics**
+ [Trace wird generiert IDs](#xray-api-traceids)
+ [Benutzen PutTraceSegments](#xray-api-segments)
+ [Segmentdokumente an den X-Ray-Daemon senden](#xray-api-daemon)
## Trace wird generiert IDs
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. Beispiel, `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 `1480615200` Sekunden oder `58406520` in Hexadezimalziffern.
+ **Eine weltweit eindeutige 96-Bit-ID für den Trace mit 24 Hexadezimalziffern.**
**Anmerkung**
X-Ray unterstützt jetzt IDs Traces, die mit OpenTelemetry und jedem anderen Framework erstellt wurden, das der [W3C Trace Context-Spezifikation](https://www.w3.org/TR/trace-context/) 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 wie `1-4efaaf4d-1e8720b39541901950019ee5` beim Senden an X-Ray formatiert werden. X-Ray-Trace IDs enthält den ursprünglichen Anforderungszeitstempel in der Unix-Epochenzeit, aber dies ist nicht erforderlich, wenn W3C-Trace IDs im X-Ray-Format gesendet wird.
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 Scorekeep-Beispielanwendung finden Sie Skripte, die Trace erstellen IDs und Segmente an den X-Ray-Daemon senden.
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash — [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## Benutzen PutTraceSegments
Sie können Segmentdokumente mit der [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)-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](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings) 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"
```
## Segmentdokumente an den X-Ray-Daemon senden
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](xray-daemon-local.md).
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
```
**Example 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](xray-daemon.md#xray-daemon-logging), 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)
```
# Daten abrufen von AWS X-Ray
AWS X-Ray verarbeitet die Trace-Daten, die Sie an sie 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.
**Topics**
+ [Abrufen des Service-Diagramms](#xray-api-servicegraph)
+ [Abrufen des Service-Diagramms nach Gruppe](#xray-api-servicegraphgroup)
+ [Abrufen von Ablaufverfolgungen](#xray-api-traces)
+ [Abrufen und Anpassen der Ursachenanalyse](#xray-api-analytics)
## Abrufen des Service-Diagramms
Sie können die API [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) 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
1499394617
```
`date +%s` druckt ein Datum in Sekunden. Verwenden Sie diese Zahl als Endzeit. Ziehen Sie Zeit ab, um eine Startzeit zu erhalten.
**Example 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.
**Example 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
}
]
}
]
}
```
## Abrufen des Service-Diagramms nach Gruppe
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.
**Example Skript zum Abrufen eines Service-Diagramms nach Name für die Gruppe Example1**
```
aws xray get-service-graph --group-name "Example1"
```
## Abrufen von Ablaufverfolgungen
Sie können die API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) verwenden, um eine Liste von Ablaufverfolgungsübersichten abzurufen. Trace-Zusammenfassungen enthalten Informationen, anhand derer Sie Traces identifizieren können, die Sie vollständig herunterladen möchten, einschließlich Anmerkungen, Anfrage- und Antwortinformationen und. IDs
Beim Aufruf von `aws xray get-trace-summaries` stehen zwei `TimeRangeType`- Flags zur Verfügung:
+ **TraceId**— Die `GetTraceSummaries` Standardsuche 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.
**Example Skript zum Abrufen von Ablaufverfolgungsübersichten**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example 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 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) eine vollständige Ablaufverfolgung abrufen.
**Example BatchGetTraces Befehl**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example 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](xray-api-segmentdocuments.md) entsprechen.
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 Trace-Liste IDs, die Sie mit einer Abfrage aus der `get-trace-summaries` Ausgabe extrahieren können.AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter) Leiten Sie die Liste zur Eingabe von `batch-get-traces` um, um vollständige Traces für einen bestimmten Zeitraum zu erhalten.
**Example 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[*]'
```
## Abrufen und Anpassen der Ursachenanalyse
Nach der Generierung einer Trace-Zusammenfassung mit der [GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) 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.
**Example 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.
**Example 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 zu Abfragen mit Filterausdrücken finden Sie im Kapitel [Filterausdrücke](xray-console-filters.md).
**Example Beispiel für JSON-Filter**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# Konfiguration von Sampling-, Gruppen- und Verschlüsselungseinstellungen mit der AWS X-Ray API
AWS X-Ray ermöglicht APIs die Konfiguration von [Sampling-Regeln](xray-console-sampling.md), Gruppenregeln und [Verschlüsselungseinstellungen](xray-console-encryption.md).
**Topics**
+ [Verschlüsselungseinstellungen](#xray-api-configuration-encryption)
+ [Regeln für die Probenahme](#xray-api-configuration-sampling)
+ [Gruppen](#xray-api-configuration-groups)
## Verschlüsselungseinstellungen
Dient [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)zur 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 [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html), um die aktuelle Konfiguration abzurufen. Wenn X-Ray die Übernahme Ihrer Einstellungen abgeschlossen hat, ändert sich der Status von `UPDATING` zu`ACTIVE`.
```
$ 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 auf`NONE`.
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## Regeln für die Probenahme
Sie können die [Sampling-Regeln](xray-console-sampling.md) in Ihrem Konto mit der X-Ray-API verwalten. Weitere Informationen zum Hinzufügen und Verwalten von Tags finden Sie unter[Kennzeichnen von Regeln und Gruppen für die Röntgenprobenahme](xray-tagging.md).
Sie können alle Samplingregeln mit [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 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 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) ändern.
**Example API-Eingabe für [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 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](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ 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 [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html). 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.
**Example API-Eingabe für [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 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.
**Example API-Eingabe für [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)— 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 [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html).
```
$ 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
}
}
```
## Gruppen
Sie können die X-Ray-API verwenden, um Gruppen in Ihrem Konto zu verwalten. Gruppen sind eine Sammlung von Traces, 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 abrufen von AWS X-Ray](xray-api-gettingdata.md) zur Arbeit mit Servicediagrammen und Metriken über die X-Ray-API finden Sie unter. Weitere Informationen zu Gruppen finden Sie unter[Gruppen konfigurieren](xray-console-groups.md). Weitere Informationen zum Hinzufügen und Verwalten von Stichwörtern finden Sie unter[Kennzeichnen von Regeln und Gruppen für die Röntgenprobenahme](xray-tagging.md).
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](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html).
```
$ 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"
{
}
```
# Verwenden von Sampling-Regeln mit der X-Ray-API
Das AWS X-Ray SDK verwendet die X-Ray-API, um Probenahmeregeln abzurufen, Probenahmeergebnisse zu melden und Kontingente abzurufen. Sie können diese verwenden APIs , 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 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 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 [Regeln für die Probenahme](xray-api-configuration.md#xray-api-configuration-sampling), 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 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) 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 kann auch ein längeres Berichtsintervall als das Standardintervall zuweisen, 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 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html). 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.
# AWS X-Ray Dokumente segmentieren
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 APIs, HTTP- 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 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)API 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 jeweils mit und zugreifen können. [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) APIs 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](samples/xray-segmentdocument-schema-v1.0.0.zip). 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 von Filterausdrücken](xray-console-filters.md).
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](xray-daemon.md). Weitere Informationen finden Sie unter [Segmentdokumente an den X-Ray-Daemon senden](xray-api-sendingdata.md#xray-api-daemon).
**Topics**
+ [Segmentfelder](#api-segmentdocuments-fields)
+ [Untersegmente](#api-segmentdocuments-subsegments)
+ [HTTP-Anfragedaten](#api-segmentdocuments-http)
+ [Anmerkungen](#api-segmentdocuments-annotations)
+ [Metadaten](#api-segmentdocuments-metadata)
+ [AWS Ressourcendaten](#api-segmentdocuments-aws)
+ [Fehler und Ausnahmen](#api-segmentdocuments-errors)
+ [SQL-Abfragen](#api-segmentdocuments-sql)
## Segmentfelder
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.
**Example 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_id` besteht aus drei Zahlen, die durch Bindestriche getrennt sind. Beispiel, `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 `1480615200` Sekunden oder `58406520` in Hexadezimalziffern.
+ **Eine weltweit eindeutige 96-Bit-ID für den Trace mit 24 Hexadezimalziffern.**
**Anmerkung**
X-Ray unterstützt jetzt IDs Traces, die mit OpenTelemetry und jedem anderen Framework erstellt wurden, das der [W3C Trace Context-Spezifikation](https://www.w3.org/TR/trace-context/) 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 wie `1-4efaaf4d-1e8720b39541901950019ee5` beim Senden an X-Ray formatiert werden. X-Ray-Trace IDs enthält den ursprünglichen Anforderungszeitstempel in der Unix-Epochenzeit, dies ist jedoch nicht erforderlich, wenn W3C-Trace IDs im X-Ray-Format gesendet wird.
**Sicherheit der Ablaufverfolgungs-ID**
Trace ist in IDs den Headern der [Antworten](xray-concepts.md#xray-concepts-tracingheader) sichtbar. Generieren Sie Trace IDs mit einem sicheren Zufallsalgorhythmus, um sicherzustellen, dass Angreifer future IDs Traces nicht berechnen und IDs damit Anfragen an Ihre Anwendung senden können.
+ `start_time`— **Zahl**, die die Zeit angibt, zu der das Segment erstellt wurde, in Fließkommasekunden in der Epochenzeit. Zum Beispiel `1480615200.010` oder `1.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 Beispiel `1480615200.090` oder `1.480615200090E9`. Geben Sie entweder `end_time` oder `in_progress` an.
+ `in_progress`— **boolescher Wert**, auf gesetzt, `true` anstatt anzugeben`end_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, [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)kann 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 EC2 Amazon-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-Instance läuft. EC2 In diesem Fall müssen Sie den Ursprung auf `AWS::ElasticBeanstalk::Environment` festlegen, 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](xray-concepts.md#xray-concepts-tracingheader) für Downstream-HTTP-Aufrufe hinzu. Bei verschachtelten Untersegmenten kann ein Untersegment ein Segment oder ein Untersegment als übergeordnetes Element haben.
+ `http`— [`http`](#api-segmentdocuments-http)Objekte mit Informationen über die ursprüngliche HTTP-Anfrage.
+ `aws`— [`aws`](#api-segmentdocuments-aws)Objekt mit Informationen über die AWS Ressource, auf der Ihre Anwendung die Anfrage bearbeitet hat.
+ `error`, `throttle``fault`, und `cause` — [Fehlerfelder](#api-segmentdocuments-errors), die darauf hinweisen, dass ein Fehler aufgetreten ist, und die Informationen über die Ausnahme enthalten, die den Fehler verursacht hat.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)Objekt mit Schlüssel-Wert-Paaren, die X-Ray für die Suche indexieren soll.
+ `metadata`— [`metadata`](#api-segmentdocuments-metadata)Objekt mit allen zusätzlichen Daten, die Sie in dem Segment speichern möchten.
+ `subsegments`— **Anordnung** von [`subsegment`](#api-segmentdocuments-subsegments)Objekten.
## Untersegmente
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.
**Example 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.
**Example In Bearbeitung befindliches Segment**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 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 Beispiel `1480615200.010` oder `1.480615200010E9`.
+ `end_time`— **Zahl**, die die Zeit angibt, zu der das Untersegment geschlossen wurde. Zum Beispiel `1480615200.090` oder `1.480615200090E9`. Geben Sie eine `end_time` oder `in_progress` ein.
+ `in_progress`— **boolescher Wert**, der auf gesetzt ist, `true` anstatt anzugeben, dass ein `end_time` Untersegment 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_id` besteht aus drei Zahlen, die durch Bindestriche getrennt sind. Beispiel, `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 `1480615200` Sekunden oder `58406520` in Hexadezimalziffern.
+ **Eine weltweit eindeutige 96-Bit-ID für den Trace mit 24 Hexadezimalziffern.**
**Anmerkung**
X-Ray unterstützt jetzt IDs Traces, die mit OpenTelemetry und jedem anderen Framework erstellt wurden, das der [W3C Trace Context-Spezifikation](https://www.w3.org/TR/trace-context/) 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 wie `1-4efaaf4d-1e8720b39541901950019ee5` beim Senden an X-Ray formatiert werden. X-Ray-Trace IDs enthält den ursprünglichen Anforderungszeitstempel in der Unix-Epochenzeit, dies ist jedoch nicht erforderlich, wenn W3C-Trace IDs im X-Ray-Format gesendet wird.
+ `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`— `aws` für AWS-SDK-Aufrufe; `remote` für andere Downstream-Aufrufe.
+ `http`— [`http`](#api-segmentdocuments-http)Objekt mit Informationen über einen ausgehenden HTTP-Aufruf.
+ `aws`— [`aws`](#api-segmentdocuments-aws)Objekt mit Informationen über die AWS Downstream-Ressource, die Ihre Anwendung aufgerufen hat.
+ `error`, `throttle``fault`, und `cause` — [Fehlerfelder](#api-segmentdocuments-errors), die darauf hinweisen, dass ein Fehler aufgetreten ist, und die Informationen über die Ausnahme enthalten, die den Fehler verursacht hat.
+ `annotations`— [`annotations`](#api-segmentdocuments-annotations)Objekt mit Schlüssel-Wert-Paaren, die X-Ray für die Suche indexieren soll.
+ `metadata`— [`metadata`](#api-segmentdocuments-metadata)Objekt mit allen zusätzlichen Daten, die Sie in dem Segment speichern möchten.
+ `subsegments`— **Anordnung** von [`subsegment`](#api-segmentdocuments-subsegments)Objekten.
+ `precursor_ids`— **ein Array** von Untersegmenten IDs , das Untersegmente identifiziert, denen dasselbe übergeordnete Objekt zugewiesen wurde, das vor diesem Untersegment abgeschlossen wurde.
## HTTP-Anfragedaten
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. Beispiel, `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-Paket `Source Address` oder, für weitergeleitete Anforderungen, in einem `X-Forwarded-For`-Header eingesehen werden.
+ `x_forwarded_for`— (nur Segmente) **boolescher Wert**, der angibt, dass der aus einem `X-Forwarded-For` Header gelesen `client_ip` wurde 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 ist`true`, betrachtet X-Ray den Trace als unterbrochen, bis der Downstream-Service ein Segment hochlädt`parent_id`, dessen a dem `id` des 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.
**Example Segment für HTTP-Aufrufe, die von einer auf Amazon laufenden Anwendung bedient werden EC2**
```
{
"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
}
}
```
**Example 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
}
}
}
```
**Example 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
}
```
## Anmerkungen
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.
**Example 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.
## Metadaten
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 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html)-API zurückgesendet wurde, einsehen. Feldschlüssel (`debug`im folgenden Beispiel), die mit beginnen, `AWS.` sind für die Verwendung durch AWS-provided SDKs und Clients reserviert.
**Example 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"
]
}
}
]
}
```
## AWS Ressourcendaten
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 EC2 Amazon-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 EC2 Amazon-Instance.
+ `instance_id`— Die Instance-ID der EC2 Instance.
+ `instance_size`— Der Typ der EC2 Instanz.
+ `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.conf` auf 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.
**Example 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. Beispiel, `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.
**Example 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",
}
}
```
## Fehler und Ausnahmen
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 **Ursachen**objekt 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 **Ausnahmen**objekten 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.
## SQL-Abfragen
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 ohne 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`— `call` ob die Abfrage eine verwendet hat`PreparedCall`; `statement` wenn die Abfrage eine verwendet hat`PreparedStatement`.
**Example 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=?;"
}
}
```