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 délai 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, plusieurs segments 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 indiquée. 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 racines, cet ID est null.

Les valeurs des champs "ID de trace", "ID de délai" et "ID de délai parent" permettent à et un système de traçage distribué associent correctement des segments pour former une trace. Par exemple, Cloud Trace stocke les segments dans un dépôt et les utilise ID permettant d'identifier les segments 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) indique si le délai parent a été échantillonné.

Protocoles pour la propagation contextuelle

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

Requêtes HTTP

Pour les requêtes HTTP, la propagation contextuelle est généralement effectuée En-têtes HTTP tels que les en-têtes traceparent et tracestate, qui étaient standardisée 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 l'en-tête traceparent dans vos applications. Votre l'application peut avoir besoin d'utiliser l'ancien en-tête X-Cloud-Trace-Context peut avoir besoin de prendre en charge la réception du 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 accorde la priorité. 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 au W3C. Pour assurer la rétrocompatibilité, certains services Google Cloud continuent d'accepter, générer et propager l'en-tête X-Cloud-Trace-Context. Cependant, il est il est probable 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 (le parent non échantillonné) et 1 (le parent a été é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 les demandes en cours de traitement. 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 en fonction du service Google Cloud concerné. Pour demander à un service Google Cloud d'ajouter la prise en charge de la propagation contextuelle, utiliser l'outil Issue Tracker de Google.

Propagation contextuelle dans vos applications

Certaines bibliothèques d'instrumentation, telles qu'OpenTelemetry, propager automatiquement un objet context contenant les données nécessaires pour le 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 une liste les bibliothèques OpenTelemetry qui prennent en charge le traçage, consultez API et langages de programmation SDK. 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.

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

Étape suivante