Trace traccia

Questo documento descrive brevemente il contesto, che si riferisce allo stato, e alla propagazione del contesto, che si riferisce al trasferimento delle informazioni sullo stato a le operazioni figlio. Per il tracciamento distribuito, l'ID traccia e l'ID del span in fase di elaborazione deve essere passato alle operazioni figlio.

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

  • Span ID: un identificatore univoco per l'operazione figlio. Se la stessa operazione viene eseguita più volte, più intervalli per l'operazione, ciascuno con un identificatore univoco.
  • ID traccia: l'identificatore univoco dell'operazione end-to-end in cui una determinata 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 è fornito dall'elemento 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 utilizza questi 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 World Wide Web Consortium (W3C) include informazioni su se l'intervallo principale è 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 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 traceparent
intestazione		 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, 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, 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 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'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 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 spazi generati dalla tua applicazione sono 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 utilizzi una libreria open source, determina se la propagazione del contesto è disponibile e se è necessaria 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