Strumento per Cloud Trace

Questo documento fornisce una breve panoramica su come implementare la tua applicazione per Cloud Trace. Per istruzioni dettagliate sulla configurazione di Cloud Trace, consulta le pagine di configurazione specifiche per le lingue.

Cloud Trace fornisce dati di tracciamento distribuiti per le tue applicazioni. Dopo aver implementato l'applicazione, puoi esaminare i dati di latenza per una singola richiesta e visualizzare la latenza aggregata per un'intera applicazione nella console Cloud Trace.

Quando implementare la tua applicazione

Quando i dati di traccia non vengono acquisiti automaticamente, devi instrumentare l'applicazione per raccoglierli.

Puoi strumentare l'applicazione in modo che raccolga informazioni specifiche. Diversi framework di strumentazione open source consentono di raccogliere metriche, log e tracce dall'applicazione e inviare i dati a qualsiasi fornitore, incluso Google Cloud. Per implementare la tua applicazione, ti consigliamo di utilizzare un framework di strumentazione open source indipendente dal fornitore, come OpenTelemetry, anziché API o librerie client specifiche del fornitore e del prodotto.

Per informazioni sulla strumentazione delle tue applicazioni utilizzando framework di strumentazione indipendenti dal fornitore, consulta Strumentazione e osservabilità.

Come implementare le applicazioni

Per suggerimenti sulla instrumentazione delle applicazioni per raccogliere log, metriche e tracce, consulta Scegli un approccio per la strumentazione.

Per consentire alle applicazioni di raccogliere dati di traccia, puoi eseguire una delle seguenti operazioni:

Quando creare intervalli

Le librerie client di Cloud Trace in genere gestiscono un contesto di traccia globale che contiene informazioni sull'intervallo attuale, tra cui l'ID traccia e l'eventuale campionamento della traccia. Queste librerie in genere creano intervalli sui confini RPC. Tuttavia, potrebbe essere necessario creare intervalli se l'algoritmo di creazione predefinito non è sufficiente per le tue esigenze.

È possibile accedere all'intervallo attivo corrente dal contesto della traccia globale, che a volte è aggregato in un oggetto Tracer. Puoi aggiungere informazioni pertinenti alla tua applicazione utilizzando annotazioni e tag personalizzati agli intervalli esistenti oppure puoi creare nuovi intervalli secondari con annotazioni e tag propri per tracciare il comportamento dell'applicazione con maggiore granularità. Poiché il contesto è globale, le applicazioni multi-thread che lo aggiornano devono utilizzare l'isolamento appropriato.

Quando fornire le credenziali di autenticazione

Durante l'esecuzione su Google Cloud, di solito non è necessario fornire le credenziali di autenticazione all'applicazione o specificare l'ID progetto Google Cloud nell'applicazione. Per alcune lingue, devi specificare il tuo ID progetto Google Cloud anche se esegui su Google Cloud. Inoltre, se utilizzi la modalità Autopilot per Google Kubernetes Engine o se abiliti Workload Identity, devi configurare la tua applicazione per l'utilizzo di Workload Identity.

Se l'esecuzione avviene al di fuori di Google Cloud, devi fornire le credenziali di autenticazione all'applicazione. Devi anche specificare il tuo ID progetto Google Cloud nell'applicazione.

Per informazioni dettagliate, vai alle pagine di configurazione specifiche per la lingua.

Come forzare il tracciamento di una richiesta

A meno che l'applicazione non campiona sempre ogni intervallo, in generale non è possibile forzare la traccia end-to-end di una richiesta, poiché ogni componente di una richiesta end-to-end prende la propria decisione di campionamento. Tuttavia, puoi influenzare la decisione aggiungendo all'intestazione della traccia un flag sampled, con questo flag impostato su true. Questa impostazione è un suggerimento per i componenti secondari per campionare la richiesta. Per ulteriori informazioni sulle intestazioni delle tracce, consulta Protocolli per la propagazione del contesto.

Per i componenti downstream di cui possiedi il codice, devi determinare se la logica di strumentazione rispetta il flag sampled. Ad esempio, quando utilizzi OpenTelemetry per la strumentazione, puoi usare il campione ParentBased per assicurarti che venga rispettato il flag campionato principale.

I servizi Google Cloud che registrano informazioni di tracciamento in Cloud Trace in genere accettano il flag di campionamento padre come suggerimento; tuttavia, la maggior parte dei servizi include anche il campionamento con limitazione di frequenza. Ogni servizio Google Cloud determina se supporta il tracciamento, come viene utilizzato il flag di campionamento padre e la limitazione di frequenza sul campionamento.

Abilita l'Cloud Trace API

Per utilizzare Cloud Trace, nel tuo progetto Google Cloud deve essere abilitata l'Cloud Trace API. Questa impostazione consente al progetto Google Cloud di ricevere dati di traccia da origini autenticate. L'Cloud Trace API è abilitata per impostazione predefinita nei progetti Google Cloud e non è richiesta alcuna azione da parte tua. Tuttavia, potrebbe essere necessario abilitare l'Cloud Trace API se hai modificato gli ambiti di accesso del tuo progetto Google Cloud.

Per abilitare l'Cloud Trace API, segui questi passaggi:

  1. Nel pannello di navigazione della console Google Cloud, seleziona API e servizi, fai clic su Abilita API e servizi e poi abilita l'Cloud Trace API:

    Vai alle impostazioni dell'API Cloud Trace

  2. Se viene visualizzato API abilitata, significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Passaggi successivi

Per informazioni dettagliate sulla configurazione, esempi e link a GitHub e altri repository open source, vai alla pagina di configurazione per il tuo linguaggio: