AWS X-Ray Dokumente segmentieren

Erforderliche Segmentfelder

• name – Der logische Name des Services, der die Anforderung verarbeitet 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-Kennung für das Segment, die unter Segmenten in derselben Ablaufverfolgung eindeutig ist, in 16 Hexadezimalziffern.

• trace_id – Eine eindeutige Kennung, die alle Segmente und Teilsegmente verbindet, die aus einer einzelnen Client-Anforderung stammen.

  X-Ray-Trace-ID-Format

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

  • Die Versionsnummer, 1.

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

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

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

  Anmerkung

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

  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 ist, zu der das Segment erstellt wurde, in Gleitkommasekunden in 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 ist, zu der das Segment geschlossen wurde. Zum Beispiel 1480615200.090 oder 1.480615200090E9. Geben Sie entweder end_time oder in_progress an.

• in_progress – boolean, auf gesetzt, true anstatt eine anzugeben, end_time um aufzuzeichnen, dass ein Segment gestartet wird, aber 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.

Optionale Segmentfelder

• service – Ein Objekt mit Informationen zu Ihrer Anwendung.

  • version – Eine Zeichenfolge, die die Version Ihrer Anwendung identifiziert, die die Anforderung verarbeitet hat.

• user – Eine Zeichenfolge, die den Benutzer identifiziert, der die Anforderung gesendet hat.

• origin – Der Typ der AWS Ressource, auf der Ihre Anwendung ausgeführt wird.

  Unterstützte Werte

  • AWS::EC2::Instance – Eine Amazon EC2-Instance.

  • AWS::ECS::Container – Ein Amazon-ECS-Container.

  • AWS::ElasticBeanstalk::Environment – Eine Elastic Beanstalk-Umgebung.

  Wenn mehrere Werte für Ihre Anwendung gelten, verwenden Sie den spezifischsten. Beispielsweise führt eine Multicontainer-Docker-Elastic-Beanstalk-Umgebung Ihre Anwendung auf einem Amazon-ECS-Container aus, der wiederum auf einer Amazon EC2 ausgeführt wird. 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 Untersegment-ID, die Sie angeben, wenn die Anforderung von einer instrumentierten Anwendung stammt. Das X-Ray-SDK fügt die ID des übergeordneten Teilsegments zum Ablaufverfolgungs-Header für nachgelagerte HTTP-Aufrufe hinzu. Bei verschachtelten Untersegmenten kann ein Untersegment ein Segment oder ein Untersegment als übergeordnetes Element haben.

• http – http Objekte mit Informationen über die ursprüngliche HTTP-Anforderung.

• aws – -awsObjekt mit Informationen über die AWS Ressource, für die Ihre Anwendung die Anforderung verarbeitet hat.

• error, throttlefault, und cause – Fehlerfelder, die auf einen Fehler hinweisen und Informationen über die Ausnahme enthalten, die den Fehler verursacht hat.

• annotations – -annotationsObjekt mit Schlüssel-Wert-Paaren, die X-Ray für die Suche indizieren soll.

• metadata – -metadataObjekt mit allen zusätzlichen Daten, die Sie im Segment speichern möchten.

• subsegments – Array von -subsegmentObjekten.

Erforderliche Untersegmentsfelder

• id – Eine 64-Bit-Kennung für das Untersegment, die unter Segmenten in derselben Ablaufverfolgung eindeutig ist, in 16 Hexadezimalziffern.

• 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 ist, zu der das Teilsegment erstellt wurde, in Gleitkommasekunden in Epochenzeit, genau auf Millisekunden. Zum Beispiel 1480615200.010 oder 1.480615200010E9.

• end_time – Zahl, die die Zeit ist, 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 einen anzugeben, end_time um aufzuzeichnen, dass ein Teilsegment gestartet wird, aber nicht abgeschlossen ist. Senden Sie pro nachgelagerter Anfrage nur ein vollständiges Untersegment und ein oder kein angefangenes Untersegment.

• trace_id – Ablaufverfolgungs-ID des übergeordneten Segments des Untersegments. Nur erforderlich, wenn ein Untersegment separat gesendet wird.

  X-Ray-Trace-ID-Format

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

  • Die Versionsnummer, 1.

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

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

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

  Anmerkung

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

• 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 Teilsegment separat gesendet wird.

Optionale Untersegmentsfelder

• namespace – aws für AWS SDK-Aufrufe; remote für andere Downstream-Aufrufe.

• http – -httpObjekt mit Informationen über einen ausgehenden HTTP-Aufruf.

• aws – -awsObjekt mit Informationen über die nachgelagerte AWS Ressource, die Ihre Anwendung aufgerufen hat.

• error, throttlefault, und cause – Fehlerfelder, die auf einen Fehler hinweisen und Informationen über die Ausnahme enthalten, die den Fehler verursacht hat.

• annotations – -annotationsObjekt mit Schlüssel-Wert-Paaren, die X-Ray für die Suche indizieren soll.

• metadata – -metadataObjekt mit allen zusätzlichen Daten, die Sie im Segment speichern möchten.

• subsegments – Array von -subsegmentObjekten.

• precursor_ids – Array von Untersegment-IDs, die Untersegmente mit demselben übergeordneten Element identifizieren, das vor diesem Untersegment abgeschlossen wurde.

http

Alle Felder sind optional.

• request – Informationen zu einer Anforderung.

  • method – Die Anforderungsmethode. Beispiel: GET

  • url – Die vollständige URL der Anforderung, kompiliert aus dem Protokoll, dem Hostnamen und dem Pfad der Anforderung.

  • user_agent – Die Benutzeragent-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) boolean, was darauf hinweist, dass die aus einem -X-Forwarded-ForHeader gelesen client_ip wurde und nicht zuverlässig ist, da sie gefälscht worden sein könnte.

  • traced – (nur Teilsegmente) boolescher Wert, der angibt, dass der Downstream-Aufruf an einen anderen verfolgten Service gerichtet ist. Wenn dieses Feld auf gesetzt isttrue, betrachtet X-Ray die Ablaufverfolgung als unterbrochen, bis der Downstream-Service ein Segment mit einem hochlädtparent_id, das dem id des Teilsegments entspricht, das diesen Block enthält.

• response – Informationen zu einer Antwort.

  • status – Ganzzahl, die den HTTP-Status der Antwort angibt.

  • content_length – Ganzzahl, die die Länge des Antworttexts in Byte angibt.

aws (Segmente)

Alle Felder sind optional.

• account_id – Wenn Ihre Anwendung Segmente an ein anderes sendet AWS-Konto, notieren Sie 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 – Der ARN der CloudWatch Protokollgruppe.

• ec2 – Informationen über eine Amazon EC2.

  • 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 zu einem 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 zu einem 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-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 Anforderung bedient hat.

  • deployment_id – Zahl, die die ID der letzten erfolgreichen Bereitstellung für die Instance angibt, die die Anforderung 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.

aws (Untersegmente)

Alle Felder sind optional.

• operation – Der Name der API-Aktion, die für eine - AWS-Service oder -Ressource aufgerufen wird.

• account_id – Wenn Ihre Anwendung auf Ressourcen in einem anderen Konto zugreift oder Segmente an ein anderes Konto sendet, notieren Sie die ID des Kontos, dem die AWS Ressource gehört, auf die Ihre Anwendung zugegriffen hat.

• region – Wenn sich die Ressource in einer Region befindet, die sich von Ihrer Anwendung unterscheidet, notieren Sie die Region. Beispiel: us-west-2

• request_id – Eindeutige Kennung für die Anforderung.

• queue_url – Für Operationen in einer Amazon SQS-Warteschlange die URL der Warteschlange.

• table_name – Bei Operationen in einer DynamoDB-Tabelle der Name der Tabelle.

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 Clientfehler aufgetreten ist (Antwortstatuscode lautet 4XX Client Error).

• throttle – boolean, was darauf hinweist, dass eine Anforderung gedrosselt wurde (Antwortstatuscode lautete 429 Too Many Requests).

• fault – boolescher Wert, der angibt, dass ein Serverfehler aufgetreten ist (Antwortstatuscode lautet 5XX Server Error).

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 aufgetreten ist.

• paths – Das Array von Pfaden zu Bibliotheken oder Modulen, die verwendet werden, wenn die Ausnahme aufgetreten ist.

• exceptions – Das Array von Ausnahmeobjekten.

exception

Alle Felder sind optional.

• id – Eine 64-Bit-ID für die Ausnahme, die unter Segmenten in derselben Ablaufverfolgung eindeutig ist, in 16 Hexadezimalziffern.

• message – Die Ausnahmemeldung.

• type – Der Ausnahmetyp.

• remote – boolesch, was darauf hinweist, dass die Ausnahme durch einen Fehler verursacht wurde, der von einem Downstream-Service zurückgegeben wurde.

• truncated – Ganzzahl, die die Anzahl der Stack-Frames angibt, die aus dem weggelassen werdenstack.

• skipped – Ganzzahl, die die Anzahl der Ausnahmen angibt, die zwischen dieser Ausnahme und ihrem untergeordneten Element, d. h. der Ausnahme, die sie verursacht hat, übersprungen wurden.

• cause – Ausnahme-ID des übergeordneten Elements der Ausnahme, d. h. die Ausnahme, die diese Ausnahme verursacht hat.

• stack – Array von stackFrame-Objekten.

stackFrame

Alle Felder sind optional.

• path – Der relative Pfad zur Datei.

• line – Die Zeile in der Datei.

• label – Der Funktions- oder Methodenname.

sql

Alle Felder sind optional.

• connection_string – Notieren Sie sich für SQL Server oder andere Datenbankverbindungen, die keine URL-Verbindungszeichenfolgen verwenden, die Verbindungszeichenfolge, ausgenommen Passwörter.

• url – Notieren Sie für eine Datenbankverbindung, die eine URL-Verbindungszeichenfolge verwendet, die URL, ausgenommen Passwörter.

• sanitized_query – Die Datenbankabfrage, wobei alle vom Benutzer bereitgestellten Werte entfernt oder durch einen Platzhalter ersetzt werden.

• 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 Benutzername der Datenbank.

• preparation – call wenn die Abfrage eine verwendet hatPreparedCall; statement wenn die Abfrage eine verwendet hatPreparedStatement.