Strumento per Cloud Trace

Puoi instrumentare le tue applicazioni per Cloud Trace per acquisire dati di tracciamento distribuito, esaminare la latenza per le singole richieste e visualizzare la latenza aggregata tra i servizi nella console Trace.

Questo documento fornisce una panoramica degli approcci di instrumentazione e delle opzioni di configurazione. Per istruzioni passo passo per linguaggi di programmazione specifici, consulta le pagine di configurazione specifiche per il linguaggio.

Quando instrumentare l'applicazione

Se 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, tra cui Google Cloud. Per le tue applicazioni agentiche, alcuni framework possono raccogliere i prompt e le risposte o passare il contesto che consente di tracciare 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 del fornitore e del 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 l'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 scrivi applicazioni in esecuzione 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.

  • 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.

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

Esempi di instrumentazione

Gli esempi di instrumentazione che forniamo utilizzano OpenTelemetry:

Creare intervalli personalizzati

Sebbene OpenTelemetry e le librerie client ti consentano di creare intervalli personalizzati, potresti non doverli creare manualmente perché queste librerie creano automaticamente gli intervalli ai limiti RPC.

Puoi anche aggiungere informazioni pertinenti alla tua applicazione aggiungendo 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.

In genere, le librerie mantengono un contesto di traccia globale che contiene informazioni sull'intervallo corrente, inclusi l'ID traccia e lo stato di campionamento. Le applicazioni possono accedere all'intervallo corrente tramite il contesto di traccia globale. Poiché il contesto è globale, assicurati che le applicazioni multithread propaghino il contesto tra i thread per mantenere dati di traccia accurati.

Forzare il campionamento delle tracce

Non puoi forzare il campionamento degli intervalli perché ogni componente nel percorso della richiesta prende una decisione di campionamento indipendente . Tuttavia, puoi influenzare i componenti downstream impostando il sampled flag nell'intestazione della traccia su true. Questa impostazione è un suggerimento per i componenti secondari di campionare la richiesta. Per saperne di più sulle intestazioni delle tracce, consulta Protocolli per la propagazione del contesto.

  • Le tue applicazioni: configuri il modo in cui la logica di instrumentazione rispetta il flag sampled. Ad esempio, quando utilizzi OpenTelemetry, puoi utilizzare il campionatore ParentBased per assicurarti che il flag di campionamento del parent venga rispettato.

  • Google Cloud Servizi: ogni servizio determina il proprio supporto per il tracciamento. In generale, i servizi accettano il flag di campionamento parent come suggerimento, applicando al contempo i propri limiti di frequenza di campionamento.

Correlare metriche e tracce con gli esemplari

Puoi correlare i dati delle metriche con le tracce utilizzando gli esemplari. Un esemplare è una richiesta o uno span di campione rappresentativo associato a una misurazione delle metriche. Ad esempio, un esemplare può contenere un link a una traccia, che ti consente di correlare i dati di metriche e tracce. Per un esempio basato su OpenTelemetry, consulta Correlare metriche e tracce utilizzando gli esemplari.

Potresti visualizzare esemplari generati dal sistema nei grafici delle dashboard che mostrano i risultati delle query SQL per i dati di traccia. Questi esemplari collegano direttamente i risultati di query specifici alle tracce. Per saperne di più, consulta Generare e visualizzare gli esemplari di traccia.

Configurare il progetto e la piattaforma

Questa sezione descrive le API e i ruoli Identity and Access Management (IAM) richiesti e spiega come configurare le credenziali di autenticazione per la tua piattaforma.

Abilitare le API

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

Abilita le API Telemetry e Cloud Trace.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Concedere ruoli IAM

I ruoli IAM richiesti dipendono dal fatto che tu stia visualizzando i dati di traccia nella Google Cloud console o scrivendo i dati di traccia nel tuo progetto:

  • Per ottenere le autorizzazioni necessarie per visualizzare i dati di traccia utilizzando la Google Cloud console, chiedi all'amministratore di concederti il ruolo IAM Utente Cloud Trace (roles/cloudtrace.user) nel tuo progetto.

  • Per ottenere le autorizzazioni necessarie per scrivere i dati di traccia utilizzando l'Cloud Trace API, chiedi all'amministratore di concederti il ruolo IAM Agente Cloud Trace (roles/cloudtrace.agent) nel tuo progetto.

  • Per ottenere le autorizzazioni necessarie per scrivere i dati di traccia utilizzando l'API Telemetry, chiedi all'amministratore di concederti il ruolo IAM Writer di telemetria cloud (roles/telemetry.writer) nel tuo progetto.

Autentica

Questa sezione descrive come eseguire l'autenticazione quando le applicazioni vengono eseguite su Google Cloud e quando vengono eseguite altrove.

Esegui su Google Cloud

Quando l'applicazione viene eseguita su Google Cloud, in genere non è necessario fornire credenziali di autenticazione. Tuttavia, alcune librerie client di linguaggio richiedono l'ID progetto anche se ospitate su Google Cloud.

Verifica che la tua Google Cloud piattaforma abbia abilitato l' ambito di accesso all'API Cloud Trace. Per le seguenti configurazioni, le impostazioni dell'ambito di accesso predefinite 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

Esegui in locale e altrove

Se l'applicazione viene eseguita all'esterno Google Cloud, devi fornire le credenziali di autenticazione alla libreria client. Al service account 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 file delle chiavi del 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 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