Strumento per Cloud Trace

Questo documento fornisce una breve panoramica su come eseguire l'instrumentazione dell'applicazione per Cloud Trace. Per istruzioni dettagliate sulla configurazione di Cloud Trace, consulta le pagine di configurazione specifiche per la lingua.

Cloud Trace fornisce dati di monitoraggio distribuito per le tue applicazioni. Dopo aver eseguito l'instrumentazione dell'applicazione, puoi esaminare i dati sulla latenza per una singola richiesta e visualizzare la latenza aggregata per un'intera applicazione nella console Cloud Trace.

Quando eseguire l'instrumentazione dell'applicazione

Quando i dati traccia non vengono acquisiti automaticamente, devi instrumentare la tua applicazione per raccoglierli.

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

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

Come eseguire l'instrumentazione delle applicazioni

Per instrumentare le applicazioni in modo da raccogliere i dati di traccia, puoi eseguire una delle seguenti operazioni:

Quando creare gli intervalli

In genere, le librerie client di Cloud Trace gestiscono un contesto traccia globale che contiene informazioni sull'intervallo corrente, incluso l'ID traccia e se la traccia viene campionata. Queste librerie in genere creano span sui confini RPC. Tuttavia, potresti dover creare degli intervalli se l'algoritmo di creazione predefinito non è sufficiente per le tue esigenze.

È possibile accedere allo span attivo corrente tramite il contesto traccia globale, che a volte è incluso in un oggetto Tracer. Puoi aggiungere informazioni pertinenti alla tua applicazione utilizzando annotazioni e tag personalizzati per gli elementi span esistenti oppure puoi creare nuovi elementi span secondari con le relative annotazioni e i relativi tag per monitorare il comportamento dell'applicazione con una granularità più fine. Poiché il contesto è globale, le applicazioni multithread che lo aggiornano devono utilizzare l'isolamento appropriato.

Quando fornire le credenziali di autenticazione

In genere, non è necessario fornire le credenziali di autenticazione alla tua applicazione o specificare l'ID progetto Google Cloud al suo interno quando esegui l'applicazione su Google Cloud. Per alcune lingue, è necessario specificare l'ID progetto Google Cloud anche se la pubblicazione avviene su Google Cloud. Inoltre, se utilizzi la modalità Autopilot per Google Kubernetes Engine o se attivi la federazione delle identità per i carichi di lavoro per GKE, devi configurare l'applicazione in modo che utilizzi la federazione delle identità per i carichi di lavoro per GKE.

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

Per maggiori dettagli, vai alle pagine di configurazione specifiche per la lingua.

Come forzare il monitoraggio di una richiesta

A meno che la tua applicazione non esamini sempre ogni span, in genere non è possibile forzare il monitoraggio end-to-end di una richiesta perché 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 impostato su true. Questa impostazione è un suggerimento per i componenti secondari per eseguire il campionamento della richiesta. Per ulteriori informazioni sulle intestazioni di traccia, consulta Protocolli per la propagazione del contesto.

Per i componenti a valle di cui sei proprietario del codice, devi determinare se la logica di misurazione rispetta il flag sampled. Ad esempio, quando utilizzi OpenTelemetry per la misurazione, puoi utilizzare il ParentBased sampler per assicurarti che il flag campionato principale venga rispettato.

I servizi Google Cloud che registrano le informazioni di monitoraggio in Cloud Trace tipicamente accettano il flag di campionamento principale come suggerimento. Tuttavia, la maggior parte dei servizi applica anche un limite di frequenza al campionamento. Ogni servizio Google Cloud determina se supporta il monitoraggio, come viene utilizzato il flag di campionamento principale e il limite di frequenza del campionamento.

Come correlare i dati delle metriche e delle tracce

Puoi correlare i dati delle metriche con valori di distribuzione con le tracce collegando gli esempi ai punti dati delle metriche. Se completi i passaggi di configurazione necessari, OpenTelemetry, la libreria di strumenti consigliata, aggiunge automaticamente questi esempi. Per ulteriori informazioni, consulta Correlare metriche e tracce utilizzando gli esempi.

Configura il progetto e la piattaforma

  1. Assicurati che l'API Cloud Trace sia abilitata.

    Per impostazione predefinita, l'Cloud Trace API è attivata nei progetti Google Cloud e non devi fare nulla. Tuttavia, i vincoli di sicurezza definiti dalla tua organizzazione potrebbero aver disattivato l'API. Per informazioni sulla risoluzione dei problemi, consulta Sviluppare applicazioni in un ambiente Google Cloud vincolato.

    Enable the Cloud Trace API.

    Enable the API

  2. Configura la tua piattaforma.

    Puoi utilizzare Cloud Trace su Google Cloud e su altre piattaforme.

    • Google Cloud: quando l'applicazione è in esecuzione su Google Cloud, non è necessario fornire le credenziali di autenticazione sotto forma di account di servizio alla libreria client. Tuttavia, devi assicurarti che sulla tua piattaforma Google Cloud sia attivato l'ambito di accesso dell'API Cloud Trace.

      Per le seguenti configurazioni, le impostazioni di ambito di accesso predefinite includono l'ambito di accesso dell'Cloud Trace API:

      Se utilizzi ambiti di accesso personalizzati, devi assicurarti che sia abilitato l'ambito di accesso dell'API Cloud Trace. Ad esempio, se utilizzi Google Cloud CLI per creare un cluster GKE e se specifichi il flag --scopes, assicurati che l'ambito includa trace.append. Il comando seguente illustra l'impostazione del flag --scopes:

      gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

    • Esecuzione locale e altrove: se l'applicazione viene eseguita al di fuori di Google Cloud, devi fornire le credenziali di autenticazione sotto forma di un account di servizio alla libreria client. All'account di servizio deve essere concesso il ruolo Agente Cloud Trace (roles/cloudtrace.agent). Per informazioni sui ruoli, consulta Controllare l'accesso con IAM.

      Le librerie client di Google Cloud utilizzano le credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione. Puoi fornire queste credenziali in uno di tre modi:

      • Esegui gcloud auth application-default login

      • Posiziona l'account di servizio in un percorso predefinito per il sistema operativo. Di seguito sono elencati i percorsi predefiniti per Windows e Linux:

        • Windows: %APPDATA%/gcloud/application_default_credentials.json

        • Linux: $HOME/.config/gcloud/application_default_credentials.json

      • Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del tuo account di servizio:

        Linux/macOS

          export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        Windows

          set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        PowerShell:

          $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Passaggi successivi

Per informazioni dettagliate sulla configurazione, esempi e link a GitHub e ad altri repository open source, vai alla pagina di configurazione della tua lingua.