Trace della traccia

Il contesto di traccia e la propagazione del contesto sono i meccanismi utilizzati per passare i metadati tra operazioni e servizi in modo che Cloud Trace possa collegare i singoli intervalli in una traccia distribuita completa end-to-end.

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

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

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

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, 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 di 128 bit.
  • PARENT_SPAN_ID è un valore esadecimale di 16 caratteri che identifica l'intervallo padre.
  • TRACE_FLAGS è un valore esadecimale di 2 caratteri che identifica la decisione di campionamento del padre. Quando un padre ha campionato l'intervallo, il valore è 01.

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

Quando possibile, utilizza l'intestazione traceparent nelle tue applications. 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 traceparent
header		 X-Cloud-Trace-Context
header
Separatori trattini (-) barra (/) e punto e virgola (;)
Rappresentazione dell'ID intervallo
 Esadecimale Decimale

Intestazione precedente 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 di 128 bit.
  • SPAN_ID è una rappresentazione decimale a 64 bit dell'ID intervallo senza segno.
  • OPTIONS supporta 0 (padre non campionato) e 1 (padre 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 dipende 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 la 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