Strumento per Cloud Trace

Questo documento fornisce una breve panoramica su come instrumentare la tua 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 tracciamento distribuito per le tue applicazioni. Dopo aver instrumentato 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 instrumentare l'applicazione

Quando i dati di traccia per la convalida delle prestazioni o la risoluzione dei problemi non vengono acquisiti automaticamente, instrumenta l'applicazione.

Instrumenta l'applicazione per raccogliere informazioni specifiche che ti aiutino a comprenderne le prestazioni e a risolvere i problemi. Diversi framework di instrumentazione open source raccolgono dati di log, metriche e tracce e possono inviarli a qualsiasi fornitore, incluso Google Cloud. Per le tue applicazioni agentiche, alcuni framework possono raccogliere i prompt e le risposte o passare il contesto che consente il tracciamento di alcune chiamate ai server MCP di Google Cloud remoti.

Per instrumentare l'applicazione, ti consigliamo di utilizzare un framework di instrumentazione open source e indipendente dal fornitore, come OpenTelemetry, anziché API o librerie client specifiche per il fornitore e il prodotto. Per informazioni su questi framework, consulta Instrumentazione e osservabilità e Scegliere un approccio di instrumentazione.

Come instrumentare le applicazioni

Esistono diversi approcci che puoi utilizzare per instrumentare la tua applicazione:

  • Consigliato: utilizza OpenTelemetry, configura la tua applicazione con un esportatore OTLP che invia i dati di traccia a un agente di raccolta e configura l'agente di raccolta per inviare i dati di traccia al tuo Google Cloud progetto utilizzando l'API Telemetry (OTLP). Per saperne di più sui nostri consigli, consulta Scegliere un approccio di instrumentazione.

  • Utilizza OpenTelemetry e configura l'applicazione con un esportatore OTLP che invia i dati di traccia al tuo Google Cloud progetto utilizzando l' API Telemetry.

  • Se stai scrivendo applicazioni che vengono eseguite su Compute Engine, puoi utilizzare Ops Agent e il ricevitore OpenTelemetry Protocol (OTLP) per raccogliere tracce e metriche dalla tua applicazione. Ops Agent può anche raccogliere i log, ma non utilizzando OTLP. Per saperne di più, consulta Utilizzare Ops Agent e OTLP e Panoramica di Ops Agent.

  • Richiama direttamente l'API Telemetry o l'API Cloud Trace.

  • Utilizza le librerie client di Cloud Trace o l'esportatore Cloud Trace per OpenTelemetry.

  • Per le applicazioni Spring Boot, configurale in modo che inoltrino i dati di traccia raccolti a Cloud Trace. Per informazioni su questa procedura, consulta Spring Cloud per Google Cloud: Cloud Trace.

Gli esempi di instrumentazione che forniamo utilizzano OpenTelemetry:

Quando creare intervalli

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

È possibile accedere all'intervallo attivo corrente tramite il contesto di traccia globale, a volte racchiuso 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 una granularità più fine. Poiché il contesto è globale, le applicazioni multithread che aggiornano il contesto devono utilizzare un isolamento appropriato.

Quando fornire le credenziali di autenticazione

In genere non è necessario fornire le credenziali di autenticazione all'applicazione o specificare l'ID progetto nell'applicazione quando viene eseguita su. Google Cloud Google CloudPer alcune lingue, devi specificare l'ID Google Cloud progetto anche se esegui l'applicazione su Google Cloud. Inoltre, se utilizzi la modalità Autopilot per Google Kubernetes Engine o se abiliti Workload Identity Federation for GKE, devi configurare l'applicazione in modo che utilizzi Workload Identity Federation for GKE.

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

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

Come forzare il tracciamento di una richiesta

A meno che l'applicazione non campioni sempre ogni intervallo, in generale non è possibile forzare il tracciamento 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 sampled flag, impostato su true. Questa impostazione è un suggerimento per i componenti secondari per campionare la richiesta. Per saperne di più sulle intestazioni di traccia, consulta Protocolli per la propagazione del contesto.

Per i componenti downstream di cui possiedi il codice, devi determinare se la logica di instrumentazione rispetta il flag sampled. Ad esempio, quando utilizzi OpenTelemetry per l'instrumentazione, puoi utilizzare il ParentBased campionatore per assicurarti che il flag sampled del parent venga rispettato.

Google Cloud I servizi che registrano le informazioni di tracciamento in Cloud Trace in genere accettano il flag di campionamento del parent come suggerimento; tuttavia, la maggior parte dei servizi limita anche la frequenza di campionamento. Ogni Google Cloud servizio determina se supporta il tracciamento, come viene utilizzato il flag di campionamento del parent e il limite di frequenza per il campionamento.

Come correlare i dati di metriche e tracce

Puoi correlare i dati delle metriche con valori di distribuzione con le tracce collegando gli esemplari ai punti dati delle metriche. Se completi i passaggi di configurazione necessari, OpenTelemetry, la libreria di instrumentazione consigliata, aggiunge automaticamente questi esemplari. Per saperne di più, consulta Correlare metriche e tracce utilizzando gli esemplari.

Configurare il progetto e la piattaforma

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

    Per impostazione predefinita, Google Cloud i progetti hanno l'Cloud Trace API abilitata e non devi intraprendere alcuna azione. Tuttavia, i vincoli di sicurezza definiti dalla tua organizzazione potrebbero aver disabilitato l'API. Per informazioni sulla risoluzione dei problemi, consulta Sviluppare applicazioni in un ambiente vincolato. Google Cloud

    Abilita l'Cloud Trace API.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

  2. Configura la piattaforma.

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

    • Google Cloud: quando l'applicazione viene eseguita su Google Cloud, non è necessario fornire le credenziali di autenticazione sotto forma di account di servizio alla libreria client. Tuttavia, deve assicurarsi che la Google Cloud piattaforma abbia abilitato l' ambito di accesso all'API Cloud Trace.

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

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

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

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

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

      • Esegui gcloud auth application-default login

      • Inserisci il account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono riportati 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 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 per la tua lingua.