Questo documento descrive brevemente il contesto, che fa riferimento allo stato, e la propagazione del contesto, che si riferisce al trasferimento di informazioni sullo stato alle operazioni secondarie. Per il tracciamento distribuito, l'ID traccia e l'ID dell'intervallo da elaborare devono essere passati alle operazioni figlio.
Le operazioni figlio creano un intervallo e impostano i seguenti campi:
- ID intervallo: un identificatore univoco dell'operazione figlio. Se la stessa operazione viene eseguita più volte, saranno presenti più intervalli per l'operazione, ciascuno con un identificatore univoco.
- ID traccia: l'identificatore univoco dell'operazione end-to-end in cui si è verificata l'operazione complessiva specifica. Il valore di questo campo è fornito dall'elemento padre.
- ID intervallo padre: l'identificatore univoco dell'intervallo padre.
Il valore di questo campo è fornito dall'elemento padre.
Per gli intervalli principali, questo ID è
null
.
I valori dei campi ID traccia, ID intervallo e ID intervallo padre consentono a un sistema di tracciamento distribuito di collegare correttamente gli intervalli per formare una traccia. Ad esempio, Cloud Trace archivia gli intervalli in un repository e utilizza questi campi ID per identificare gli intervalli che compongono una traccia.
Il contesto può includere altre informazioni sullo stato, utili per il tracciamento distribuito. Ad esempio, lo standard World Wide Web Consortium (W3C) include informazioni che indicano se l'intervallo padre è stato campionato.
Protocolli per la propagazione del contesto
Le seguenti sezioni descrivono come specifici protocolli di richiesta propagano il contesto.
Richieste HTTP
Per le richieste HTTP, la propagazione del contesto viene in genere eseguita tramite intestazioni HTTP come le intestazioni traceparent
e tracestate
, che sono state standardizzate da W3C.
I servizi Google Cloud che supportano la propagazione del contesto delle tracce in genere supportano sia l'intestazione traceparent
sia l'intestazione X-Cloud-Trace-Context
legacy.
Se possibile, ti consigliamo di utilizzare
l'intestazione traceparent
nelle tue applicazioni. La tua
applicazione potrebbe dover utilizzare l'intestazione X-Cloud-Trace-Context
legacy o
supportare la ricezione del contesto di traccia in un formato diverso.
Se hai un'applicazione che supporta solo l'intestazione X-Cloud-Trace-Context
, ti consigliamo di aggiornare l'applicazione in modo che supporti e di dare priorità all'intestazione traceparent
. La tua applicazione può continuare a utilizzare l'intestazione X-Cloud-Trace-Context
come soluzione di riserva.
La seguente tabella riassume alcune differenze significative tra le due intestazioni:
Attributo | traceparent Intestazione |
X-Cloud-Trace-Context intestazione |
---|---|---|
Separatori | trattini (-) |
barra (/) e punto e virgola (;) |
Rappresentazione dell'ID intervallo |
Esadecimale | Decimale |
Intestazione X-Cloud-Trace-Context
precedente
L'intestazione X-Cloud-Trace-Context
utilizzata da Google Cloud è precedente alla specifica W3C.
Per la compatibilità con le versioni precedenti, alcuni servizi Google Cloud continuano ad accettare, generare e propagare l'intestazione X-Cloud-Trace-Context
. Tuttavia, è probabile che questi sistemi supportino anche l'intestazione traceparent
.
L'intestazione X-Cloud-Trace-Context
ha il seguente formato:
X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS
I campi dell'intestazione sono definiti come segue:
TRACE_ID
è un valore esadecimale di 32 caratteri che rappresenta un numero a 128 bit.SPAN_ID
è una rappresentazione decimale a 64 bit dell'ID intervallo senza segno.OPTIONS
supporta0
(elemento principale non campionato) e1
(elemento principale non campionato).
Richieste gRPC
Per le richieste gRPC, la propagazione del contesto viene eseguita utilizzando i metadati gRPC, che vengono implementati sopra le intestazioni HTTP. Le applicazioni gRPC potrebbero utilizzare l'intestazione traceparent
o una chiave di contesto dei metadati denominata grpc-trace-bin
.
Per i componenti di tua proprietà, è consigliabile utilizzare l'intestazione traceparent
.
Propagazione del contesto per i servizi Google Cloud
I servizi Google Cloud potrebbero fungere da iniziatori o intermediari nell'elaborazione delle richieste. Ad esempio, è noto che i seguenti servizi partecipano all'elaborazione delle richieste:
- Apigee
- App Engine
- Cloud Endpoints
- Cloud Functions
- Cloud Load Balancing
- Cloud Run
- Cloud Scheduler
- Cloud Tasks
- Pub/Sub
Il supporto per l'avvio e la propagazione del contesto delle tracce dipende dal servizio Google Cloud specifico. Per richiedere a un servizio Google Cloud di aggiungere il supporto per la propagazione del contesto, utilizza Google Issue Tracker.
Propagazione del contesto nelle applicazioni
Alcune librerie di strumentazione, come OpenTelemetry, propagano automaticamente un oggetto context
contenente i dati necessari per il tracciamento. Se utilizzi questi tipi di librerie, gli intervalli generati dalla tua applicazione sono configurati correttamente. Per un elenco delle librerie OpenTelemetry che supportano il tracciamento, consulta API e SDK di linguaggio. Per un esempio di strumentazione, consulta Generare tracce e metriche con Go.
Se utilizzi una libreria open source, determina se è disponibile la propagazione del contesto e se è richiesta la configurazione.
Se non esiste una libreria di strumentazione adatta, devi assicurarti che l'applicazione propaghi il contesto di traccia alle operazioni figlio.
Passaggi successivi
Scopri di più sul campionamento di Trace.
Risorse OpenTelemetry: