Contexte de trace

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

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

  • ID de délai: identifiant unique de l'opération enfant. Si la même opération est exécutée plusieurs fois, il existe plusieurs délais 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.
  • Parent span ID (ID de segment parent) : identifiant unique du segment parent. La valeur de ce champ est fournie par le parent. Pour les délais racines, cet ID est null.

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

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

Protocoles pour la propagation du contexte

Les sections suivantes décrivent comment des protocoles de requête spécifiques se propagent au contexte.

Requêtes HTTP

Pour les requêtes HTTP, la propagation du contexte est généralement effectuée via des en-têtes HTTP tels que les en-têtes traceparent et tracestate, qui ont été normalisés par W3C. Les services Google Cloud compatibles avec la propagation du contexte de trace sont généralement compatibles avec l'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 devra peut-être utiliser l'ancien en-tête X-Cloud-Trace-Context ou accepter la réception de contexte de trace dans un format différent.

Si votre application n'accepte que l'en-tête X-Cloud-Trace-Context, nous vous recommandons de la mettre à jour pour qu'elle accepte et donne la priorité à l'en-tête traceparent. Votre application peut continuer à utiliser l'en-tête X-Cloud-Trace-Context comme solution de remplacement.

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

Attribut traceparent
en-tête		 X-Cloud-Trace-Context
en-tête
Séparateurs traits d'union (-) barre oblique (/) et point-virgule (;)
Représentation de l'ID
du délai		 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 de 64 bits de l'ID de délai non signé.
  • OPTIONS accepte 0 (le parent non échantillonné) et 1 (le parent a été échantillonné).

Requêtes gRPC

Pour les requêtes gRPC, la propagation du contexte est effectuée à l'aide de métadonnées gRPC, mises en œuvre 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 qui vous appartiennent, nous vous recommandons d'utiliser l'en-tête traceparent.

Propagation du contexte pour les services Google Cloud

Les services Google 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 concerné. 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, propagent automatiquement un objet context contenant les données nécessaires au traçage. Si vous utilisez ces types de bibliothèques, les segments générés par votre application sont correctement configurés. Pour obtenir la liste des bibliothèques OpenTelemetry compatibles avec le traçage, consultez la page API et SDK de langage. Pour obtenir un exemple d'instrumentation, consultez Générer des traces et des métriques avec Go.

Si vous utilisez une bibliothèque Open Source, déterminez si la propagation contextuelle est disponible et si une configuration est requise.

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

Étapes suivantes