Trace delle tracce

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 traceparentIntestazione
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 supporta 0 (elemento principale non campionato) e 1 (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:

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