Strumento per Cloud Trace

Questo documento fornisce una breve panoramica su come instrumentare l'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 analizzare 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, strumenta l'applicazione.

Strumenta la tua applicazione per raccogliere informazioni specifiche che ti aiutino a comprenderne le prestazioni e a risolvere i problemi. Diversi framework di strumentazione open source raccolgono dati di log, metriche e tracce e possono inviarli a qualsiasi fornitore, incluso Google Cloud. Per le tue applicazioni agentic, alcuni framework possono raccogliere i prompt e le risposte o trasmettere il contesto che consente di tracciare alcune chiamate ai server Google Cloud MCP.

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 fornitori e prodotti. Per informazioni su questi framework, vedi 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 progetto Google Cloud utilizzando l'API Telemetry (OTLP). Per saperne di più sui nostri consigli, consulta la sezione Scegliere un approccio di strumentazione.

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

  • Se scrivi applicazioni 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 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 strumentazione che forniamo utilizzano OpenTelemetry:

  • Per scoprire quali server MCP Google Cloud remoti supportano la generazione di tracce e come configurare l'applicazione per indicare a questi server di creare span, consulta Esaminare le chiamate MCP utilizzando Trace.

Quando creare intervalli

Le librerie client di Cloud Trace in genere mantengono un contesto di traccia globale che contiene informazioni sullo span corrente, inclusi l'ID traccia e se la traccia viene campionata. Queste librerie in genere creano span sui limiti RPC. Tuttavia, potrebbe essere necessario creare intervalli se l'algoritmo di creazione predefinito non è sufficiente per le tue esigenze.

È possibile accedere allo span attivo corrente tramite il contesto di traccia globale, che 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ù precisa. 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 devi fornire credenziali di autenticazione alla tua applicazione o specificare l'ID progetto nella tua applicazione quando esegui l'applicazione su Google Cloud. Google Cloud Per alcune lingue, devi specificare l'ID progetto Google Cloud anche se l'esecuzione avviene 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 per utilizzare Workload Identity Federation for GKE.

Se corri al di fuori di Google Cloud, devi fornire le credenziali di autenticazione alla tua applicazione. Devi anche specificare l'ID progettoGoogle Cloud nella tua applicazione.

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

Come forzare la tracciabilità di una richiesta

A meno che la tua applicazione non campioni sempre ogni intervallo, in generale non è possibile forzare la tracciabilità 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 di 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 di traccia, 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 l'instrumentazione, puoi utilizzare il campionatore ParentBased per assicurarti che il flag di campionamento principale venga rispettato.

I serviziGoogle Cloud che registrano le informazioni di tracciamento in Cloud Trace in genere accettano il flag di campionamento principale come suggerimento; tuttavia, la maggior parte dei servizi limita anche la frequenza di campionamento. Ogni servizio Google Cloud determina se supporta la tracciabilità, 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 allegando gli esemplari ai punti dati delle metriche. Se completi i passaggi di configurazione necessari, OpenTelemetry, che è la libreria di strumentazione consigliata, aggiunge automaticamente questi esemplari. Per ulteriori informazioni, consulta Correlare metriche e tracce utilizzando gli esemplari.

Configura il progetto e la piattaforma

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

    Per impostazione predefinita,i progetti Google Cloud hanno l'Cloud Trace API abilitata 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, vedi Sviluppare applicazioni in un ambiente Google Cloud vincolato.

    Abilita l'Cloud Trace API.

    Ruoli richiesti per abilitare le API

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

    Abilitare l'API

  2. Configura la tua piattaforma.

    Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

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

      Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di accesso includono l'ambito di accesso dell&#39Cloud Trace APIe:

      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 se specifichi il flag --scopes, assicurati che l'ambito includa trace.append. Il seguente comando mostra 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 la tua applicazione viene eseguita al di fuori di Google Cloud, devi fornire le credenziali di autenticazione sotto 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.

      Le librerie clientGoogle Cloud utilizzano le Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione. Puoi fornire queste credenziali in uno dei tre modi seguenti:

      • Esegui gcloud auth application-default login

      • Posiziona il account di servizio in un percorso predefinito per il tuo 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 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.