Trace 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 il monitoraggio distribuito, l'ID traccia e l'ID dello span in fase di elaborazione devono essere trasmessi alle operazioni secondarie.

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

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

I valori dei campi ID traccia, ID span e ID span principale consentono a un sistema di monitoraggio distribuito di collegare correttamente gli span 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 il monitoraggio distribuito. Ad esempio, lo standard World Wide Web Consortium (W3C) include informazioni su se l'intervallo principale è stato campionato.

Protocolli per la propagazione del contesto

Le seguenti sezioni 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 le intestazioni HTTP, come le intestazioni traceparent e tracestate, che sono state standardizzate dal W3C. I servizi Google Cloud che supportano la propagazione del contesto della traccia in genere supportano sia l'intestazione traceparent sia l'intestazione X-Cloud-Trace-Context precedente.

Se possibile, ti consigliamo di utilizzare l'intestazione traceparent nelle tue applicazioni. La tua applicazione potrebbe dover utilizzare l'intestazione X-Cloud-Trace-Context precedente o supportare la ricezione del contesto 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 Intestazione traceparent
 X-Cloud-Trace-Context
header
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 non firmato.
  • 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 metadati gRPC, che vengono implementati sulle 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 servizi Google Cloud

I servizi Google Cloud potrebbero agire come 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 particolare servizio Google Cloud. Per richiedere che un servizio Google Cloud aggiunga il supporto per la propagazione del contesto, utilizza il tracker dei problemi di Google.

Propagazione del contesto nelle applicazioni

Alcune librerie di strumenti, come OpenTelemetry, propaggono automaticamente un oggetto context contenente i dati necessari per il monitoraggio. Se utilizzi questi tipi di librerie, gli intervalli generati dalla tua applicazione sono configurati correttamente. Per un elenco delle librerie OpenTelemetry che supportano il monitoraggio, consulta API e SDK per i linguaggi. Per un esempio di strumentazione, consulta Generare tracce e metriche con Go.

Se utilizzi una libreria open source, determina se la propagazione del contesto è disponibile e se è necessaria la configurazione.

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

Passaggi successivi