Contexte de trace

Le contexte de trace et la propagation du contexte permettent à vos applications distribuées de transmettre des identifiants de requête entre les services dans des en-têtes ou des métadonnées. Cloud Trace utilise ce contexte partagé pour associer des spans individuels à des traces distribuées complètes, reconstruire des hiérarchies d'exécution et évaluer si les requêtes sont échantillonnées.

Fonctionnement de la propagation du contexte

Lorsque votre application traite une requête et appelle des services en aval, elle transmet des identifiants (tels que l'ID de trace, l'ID de segment 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 remplir les champs suivants dans les nouvelles portées :

  • ID de span : 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 de bout en bout globale, fourni par le parent.
  • ID du segment parent : identifiant unique du segment parent appelant. Ce champ est défini sur null pour les portées racines.

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

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. L'en-tête traceparent contient les identifiants permettant d'identifier de manière unique une requête. En revanche, l'en-tête tracestate est facultatif et contient des métadonnées spécifiques au fournisseur.

L'en-tête traceparent est au 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 est 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. Lorsque le parent a échantillonné le span, la valeur est 01.

Les servicesGoogle Cloud 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.

Si possible, utilisez l'en-tête traceparent dans vos applications. Si une application n'accepte que l'en-tête X-Cloud-Trace-Context, nous vous recommandons de la mettre à jour 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 quelques 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 (;)
Représentation de l'ID de portée
 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 est au 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 portée 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 qui vous appartiennent, 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 serviceGoogle 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 par 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 l'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