Trace della traccia

Il contesto della traccia e la propagazione del contesto consentono alle applicazioni distribuite di passare gli identificatori di richiesta tra i servizi nelle intestazioni o nei metadati. Cloud Trace utilizza questo contesto condiviso per collegare i singoli intervalli in tracce distribuite complete, ricostruire le gerarchie di esecuzione e valutare se le richieste vengono campionate.

Come funziona la propagazione del contesto

Quando la tua applicazione gestisce una richiesta e chiama i servizi downstream, passa gli identificatori, come l'ID traccia, l'ID intervallo principale e lo stato di campionamento, utilizzando le intestazioni o i metadati delle richieste. Le operazioni secondarie utilizzano questo contesto per compilare i seguenti campi nei nuovi intervalli:

  • ID span: un identificatore univoco per l'operazione secondaria. Se un'operazione viene eseguita più volte, ogni invocazione genera uno span con un ID span distinto.
  • ID traccia: l'identificatore univoco della richiesta end-to-end complessiva, fornito dal genitore.
  • ID span padre: l'identificatore univoco dello span padre chiamante. Questo campo è null per gli span radice.

Utilizzando questi identificatori condivisi, Trace ricostruisce la gerarchia di esecuzione e misura la latenza in tutti i servizi partecipanti. Il contesto può includere anche informazioni aggiuntive sullo stato, ad esempio se una richiesta è stata campionata.

Protocolli per la propagazione del contesto

Le sezioni seguenti descrivono in che modo protocolli di richiesta specifici 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 dal W3C. L'intestazione traceparent contiene gli identificatori per identificare in modo univoco una richiesta. Al contrario, l'intestazione tracestate è facoltativa e contiene metadati specifici del fornitore.

L'intestazione traceparent ha il seguente formato:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

I campi dell'intestazione traceparent sono definiti come segue:

  • VERSION è la versione dell'intestazione. Deve essere 00.
  • TRACE_ID è un valore esadecimale di 32 caratteri che rappresenta un numero a 128 bit.
  • PARENT_SPAN_ID è un valore esadecimale di 16 caratteri che identifica lo span principale.
  • TRACE_FLAGS è un valore esadecimale di 2 caratteri che identifica la decisione di campionamento del genitore. Quando un elemento principale ha campionato lo span, il valore è 01.

Google Cloud I servizi che supportano la propagazione del contesto della traccia in genere supportano sia l'intestazione traceparent sia l'intestazione legacy X-Cloud-Trace-Context.

Se possibile, utilizza l'intestazione traceparent nelle tue applicazioni. Se un'applicazione supporta solo l'intestazione X-Cloud-Trace-Context, ti consigliamo di aggiornarla in modo che supporti e dia la 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 Intestazione traceparent
 Intestazione X-Cloud-Trace-Context
Separatori trattini (-) barra (/) e punto e virgola (;)
Rappresentazione dell'ID intervallo
 Esadecimale Decimale

Intestazione legacy X-Cloud-Trace-Context

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 non firmato.
  • OPTIONS supporta 0 (genitore non campionato) e 1 (genitore campionato).

Richieste gRPC

Per le richieste gRPC, la propagazione del contesto viene eseguita utilizzando i metadati gRPC, implementati sopra le intestazioni HTTP. Le applicazioni gRPC potrebbero utilizzare l'intestazione traceparent o una chiave di contesto dei metadati chiamata grpc-trace-bin.

Per i componenti di tua proprietà, ti consigliamo di utilizzare l'intestazione traceparent.

Propagazione del contesto per i servizi Google Cloud

I serviziGoogle 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'inizializzazione e la propagazione del contesto della traccia dipende dal servizioGoogle 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, possono propagare un oggetto context che contiene i dati necessari per la tracciabilità. Per un elenco delle librerie OpenTelemetry che supportano la tracciabilità, consulta API e SDK per linguaggio.

Se utilizzi una libreria open source, determina se la propagazione del contesto è disponibile e se è necessaria la configurazione. Ad esempio, se utilizzi OpenTelemetry per instrumentare un'app Go, l'app deve chiamare SetTextMapPropagator, che configura il contesto per utilizzare il formato W3C traceparent. Per un esempio, vedi Esempio di instrumentazione Go.

Quando non è presente una libreria di strumentazione adatta, devi assicurarti che la tua applicazione propaghi il contesto della traccia alle operazioni secondarie.

Passaggi successivi