Trace-Kontext

In diesem Dokument werden Kontext (der sich auf den Status bezieht) und Kontextweitergabe (die sich auf das Übergeben von Statusinformationen an untergeordnete Vorgänge bezieht) kurz beschrieben. Für das verteilte Tracing müssen die Trace-ID und die ID des verarbeiteten Spans an untergeordnete Vorgänge übergeben werden.

Bei untergeordneten Vorgängen wird ein Span erstellt und die folgenden Felder werden festgelegt:

  • Span-ID: Eine eindeutige Kennung für den untergeordneten Vorgang. Wenn derselbe Vorgang mehrmals ausgeführt wird, gibt es mehrere Spans 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 stattgefunden hat. Der Wert dieses Felds wird vom übergeordneten Element bereitgestellt.
  • Übergeordnete Span-ID: Die eindeutige Kennung des Spans des übergeordneten Elements. Der Wert dieses Felds wird vom übergeordneten Element bereitgestellt. Bei Root-Spans ist diese ID null.

Mithilfe der Werte der Felder „Trace-ID“, „Span-ID“ und „Übergeordnete Span-ID“ kann ein System für verteiltes Tracing Spans korrekt verknüpfen, um einen Trace zu bilden. In Cloud Trace werden Spans beispielsweise in einem Repository gespeichert. Anhand dieser ID-Felder wird ermittelt, welche Spans zu einem Trace gehören.

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

Protokolle für die Weitergabe von Kontext

In den folgenden Abschnitten wird beschrieben, wie der Kontext über bestimmte Anfrageprotokolle weitergegeben wird.

HTTP-Anfragen

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

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

Wenn Sie eine Anwendung haben, die nur den X-Cloud-Trace-Context-Header unterstützt, empfehlen wir, dass Sie Ihre Anwendung aktualisieren, um den traceparent-Header zu unterstützen und zu priorisieren. Ihre Anwendung kann den Header X-Cloud-Trace-Context weiterhin als Fallback-Lösung verwenden.

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

Attribut traceparent
-Header		 X-Cloud-Trace-Context
-Header
Trennzeichen zwischen Zeilen Bindestriche (-) Schrägstrich (/) und Semikolon (;)
Span-ID
Darstellung		 Hexadezimal Dezimal

Alter X-Cloud-Trace-Context-Header

Der Header X-Cloud-Trace-Context, der von Google Cloud verwendet wird, ist älter als die W3C-Spezifikation. Aus Gründen der Abwärtskompatibilität akzeptieren, generieren und übertragen einige Google Cloud Dienste weiterhin den X-Cloud-Trace-Context-Header. 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-Dezimaldarstellung der Span-ID ohne Vorzeichen.
  • OPTIONS unterstützt 0 (übergeordnetes Element nicht berücksichtigt) und 1 (übergeordnetes Element wurde berücksichtigt).

gRPC-Anfragen

Bei gRPC-Anfragen erfolgt die Kontextweitergabe über gRPC-Metadaten, die auf HTTP-Headern basieren. gRPC-Anwendungen verwenden möglicherweise den Header traceparent oder einen Metadatenkontextschlüssel namens grpc-trace-bin.

Für Komponenten, die Ihnen gehören, empfehlen wir die Verwendung des traceparent-Headers.

Weitergabe von Kontext für Google Cloud -Dienste

Google Cloud -Dienste können als Initiatoren oder Vermittler bei der Verarbeitung von Anfragen fungieren. Die folgenden Dienste sind beispielsweise bekannt dafür, dass sie Anfragen verarbeiten:

Die Unterstützung für die Initiierung und Weitergabe des Trace-Kontexts hängt vom jeweiligen Google Cloud Dienst ab. Wenn Sie möchten, dass ein Google Cloud -Dienst die Kontextweitergabe unterstützt, verwenden Sie den Google Issue Tracker.

Weitergabe von Kontext in Ihren Anwendungen

Einige Instrumentierungsbibliotheken, z. B. OpenTelemetry, können ein context-Objekt weitergeben, das die für das Tracing 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 verwenden, um eine Go-App zu instrumentieren, sollte Ihre App SetTextMapPropagator aufrufen. Dadurch wird der Kontext so konfiguriert, dass das W3C-Format traceparent verwendet wird. Ein Beispiel finden Sie unter Go-Instrumentierungsbeispiel.

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

Nächste Schritte