Contexte de trace

Ce document décrit brièvement le contexte, qui fait référence à l'état, et la propagation de contexte, qui consiste à transmettre des informations d'état aux opérations enfants. Pour le traçage distribué, l'ID de trace et l'ID du le segment en cours de traitement doit ê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 plages pour cette opération, chacune avec un identifiant unique.
  • ID de trace: identifiant unique de l'opération de bout en bout pour laquelle une opération globale particulière a eu lieu. La valeur de ce champ est fournie par le parent.
  • Parent span ID: identifiant unique du segment parent. La valeur de ce champ est fournie par le parent. Pour les délais racine, cet ID est null.

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

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

Protocoles de propagation contextuelle

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 de 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 le W3C. Les services Google Cloud compatibles avec la propagation du contexte de trace acceptent généralement à la fois traceparent et l'ancien en-tête X-Cloud-Trace-Context.

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

Si votre application n'est compatible qu'avec l'en-tête X-Cloud-Trace-Context, nous vous recommandons de la mettre à jour pour qu'elle prenne en charge l'en-tête traceparent et qu'elle lui donne la priorité. Votre application peut continuer à utiliser l'en-tête X-Cloud-Trace-Context comme solution de secours.

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

Attribut En-tête traceparent
 X-Cloud-Trace-Context
en-tête
Séparateurs traits d'union (-) barre oblique (/) et point-virgul (;)
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 date d'avant la spécification du W3C. Pour des raisons de rétrocompatibilité, certains services Google Cloud continuent d'accepter, de générer et de propager l'en-tête X-Cloud-Trace-Context. Cependant, il est probablement que ces systèmes acceptent également 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 (parent non échantillonné) et 1 (parent échantillonné).

Requêtes gRPC

Pour les requêtes gRPC, la propagation contextuelle est effectuée à l'aide de 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 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 de 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 à traitement des demandes:

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

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 objets Span générées par votre application sont correctement configurées. Pour obtenir la liste des bibliothèques OpenTelemetry compatibles avec le traçage, consultez la section API et SDK de langage. Pour obtenir un exemple d'instrumentation, consultez la section Générer des traces et des métriques avec Go.

Si vous vous appuyez sur une bibliothèque Open Source, déterminez si la propagation de contexte est disponible et si une configuration est requise.

Lorsqu'il n'existe pas de bibliothèque d'instrumentation appropriée, vous devez vous assurer que votre application propage le contexte de trace aux opérations enfants.

Étape suivante