Contexte de trace

Le contexte de trace et la propagation du contexte sont les mécanismes utilisés pour transmettre des métadonnées entre les opérations et les services afin que Cloud Trace puisse associer des délais individuels dans une trace distribuée complète de bout en bout.

Lorsque votre application gère une requête et appelle des services en aval, elle transmet des identifiants (tels que l'ID de trace, l'ID de délai parent et l'état d'échantillonnage) à l'aide d'en-têtes de requête ou de métadonnées. Les opérations enfants utilisent ce contexte pour renseigner les champs suivants sur les nouveaux délais :

  • ID de segment : identifiant unique de l'opération enfant. Si une opération est exécutée plusieurs fois, chaque appel génère un segment avec un ID de segment distinct.
  • ID de trace : identifiant unique de la requête globale de bout en bout, fourni par le parent.
  • ID du segment parent : identifiant unique du segment parent appelant. Ce champ est null pour les délais racines.

À l'aide de ces identifiants partagés, Cloud Trace reconstruit la hiérarchie d'exécution et mesure la latence sur tous les services participants. Le contexte peut également inclure des informations d'état supplémentaires, par exemple si une requête a été échantillonnée.

Protocoles de propagation du contexte

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

Requêtes HTTP

Pour les requêtes HTTP, la propagation du contexte s'effectue généralement via des en-têtes HTTP tels que les en-têtes traceparent et tracestate, qui ont été normalisés par le W3C. L'en-tête traceparent contient les identifiants permettant d'identifier une requête de manière unique. En revanche, l'en-tête tracestate est facultatif et contient des métadonnées spécifiques au fournisseur.

L'en-tête traceparent présente le format suivant :

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

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

  • VERSION correspond à la version de l'en-tête. Doit être 00.
  • TRACE_ID est une valeur hexadécimale de 32 caractères. Elle représente un nombre de 128 bits.
  • PARENT_SPAN_ID est une valeur hexadécimale de 16 caractères qui identifie le segment parent.
  • TRACE_FLAGS est une valeur hexadécimale de deux caractères qui identifie la décision d'échantillonnage du parent. Lorsqu'un parent a échantillonné le délai, la valeur est 01.

Google Cloud Les services qui acceptent 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, utilisez l'en-tête traceparent dans vos applications. Si une application n'est compatible qu'avec l'en-tête X-Cloud-Trace-Context, nous vous recommandons de la mettre à jour pour qu'elle soit compatible avec l'en-tête traceparent et qu'elle le privilégie. 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 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 Décimal

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 Google Cloud services 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 présente 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 du contexte s'effectue à l'aide de métadonnées gRPC, qui sont implémentées en plus 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 Google Cloud services

Google Cloud Les services 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 compatibilité avec l'initiation et la propagation du contexte de trace dépend du service spécifique Google Cloud . Pour demander à un Google Cloud service d'ajouter la compatibilité avec la propagation du contexte, utilisez l'outil de suivi des problèmes de Google.

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 la page API et SDK de langage.

Si vous utilisez 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 l'exemple d'instrumentation Go.

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

Étape suivante