Trace-Kontext

Trace-Kontext und Kontextweitergabe sind die Mechanismen, mit denen Metadaten zwischen Vorgängen und Diensten weitergegeben werden, sodass Cloud Trace einzelne Spans zu einem vollständigen End-to-End-Trace verknüpfen kann.

Wenn Ihre Anwendung eine Anfrage verarbeitet und nachgelagerte Dienste aufruft, werden Kennungen wie die Trace-ID, die übergeordnete Span-ID und der Sampling-Status mithilfe von Anfrageheadern oder Metadaten weitergegeben. Untergeordnete Vorgänge verwenden diesen Kontext, um die folgenden Felder in neuen Spans auszufüllen:

  • Span-ID: Eine eindeutige Kennung für den untergeordneten Vorgang. Wenn ein Vorgang mehrmals ausgeführt wird, wird für jeden Aufruf ein Span mit einer eindeutigen Span-ID generiert.
  • Trace-ID: Die eindeutige Kennung der gesamten End-to-End-Anfrage, die vom übergeordneten Element bereitgestellt wird.
  • Übergeordnete Span-ID: Die eindeutige Kennung des aufrufenden übergeordneten Spans. Dieses Feld ist für Stamm-Spans null.

Mit diesen freigegebenen Kennungen rekonstruiert Cloud Trace die Ausführungshierarchie und misst die Latenz über alle beteiligten Dienste hinweg. Der Kontext kann auch zusätzliche Statusinformationen enthalten, z. B. ob eine Anfrage gesampeltwurde.

Protokolle für die Kontextweitergabe

In den folgenden Abschnitten wird beschrieben, wie der Kontext mit bestimmten Anfrageprotokollen 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. Der Header traceparent enthält die Kennungen, mit denen eine Anfrage eindeutig identifiziert wird. Im Gegensatz dazu ist der Header tracestate optional und enthält anbieterspezifische Metadaten.

Der Header traceparent hat das folgende Format:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

Die Felder des Headers traceparent sind wie folgt definiert:

  • VERSION ist die Header-Version. Muss 00 sein.
  • TRACE_ID ist ein aus 32 Zeichen bestehender hexadezimaler Wert, der für eine Zahl mit 128 Bit steht.
  • PARENT_SPAN_ID ist ein aus 16 Zeichen bestehender hexadezimaler Wert, der den übergeordneten Span identifiziert.
  • TRACE_FLAGS ist ein aus 2 Zeichen bestehender hexadezimaler Wert, der die Sampling-Entscheidung des übergeordneten Elements identifiziert. Wenn ein übergeordnetes Element den Span gesampelt hat, ist der Wert 01.

Google Cloud Dienste, die die Weitergabe von Trace-Kontext unterstützen, unterstützen in der Regel sowohl den traceparent als auch den Legacy-X-Cloud-Trace-Context Header.

Verwenden Sie nach Möglichkeit den traceparent Header in Ihren Anwendungen. Wenn eine Anwendung nur den Header X-Cloud-Trace-Context unterstützt, empfehlen wir, die Anwendung so zu aktualisieren, dass sie den Header traceparent unterstützt und priorisiert. 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 Bindestriche (-) Schrägstrich (/) und Semikolon (;)
Darstellung der Span-ID
 Hexadezimal Dezimal

Legacy-Header X-Cloud-Trace-Context

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

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

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

Die Felder des Headers sind wie folgt 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 vorzeichenlosen Span-ID.
  • OPTIONS unterstützt 0 (übergeordnetes Element nicht gesampelt) und 1 (übergeordnetes Element gesampelt).

gRPC-Anfragen

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

Für Komponenten, deren Inhaber Sie sind, empfehlen wir die Verwendung des Headers traceparent.

Kontextweitergabe für Google Cloud Dienste

Google Cloud Dienste können bei der Verarbeitung von Anfragen als Initiatoren oder Vermittler fungieren. Die folgenden Dienste sind beispielsweise an der Verarbeitung von Anfragen beteiligt:

Die Unterstützung für die Initiierung und Weitergabe von Trace-Kontext 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.

Kontextweitergabe in Ihren Anwendungen

Einige Instrumentierungsbibliotheken wie 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-Anwendung zu instrumentieren, sollte Ihre Anwendung SetTextMapPropagator aufrufen, wodurch der Kontext so konfiguriert wird, 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