Trace della traccia

Questo documento descrive brevemente il contesto, che si riferisce allo stato, e la propagazione del contesto, che si riferisce al passaggio delle informazioni sullo stato alle operazioni secondarie. Per la traccia distribuita, l'ID traccia e l'ID dell'intervallo in fase di elaborazione devono essere passati alle operazioni secondarie.

Le operazioni secondarie creano un intervallo e impostano i seguenti campi:

  • ID intervallo: un identificatore univoco per l'operazione secondaria. Se la stessa operazione viene eseguita più volte, esistono più intervalli per l'operazione, ognuno con un identificatore univoco.
  • ID traccia: l'identificatore univoco dell'operazione end-to-end in cui si è svolta questa particolare operazione complessiva. Il valore di questo campo viene fornito dall'elemento principale.
  • ID intervallo principale: l'identificatore univoco dell'intervallo dell'elemento principale. Il valore di questo campo viene fornito dall'elemento principale. Per gli intervalli radice, questo ID è null.

I valori dei campi ID traccia, ID intervallo e ID intervallo principale consentono a un sistema di traccia distribuita 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 potrebbe includere altre informazioni sullo stato utili per la traccia distribuita. Ad esempio, lo standard del World Wide Web Consortium (W3C) include informazioni che indicano se l'intervallo principale è stato campionato.

Protocolli per la propagazione del contesto

Le seguenti sezioni descrivono in che modo i protocolli di richiesta specifici propagano il contesto.

Richieste HTTP

Per le richieste HTTP, la propagazione del contesto viene in genere eseguita tramite le intestazioni HTTP, come le intestazioni traceparent e tracestate, che sono state standardizzate dal W3C. Google Cloud I servizi che supportano la propagazione del contesto di traccia in genere supportano sia l'intestazione traceparent sia l'intestazione legacy X-Cloud-Trace-Context.

Quando possibile, ti consigliamo di utilizzare l' traceparent header nelle tue applicazioni. La tua applicazione potrebbe dover utilizzare l'intestazione legacy X-Cloud-Trace-Context 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 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 traceparent
intestazione		 X-Cloud-Trace-Context
intestazione
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 Google Cloud servizi continuano ad accettare, generare e propagare l'X-Cloud-Trace-Context intestazione. 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 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 denominata grpc-trace-bin.

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

Propagazione del contesto per i Google Cloud servizi

Google Cloud I servizi potrebbero fungere da iniziatori o intermediari nell'elaborazione delle richieste. Ad esempio, i seguenti servizi sono noti per partecipare all'elaborazione delle richieste:

Il supporto per l'inizializzazione e la propagazione del contesto di traccia è dipendente dal servizio specifico Google Cloud . Per richiedere a un Google Cloud servizio 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 traccia. Per un elenco delle librerie OpenTelemetry che supportano la traccia, consulta API e SDK di linguaggio.

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

Quando non è disponibile una libreria di strumentazione adatta, devi assicurarti che l'applicazione propaghi il contesto di traccia alle operazioni secondarie.

Passaggi successivi