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
accepte0
(parent non échantillonné) et1
(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:
- Apigee
- App Engine
- Cloud Endpoints
- Fonctions Cloud Run
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
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
En savoir plus sur l'échantillonnage de traces
Ressources OpenTelemetry :