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 figlio 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 genitore.
  • ID intervallo padre: l'identificatore univoco dell'intervallo padre. Il valore di questo campo viene fornito dall'account principale. 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 collega correttamente gli intervalli per formare una traccia. Ad esempio, Cloud Trace archivia gli intervalli in un repository e li utilizza Campi ID per identificare gli intervalli che compongono una traccia.

Il contesto potrebbe includere altre informazioni di stato utili per distribuire per il tracciamento delle minacce. Ad esempio, lo standard del World Wide Web Consortium (W3C) include informazioni sul fatto che l'intervallo padre sia stato campionato.

Protocolli per la propagazione del contesto

Le seguenti sezioni descrivono come protocolli specifici di richiesta di propagare il contesto.

Richieste HTTP

Per le richieste HTTP, la propagazione del contesto in genere viene eseguita attraverso Intestazioni HTTP come le intestazioni traceparent e tracestate, che erano standardizzato da W3C. I servizi Google Cloud che supportano la propagazione del contesto di 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. Il tuo dell'applicazione potrebbe dover utilizzare l'intestazione X-Cloud-Trace-Context legacy potrebbe dover supportare la ricezione di contesto della traccia in un formato diverso.

Se la tua applicazione supporta soltanto X-Cloud-Trace-Context , ti consigliamo di aggiornare l'applicazione per supportare e dare la priorità, l'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 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 fungere da iniziatori o intermediari nella richiesta e l'elaborazione dei dati. Ad esempio, è noto che i seguenti servizi partecipano all'elaborazione delle richieste:

Il supporto per l'avvio e la propagazione del contesto della traccia è dipendono dal servizio Google Cloud specifico. Per richiedere che un servizio Google Cloud aggiunga il supporto per la propagazione del contesto, utilizzare Google Issue Tracker.

Propagazione del contesto nelle tue applicazioni

Alcune librerie di strumentazione, come OpenTelemetry, propaga automaticamente un oggetto context contenente i dati necessari per il tracciamento. Se utilizzi questi tipi di librerie, gli intervalli generati dalla tua applicazione siano configurati correttamente. Per un elenco di per le librerie OpenTelemetry che supportano il tracciamento, vedi API Language e SDK. Per una strumentazione consulta Generare tracce e metriche con Go.

Se ti affidi a una libreria open source, determina se sia disponibile la propagazione del contesto e se è richiesta la configurazione.

Se non è disponibile una libreria di strumentazione adatta, devi assicurarti che la tua applicazione si propaghi il contesto della traccia alle operazioni figlio.

Passaggi successivi