Contexte de trace

Ce document décrit brièvement le contexte, qui fait référence à l'état, et la propagation du contexte, qui fait référence à la transmission des informations d'état aux opérations enfants. Pour le traçage distribué, l'ID de trace et l'ID de la portée en cours de traitement doivent être transmis aux opérations enfants.

Les opérations enfants créent un span et définissent les champs suivants :

  • ID de span : identifiant unique de l'opération enfant. Si la même opération est exécutée plusieurs fois, il existe plusieurs spans pour cette opération, chacun avec un identifiant unique.
  • ID de trace : identifiant unique de l'opération de bout en bout dans laquelle cette opération globale particulière a eu lieu. La valeur de ce champ est fournie par le parent.
  • ID du segment parent : identifiant unique du segment parent. La valeur de ce champ est fournie par le parent. Pour les portées racine, cet ID est null.

Les valeurs des champs "ID de trace", "ID de segment" et "ID de segment parent" permettent à un système de traçage distribué de relier correctement les segments entre eux pour former une trace. Par exemple, Cloud Trace stocke les spans dans un dépôt et utilise ces champs d'ID pour identifier les spans qui composent une trace.

Le contexte peut inclure d'autres informations d'état utiles pour le traçage distribué. Par exemple, la norme du World Wide Web Consortium (W3C) inclut des informations indiquant si le span parent a été échantillonné.

Protocoles de propagation du contexte

Les sections suivantes décrivent comment les protocoles de requête spécifiques propagent le contexte.

Requêtes HTTP

Pour les requêtes HTTP, la propagation du contexte est généralement effectuée à l'aide d'en-têtes HTTP tels que les en-têtes traceparent et tracestate, qui ont été normalisés par le W3C. Les servicesGoogle Cloud qui prennent en charge la propagation du contexte de trace sont généralement compatibles avec l'en-tête traceparent et l'ancien en-tête X-Cloud-Trace-Context.

Dans la mesure du possible, nous vous recommandons d'utiliser l'en-tête traceparent dans vos applications. Votre application peut avoir besoin d'utiliser l'ancien en-tête X-Cloud-Trace-Context ou de prendre en charge la réception du contexte de trace dans un format différent.

Si vous disposez d'une application qui n'accepte que l'en-tête X-Cloud-Trace-Context, nous vous recommandons de mettre à jour votre application pour qu'elle accepte et privilégie l'en-tête traceparent. Votre application peut continuer à utiliser l'en-tête X-Cloud-Trace-Context comme solution de secours.

Le tableau suivant récapitule certaines différences importantes entre les deux en-têtes :

Attribut En-tête traceparent
 En-tête X-Cloud-Trace-Context
Séparateurs traits d'union (-) barre oblique (/) et point-virgule (;)
ID du délai
représentation		 Hexadécimal Decimal

Ancien en-tête X-Cloud-Trace-Context

L'en-tête X-Cloud-Trace-Context utilisé par Google Cloud est antérieur à la spécification W3C. Pour assurer la rétrocompatibilité, certains services Google Cloud continuent d'accepter, de générer et de propager l'en-tête X-Cloud-Trace-Context. Toutefois, il est probable que ces systèmes soient également compatibles avec l'en-tête traceparent.

L'en-tête X-Cloud-Trace-Context a le format suivant :

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

Les champs de l'en-tête sont définis comme suit :

  • TRACE_ID est une valeur hexadécimale de 32 caractères. Elle représente un nombre de 128 bits.
  • SPAN_ID est une représentation décimale 64 bits de l'ID de délai non signé.
  • OPTIONS accepte 0 (parent non échantillonné) et 1 (parent échantillonné).

Requêtes gRPC

Pour les requêtes gRPC, la propagation du contexte s'effectue à l'aide des métadonnées gRPC, qui sont implémentées au-dessus des en-têtes HTTP. Les applications gRPC peuvent utiliser l'en-tête traceparent ou une clé de contexte de métadonnées appelée grpc-trace-bin.

Pour les composants dont vous êtes propriétaire, nous vous recommandons d'utiliser l'en-tête traceparent.

Propagation du contexte pour les services Google Cloud

Les servicesGoogle Cloud peuvent agir en tant qu'initiateurs ou intermédiaires dans le traitement des requêtes. Par exemple, les services suivants sont connus pour participer au traitement des requêtes :

La prise en charge de l'initiation et de la propagation du contexte de trace dépend du service Google Cloud spécifique. Pour demander à un service Google Cloud d'ajouter la prise en charge de la propagation du contexte, utilisez Google Issue Tracker.

Propagation du contexte dans vos applications

Certaines bibliothèques d'instrumentation, telles qu'OpenTelemetry, peuvent propager un objet context contenant les données nécessaires au traçage. Pour obtenir la liste des bibliothèques OpenTelemetry compatibles avec le traçage, consultez API et SDK de langage.

Si vous vous appuyez sur une bibliothèque Open Source, déterminez si la propagation du contexte est disponible et si une configuration est requise. Par exemple, si vous utilisez OpenTelemetry pour instrumenter une application Go, votre application doit appeler SetTextMapPropagator, qui configure le contexte pour utiliser le format traceparent W3C. Pour obtenir un exemple, consultez Exemple d'instrumentation Go.

En l'absence de bibliothèque d'instrumentation appropriée, vous devez vous assurer que votre application propage le contexte de trace aux opérations enfants.

Étapes suivantes