Trace-Kontext

Mit Trace-Kontext und Kontextweitergabe können Ihre verteilten Anwendungen Anforderungs-IDs in Headern oder Metadaten zwischen Diensten weitergeben. Cloud Trace verwendet diesen gemeinsamen Kontext, um einzelne Spans zu vollständigen verteilten Traces zu verknüpfen, Ausführungshierarchien zu rekonstruieren und zu bewerten, ob Anfragen erfasst werden.

Funktionsweise der Kontextweitergabe

Wenn Ihre Anwendung eine Anfrage verarbeitet und Downstream-Dienste aufruft, werden Kennungen wie die Trace-ID, die übergeordnete Span-ID und der Sampling-Status über Anfrageheader oder Metadaten übergeben. 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 bei jedem Aufruf ein Bereich mit einer eindeutigen Bereichs-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 Stammspannen null.

Mithilfe dieser freigegebenen Kennungen rekonstruiert 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 erfolgreich war.

Protokolle für die Weitergabe von Kontext

In den folgenden Abschnitten wird beschrieben, wie der Kontext bei bestimmten Anfrageprotokollen weitergegeben wird.

HTTP-Anfragen

Bei HTTP-Anfragen erfolgt die Kontextweitergabe in der Regel über HTTP-Header wie traceparent und tracestate, die vom W3C standardisiert wurden. Der Header traceparent enthält die Kennungen, mit denen eine Anfrage eindeutig identifiziert wird. Der tracestate-Header ist hingegen optional und enthält anbieterspezifische Metadaten.

Der traceparent-Header hat das folgende Format:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

Die Felder des traceparent-Headers sind so definiert:

  • VERSION ist die Header-Version. Muss 00 lauten.
  • TRACE_ID ist ein aus 32 Zeichen bestehender hexadezimaler Wert, der für eine Zahl mit 128 Bit steht.
  • PARENT_SPAN_ID ist ein 16-stelliger Hexadezimalwert, der den übergeordneten Bereich identifiziert.
  • TRACE_FLAGS ist ein zweistelliger Hexadezimalwert, der die Sampling-Entscheidung des übergeordneten Elements angibt. Wenn ein übergeordneter Span stichprobenartig erfasst wurde, 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-Header X-Cloud-Trace-Context.

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

Alter X-Cloud-Trace-Context-Header

Der von Google Cloud verwendete X-Cloud-Trace-Context-Header 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 vorzeichenlosen Spannen-ID.
  • OPTIONS unterstützt 0 (übergeordnetes Element nicht in der Stichprobe) und 1 (übergeordnetes Element in der Stichprobe).

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

Kontextweitergabe 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 jeweiligenGoogle 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 der Trace-Kontext an untergeordnete Vorgänge weitergegeben wird.

Nächste Schritte