AWS X-Ray Dokumente segmentieren - AWS X-Ray
SegmentfelderUntersegmenteHTTP-AnfragedatenAnmerkungenMetadatenAWS -RessourcendatenFehler und AusnahmenSQL-Abfragen

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.

AWS X-Ray Dokumente segmentieren

Ein Ablaufverfolgungssegment ist eine JSON-Darstellung einer Anfrage, die Ihrer Anwendung dient. Ein Ablaufverfolgungssegment zeichnet Informationen über die ursprüngliche Anforderung, Informationen über die lokale Arbeit Ihrer Anwendung und Untersegmente mit Informationen über nachgelagerte Aufrufe auf, die Ihre Anwendung an AWS Ressourcen, HTTP-APIs und SQL-Datenbanken durchführt.

Ein Segmentdokument übermittelt Informationen über ein Segment an X-Ray. Ein Segmentdokument kann bis zu 64 kB groß sein und ein ganzes Segment mit Teilsegmenten, ein Fragment eines Segments, das angibt, dass eine Anforderung in Bearbeitung ist, oder ein einzelnes Teilsegment enthalten, das separat gesendet wird. Sie können Segmentdokumente mithilfe der PutTraceSegments API direkt an X-Ray senden.

X-Ray kompiliert und verarbeitet Segmentdokumente, um abfragbare Trace-Zusammenfassungen und vollständige Traces zu generieren, auf die Sie mithilfe der BatchGetTraces APIs GetTraceSummaries bzw. zugreifen können. 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 der vollständigen Ablaufverfolgung hinzu. Abgeleitete Segmente stellen nachgelagerte Services und Ressourcen in der Ablaufverfolgungszuordnung dar.

X-Ray stellt ein JSON-Schema für Segmentdokumente bereit. Sie können das Schema hier herunterladen: xray-segmentdocument-schema-v1.0.0. Die im Schema angegebenen Felder und Objekte werden in den folgenden Abschnitten genauer beschrieben.

Eine Teilmenge von Segmentfeldern wird von X-Ray für die Verwendung mit Filterausdrücken indiziert. Wenn Sie beispielsweise das user Feld für ein 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.

Wenn Sie Ihre Anwendung mit dem X-Ray-SDK instrumentieren, generiert das SDK Segmentdokumente für Sie. Anstatt Segmentdokumente direkt an X-Ray zu senden, überträgt das SDK sie über einen lokalen UDP-Port an den X-Ray-Daemon . Weitere Informationen finden Sie unter Senden von Segmentdokumenten an den X-Ray-Daemon.

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.

Beispiel Minimales vollständiges Segment
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0a",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "end_time" : 1.478293361449E9
}

Die folgenden Felder sind für Segmente erforderlich oder in einigen Fällen notwendig.

Anmerkung

Der Wert muss aus Zeichenfolgen (bis zu 250 Zeichen) bestehen, soweit nicht anders angegeben.

Erforderliche Segmentfelder

  • name – Der logische Name des 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.

Servicenamen

Die eines Segments name sollten mit dem Domänennamen oder dem logischen Namen des Services übereinstimmen, der das Segment generiert. Dies wird jedoch nicht durchgesetzt. Jede Anwendung, die berechtigt ist, Segmente mit einem beliebigen Namen zu PutTraceSegments 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 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.

Untersegmente

Sie können Untersegmente erstellen, um Aufrufe von AWS -Services und Ressourcen aufzuzeichnen, die Sie mit dem AWS SDK, Aufrufe interner oder externer HTTP-Web-APIs oder SQL-Datenbankabfragen durchführen. 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 Services auf, der ihn aufruft. X-Ray verwendet Teilsegmente, um nachgelagerte Services zu identifizieren, die keine Segmente senden, und um Einträge für sie im Servicediagramm zu erstellen.

Ein Untersegment kann in einem vollständigen Segmentdokument eingebettet oder separat gesendet werden. Senden Sie Untersegmente separat, um nachgelagerte Aufrufe für lange andauernde Anforderungen asynchron nachzuverfolgen oder um zu verhindern, dass die maximale Größe des Segmentdokuments überschritten wird.

Beispiel Segment mit eingebettetem Untersegment

Ein unabhängiges Untersegment hat einen type vom subsegment und einen parent_id, der das übergeordnete Segment identifiziert.

{
  "trace_id"   : "1-5759e988-bd862e3fe1be46a994272793",
  "id"         : "defdfd9912dc5a56",
  "start_time" : 1461096053.37518,
  "end_time"   : 1461096053.4042,
  "name"       : "www.example.com",
  "http"       : {
    "request"  : {
      "url"        : "https://www.example.com/health",
      "method"     : "GET",
      "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
      "client_ip"  : "11.0.3.111"
    },
    "response" : {
      "status"         : 200,
      "content_length" : 86
    }
  },
  "subsegments" : [
    {
      "id"         : "53995c3f42cd8ad8",
      "name"       : "api.example.com",
      "start_time" : 1461096053.37769,
      "end_time"   : 1461096053.40379,
      "namespace"  : "remote",
      "http"       : {
        "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
        },
        "response" : {
          "status"         : 200,
          "content_length" : 861
        }
      }
    }
  ]
}

Bei lang andauernden Anfragen können Sie ein Segment in Bearbeitung senden, um X-Ray darüber zu informieren, dass die Anfrage empfangen wurde, und dann Teilsegmente separat senden, um sie zu verfolgen, bevor Sie die ursprüngliche Anfrage abschließen.

Beispiel In Bearbeitung befindliches Segment
{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}
Beispiel Unabhängiges Untersegment

Ein unabhängiges Untersegment hat einen type-subsegment, eine trace_id und eine parent_id, die das übergeordnete Segment identifiziert.

{
  "name" : "api.example.com",
  "id" : "53995c3f42cd8ad8",
  "start_time" : 1.478293361271E9,
  "end_time" : 1.478293361449E9,
  "type" : "subsegment",
  "trace_id" : "1-581cf771-a006649127e371903a2de979"
  "parent_id" : "defdfd9912dc5a56",
  "namespace"  : "remote",
  "http"       : {
      "request"  : {
          "url"    : "https://api.example.com/health",
          "method" : "POST",
          "traced" : true
      },
      "response" : {
          "status"         : 200,
          "content_length" : 861
      }
  }
}

Schließen Sie das Segment nach Abschluss der Anforderung mit einer end_time. Das vollständige Segment überschreibt das sich in Bearbeitung befindliche Segment.

Sie können außerdem Untersegmente für abgeschlossene Anforderungen, die asynchrone Workflows auslösen, getrennt senden. Beispielsweise kann eine Web-API eine OK 200-Antwort, unmittelbar bevor die vom Benutzer angeforderte Arbeit beginnt, zurücksenden. Sie können ein vollständiges Segment an X-Ray senden, sobald die Antwort gesendet wurde, gefolgt von Teilsegmenten 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-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.

Die folgenden Felder sind für Untersegmente optional.

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

Wenn Sie einen Aufruf an eine nachgelagerte Web-API instrumentieren, zeichnen Sie ein Untersegment mit Informationen über die HTTP-Anfrage und -Antwort auf. X-Ray verwendet das -Teilsegment, um ein abgeleitetes Segment für die Remote-API zu generieren.

Beispiel Segment für einen HTTP-Aufruf, der von einer Anwendung, die über Amazon EC2 ausgeführt wird, bereitgestellt wird.
{
  "id": "6b55dcc497934f1a",
  "start_time": 1484789387.126,
  "end_time": 1484789387.535,
  "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }
Beispiel Untersegment für einen nachgelagerten HTTP-Aufruf
{
  "id": "004f72be19cddc2a",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "name": "names.example.com",
  "namespace": "remote",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  }
}
Beispiel Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{
  "id": "168416dc2ea97781",
  "name": "names.example.com",
  "trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
  "start_time": 1484786387.131,
  "end_time": 1484786387.501,
  "parent_id": "004f72be19cddc2a",
  "http": {
    "request": {
      "method": "GET",
      "url": "https://names.example.com/"
    },
    "response": {
      "content_length": -1,
      "status": 200
    }
  },
  "inferred": true
}

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 indiziert. Felder können eine Zeichenfolge, Zahl oder einen booleschen Werte (keine Objekte oder Arrays) umfassen. X-Ray indiziert bis zu 50 Anmerkungen pro Ablaufverfolgung.

Beispiel Segment für HTTP-Aufrufe mit Anmerkungen
{
  "id": "6b55dcc497932f1a",
  "start_time": 1484789187.126,
  "end_time": 1484789187.535,
  "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
  "name": "www.example.com",
  "origin": "AWS::EC2::Instance",
  "aws": {
    "ec2": {
      "availability_zone": "us-west-2c",
      "instance_id": "i-0b5a4678fc325bg98"
    },
    "xray": {
        "sdk_version": "2.11.0 for Java"
    },
  },
  "annotations": {
    "customer_category" : 124,
    "zip_code" : 98101,
    "country" : "United States",
    "internal" : false
  },
  "http": {
    "request": {
      "method": "POST",
      "client_ip": "78.255.233.48",
      "url": "http://www.example.com/api/user",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
      "x_forwarded_for": true
    },
    "response": {
      "status": 200
    }
  }

Die Schlüssel müssen alphanumerisch sein, um mit Filtern funktionieren zu können. Unterstriche sind zulässig. Andere Zeichen und Leerzeichen sind nicht zulässig.

Metadaten

Segmente und Untersegmente können ein metadata Objekt enthalten, das ein oder mehrere Felder mit Werten eines beliebigen Typs enthält, einschließlich Objekte und Arrays. X-Ray indiziert keine Metadaten und Werte können eine beliebige Größe haben, solange das Segmentdokument die maximale Größe (64 kB) nicht überschreitet. Sie können Metadaten im vollständigen Segmentdokument, das von der BatchGetTraces-API zurückgesendet wurde, einsehen. Feldschlüssel (debug im folgenden Beispiel), die mit beginnen, AWS. sind für die Verwendung durch von AWS bereitgestellte SDKs und Clientsreserviert.

Beispiel Individuelles Untersegment mit Metadaten
{
  "id": "0e58d2918e9038e8",
  "start_time": 1484789387.502,
  "end_time": 1484789387.534,
  "name": "## UserModel.saveUser",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
  "subsegments": [
    {
      "id": "0f910026178b71eb",
      "start_time": 1484789387.502,
      "end_time": 1484789387.534,
      "name": "DynamoDB",
      "namespace": "aws",
      "http": {
        "response": {
          "content_length": 58,
          "status": 200
        }
      },
      "aws": {
        "table_name": "scorekeep-user",
        "operation": "UpdateItem",
        "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
        "resource_names": [
          "scorekeep-user"
        ]
      }
    }
  ]
}

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 Multicontainer-Docker-Umgebung auf Elastic Beanstalk ausgeführt wird, Informationen über die Amazon EC2-Instance, den Amazon ECS-Container, der auf der Instance ausgeführt wird, und die Elastic Beanstalk-Umgebung selbst enthalten.

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.

Beispiel AWS -Block mit Plugins
"aws":{
   "elastic_beanstalk":{
      "version_label":"app-5a56-170119_190650-stage-170119_190650",
      "deployment_id":32,
      "environment_name":"scorekeep"
   },
   "ec2":{
      "availability_zone":"us-west-2c",
      "instance_id":"i-075ad396f12bc325a",
      "ami_id":
   },
   "cloudwatch_logs":[
      {
         "log_group":"my-cw-log-group",
         "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
      }
   ],
   "xray":{
      "auto_instrumentation":false,
      "sdk":"X-Ray for Java",
      "sdk_version":"2.8.0"
   }
}

Notieren Sie für Untersegmente Informationen über die - AWS -Services und -Ressourcen, auf die Ihre Anwendung zugreift. X-Ray verwendet diese Informationen, um abgeleitete Segmente zu erstellen, die die Downstream-Services in Ihrer Service-Übersicht darstellen.

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.

Beispiel Untersegment für einen Aufruf an 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 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).

Geben Sie die Fehlerursache an, indem Sie im Segment oder Untersegment ein Ursachenobjekt einschließen.

cause

Eine Ursache kann entweder eine 16-stellige Ausnahmen-ID oder ein Objekt mit den folgenden Feldern sein:

  • working_directory – Der vollständige Pfad des Arbeitsverzeichnisses, als die Ausnahme aufgetreten ist.

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

  • exceptions – Das Array von Ausnahmeobjekten.

Geben Sie detaillierte Informationen über die Fehler in einem oder mehreren Ausnahmenobjekten an.

exception

Alle Felder sind optional.

  • id – Eine 64-Bit-ID für die Ausnahme, die unter 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.

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 – 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.

Beispiel Untersegment mit einer SQL-Abfrage
{
  "id": "3fd8634e78ca9560",
  "start_time": 1484872218.696,
  "end_time": 1484872218.697,
  "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
  "namespace": "remote",
  "sql" : {
    "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
    "preparation": "statement",
    "database_type": "PostgreSQL",
    "database_version": "9.5.4",
    "driver_version": "PostgreSQL 9.4.1211.jre7",
    "user" : "dbuser",
    "sanitized_query" : "SELECT  *  FROM  customers  WHERE  customer_id=?;"
  }
}