Trace-Kontext

In diesem Dokument werden kurz Kontext, der sich auf den Status bezieht, und Kontextweitergabe, die sich auf die Weitergabe von Statusinformationen an untergeordnete Vorgänge, beschrieben. Bei der verteilten Aufrufabbildung müssen die Trace-ID und die ID der verarbeiteten Span an untergeordnete Vorgänge übergeben werden.

Untergeordnete Vorgänge erstellen einen Span und legen die folgenden Felder fest:

  • Span-ID: Eine eindeutige Kennung für den untergeordneten Vorgang. Wenn derselbe Vorgang mehrmals ausgeführt wird, gibt es mehrere Bereiche für diesen Vorgang, die jeweils eine eindeutige Kennung haben.
  • Trace-ID: Die eindeutige Kennung des End-to-End-Vorgangs, in dem dieser bestimmte Gesamtvorgang stattfand. Der Wert dieses Felds wird vom übergeordneten Element bereitgestellt.
  • Übergeordnete Span-ID: Die eindeutige Kennung der übergeordneten Span. Der Wert dieses Felds wird vom übergeordneten Element bereitgestellt. Bei Root-Spans ist diese ID null.

Anhand der Werte der Felder „Trace-ID“, „Span-ID“ und „Übergeordnete Span-ID“ kann ein verteiltes Trace-System Spans korrekt miteinander verknüpfen, um einen Trace zu bilden. In Cloud Trace werden beispielsweise Spans in einem Repository gespeichert. Anhand dieser ID-Felder wird ermittelt, aus welchen Spans ein Trace besteht.

Der Kontext kann auch andere Statusinformationen enthalten, die für die verteilte Fehlersuche nützlich sind. Der W3C-Standard (World Wide Web Consortium) enthält beispielsweise Informationen dazu, ob der übergeordnete Span beprobt wurde.

Protokolle für die Kontextweitergabe

In den folgenden Abschnitten wird beschrieben, wie bestimmte Anfrageprotokolle den Kontext weitergeben.

HTTP-Anfragen

Bei HTTP-Anfragen erfolgt die Kontextweitergabe in der Regel über HTTP-Header wie traceparent und tracestate, die vom W3C standardisiert wurden.Google Cloud Dienste, die die Weitergabe von Trace-Kontext unterstützen, unterstützen in der Regel sowohl den traceparent- als auch den alten X-Cloud-Trace-Context-Header.

Wir empfehlen, nach Möglichkeit den traceparent-Header in Ihren Anwendungen zu verwenden. Möglicherweise muss Ihre Anwendung den alten X-Cloud-Trace-Context-Header verwenden oder den Empfang von Trace-Kontext in einem anderen Format unterstützen.

Wenn Ihre Anwendung nur den X-Cloud-Trace-Context-Header unterstützt, empfehlen wir Ihnen, sie so zu aktualisieren, dass der traceparent-Header unterstützt und priorisiert wird. Sie können den X-Cloud-Trace-Context-Header weiterhin als Fallback-Lösung verwenden.

In der folgenden Tabelle sind einige wichtige Unterschiede zwischen den beiden Überschriften zusammengefasst:

Attribut traceparent
-Header		 X-Cloud-Trace-Context
-Header
Trennzeichen Bindestriche (-) Schrägstrich (/) und Semikolon (;)
Span-ID
darstellung		 Hexadezimal Dezimalzahl

Alter X-Cloud-Trace-Context-Header

Der X-Cloud-Trace-Context-Header, der von Google Cloud verwendet wird, stammt aus der Zeit vor der W3C-Spezifikation. Aus Gründen der Abwärtskompatibilität akzeptieren, generieren und leiten einige Google Cloud Dienste die X-Cloud-Trace-Context-Header weiterhin weiter. Es ist jedoch wahrscheinlich, dass diese Systeme auch den traceparent-Header unterstützen.

Der X-Cloud-Trace-Context-Header hat das folgende Format:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

Die Felder des Headers sind so definiert:

  • TRACE_ID ist ein aus 32 Zeichen bestehender hexadezimaler Wert, der für eine Zahl mit 128 Bit steht.
  • SPAN_ID ist eine 64-Bit-dezimal dargestellte vorzeichenlose Span-ID.
  • OPTIONS unterstützt 0 (Elternelement nicht ausgewählt) und 1 (Elternelement ausgewählt).

gRPC-Anfragen

Bei gRPC-Anfragen erfolgt die Kontextweitergabe mithilfe von gRPC-Metadaten, die über HTTP-Header implementiert werden. gRPC-Anwendungen können den traceparent-Header oder einen Metadatenkontextschlüssel namens grpc-trace-bin verwenden.

Für Komponenten, deren Inhaber Sie sind, empfehlen wir den Header traceparent.

Kontextweitergabe für Google Cloud -Dienste

Google Cloud -Dienste können als Initiatoren oder Vermittler bei der Anfrageverarbeitung fungieren. Beispielsweise sind die folgenden Dienste an der Verarbeitung von Anfragen beteiligt:

Die Unterstützung für die Initiierung und Weiterleitung von Trace-Kontexten hängt vom jeweiligen Dienst ab. Google Cloud Wenn Sie möchten, dass ein Google Cloud Dienst die Unterstützung für die Kontextweitergabe hinzufügt, verwenden Sie den Google Issue Tracker.

Kontextweitergabe in Ihren Apps

Einige Instrumentierungsbibliotheken wie OpenTelemetry können ein context-Objekt weitergeben, das die für die Verfolgung erforderlichen Daten enthält. Eine Liste der OpenTelemetry-Bibliotheken, die Tracing unterstützen, finden Sie unter Sprach-APIs und SDKs.

Wenn Sie eine Open-Source-Bibliothek verwenden, prüfen Sie, ob die Kontextweitergabe verfügbar ist und ob eine Konfiguration erforderlich ist. Wenn Sie beispielsweise OpenTelemetry zum Instrumentieren einer Go-Anwendung verwenden, sollte Ihre Anwendung SetTextMapPropagator aufrufen. Dadurch wird der Kontext so konfiguriert, dass das W3C-traceparent-Format verwendet wird. Ein Beispiel für die Instrumentierung finden Sie unter Traces und Messwerte mit Go generieren.

Wenn es keine geeignete Instrumentierungsbibliothek gibt, müssen Sie dafür sorgen, dass Ihre Anwendung den Trace-Kontext an untergeordnete Vorgänge weitergibt.

Nächste Schritte