In diesem Dokument wird kurz Kontext beschrieben, der sich auf den Zustand bezieht, und die Kontextweitergabe, die sich auf die Weitergabe von Statusinformationen an untergeordnete Vorgänge bezieht. Für verteiltes Tracing müssen die Trace-ID und die ID des verarbeiteten Spans 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 für diesen Vorgang mehrere Spans mit jeweils einer eindeutigen Kennung.
- Trace-ID: Die eindeutige Kennung des End-to-End-Vorgangs, in dem dieser bestimmte Gesamtvorgang stattgefunden hat. Der Wert dieses Feldes wird vom übergeordneten Element bereitgestellt.
- ID des übergeordneten Spans: Die eindeutige Kennung des übergeordneten Spans.
Der Wert dieses Felds wird vom übergeordneten Element bereitgestellt.
Für Haupt-Spans lautet diese ID
null
.
Anhand der Werte der Felder Trace-ID, Span-ID und übergeordnete Span-IDs kann ein verteiltes Tracing-System Spans korrekt miteinander verknüpfen, um ein Trace zu bilden. Cloud Trace speichert beispielsweise Spans in einem Repository und verwendet diese ID-Felder, um zu ermitteln, aus welchen Spans ein Trace besteht.
Der Kontext kann andere Statusinformationen umfassen, die für verteiltes Tracing nützlich sind. Der Standard des World Wide Web Consortium (W3C) enthält beispielsweise Informationen darüber, ob der übergeordnete Span als Stichproben genutzt wurde.
Protokolle für die Kontextweitergabe
In den folgenden Abschnitten wird beschrieben, wie bei bestimmten Anfrageprotokollen Kontext weitergegeben wird.
HTTP-Anfragen
Bei HTTP-Anfragen erfolgt die Kontextverteilung in der Regel über HTTP-Header wie die traceparent
- und tracestate
-Header, die von W3C standardisiert wurden.
Google Cloud-Dienste, die die Weitergabe von Trace-Kontext unterstützen, unterstützen in der Regel sowohl traceparent
als auch den Legacy-X-Cloud-Trace-Context
-Header.
Wir empfehlen, in Ihren Anwendungen nach Möglichkeit den traceparent
-Header zu verwenden. Ihre Anwendung muss möglicherweise den Legacy-Header X-Cloud-Trace-Context
verwenden oder den Empfang von Trace-Kontext in einem anderen Format unterstützen.
Wenn Sie eine Anwendung haben, die nur den Header X-Cloud-Trace-Context
unterstützt, empfehlen wir Ihnen, Ihre Anwendung so zu aktualisieren, dass sie den Header traceparent
unterstützt und priorisiert. Ihre Anwendung kann den X-Cloud-Trace-Context
-Header weiterhin als Fallback-Lösung verwenden.
In der folgenden Tabelle sind einige wesentliche Unterschiede zwischen den beiden Headern zusammengefasst:
Attribut | traceparent -Header |
X-Cloud-Trace-Context Überschrift |
---|---|---|
Trennzeichen | Bindestriche (-) |
Schrägstrich (/) und Semikolon (;) |
Span-ID- Darstellung |
Hexadezimal | Dezimal |
Legacy-X-Cloud-Trace-Context
-Header
Der von Google Cloud verwendete Header X-Cloud-Trace-Context
liegt vor der W3C-Spezifikation.
Aus Gründen der Abwärtskompatibilität akzeptieren, generieren und propagieren einige Google Cloud-Dienste den Header X-Cloud-Trace-Context
weiterhin. Es ist jedoch wahrscheinlich, dass diese Systeme auch den Header traceparent
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 die dezimale 64-Bit-Darstellung der Span-ID ohne Vorzeichen.OPTIONS
unterstützt0
(übergeordnetes Element nicht als Stichprobe) und1
(übergeordnetes Element wurde als Stichprobe verwendet).
gRPC-Anfragen
Für gRPC-Anfragen erfolgt die Kontextverteilung mithilfe von gRPC-Metadaten, die zusätzlich zu HTTP-Headern implementiert werden. gRPC-Anwendungen können den Header traceparent
oder einen Metadatenkontextschlüssel namens grpc-trace-bin
verwenden.
Für Komponenten, deren Inhaber Sie sind, empfehlen wir die Verwendung des Headers traceparent
.
Kontextverteilung für Google Cloud-Dienste
Google Cloud-Dienste können als Initiatoren oder Vermittler bei der Anfrageverarbeitung fungieren. Beispielsweise sind die folgenden Dienste bekannt dafür, dass sie an der Verarbeitung von Anfragen beteiligt sind:
- Apigee
- App Engine
- Cloud Endpoints
- Cloud Functions
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
Die Unterstützung für die Initiierung und Weitergabe von Trace-Kontext hängt vom jeweiligen Google Cloud-Dienst ab. Wenn ein Google Cloud-Dienst Unterstützung für die Kontextverteilung hinzufügen soll, verwenden Sie den Google Issue Tracker.
Weitergabe von Kontext in Ihren Anwendungen
Einige Instrumentierungsbibliotheken, z. B. OpenTelemetry, propagieren automatisch ein context
-Objekt, das die für das Tracing erforderlichen Daten enthält. Bei Verwendung dieser Bibliothekentypen sind die von Ihrer Anwendung generierten Spans ordnungsgemäß konfiguriert. Eine Liste der OpenTelemetry-Bibliotheken, die Tracing unterstützen, finden Sie unter Language APIs und SDKs. Ein Instrumentierungsbeispiel finden Sie unter Traces und Messwerte mit Go generieren.
Wenn Sie auf eine Open-Source-Bibliothek angewiesen sind, prüfen Sie, ob die Kontextweitergabe verfügbar ist und ob eine Konfiguration erforderlich ist.
Ist keine geeignete Instrumentierungsbibliothek vorhanden, müssen Sie dafür sorgen, dass Ihre Anwendung den Trace-Kontext an untergeordnete Vorgänge weitergibt.
Nächste Schritte
Weitere Informationen zu Trace Sampling
OpenTelemetry-Ressourcen: