Strumento per Cloud Trace

Puoi instrumentare le tue applicazioni per Cloud Trace in modo da acquisire dati di tracciamento distribuito, esaminare la latenza per singole richieste e visualizzare la latenza aggregata nei tuoi servizi nella console Trace.

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

Quando instrumentare l'applicazione

Strumenta la tua applicazione per raccogliere informazioni specifiche che ti aiutino a comprenderne le prestazioni e a risolvere gli errori. Esistono diversi framework di strumentazione open source che raccolgono dati di log, metriche e tracce e possono inviarli a qualsiasi fornitore, incluso Google Cloud. Per le tue applicazioni basate su agenti, alcuni framework possono raccogliere i tuoi prompt e le tue risposte o passare un contesto che consente di tracciare alcune chiamate remote ai server MCP di Google Cloud.

Per instrumentare la tua applicazione, ti consigliamo di utilizzare un framework di strumentazione 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 Osservabilità per gli sviluppatori di applicazioni e Scegli un approccio di strumentazione.

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 raccoglitore e configura il raccoglitore in modo che invii i dati di traccia al tuo progetto Google Cloud utilizzando l'API Telemetry (OTLP). Per saperne di più sui nostri suggerimenti, consulta Scegli 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 log, ma non utilizzando OTLP. Per saperne di più, consulta Utilizza 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 che raccolgono 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.

Campioni di strumentazione

Gli esempi di strumentazione che forniamo utilizzano OpenTelemetry:

Crea intervalli personalizzati

Sebbene OpenTelemetry e le librerie client consentano di creare intervalli personalizzati, potrebbe non essere necessario crearli manualmente perché queste librerie creano automaticamente intervalli ai confini RPC.

Puoi anche aggiungere informazioni pertinenti alla tua applicazione aggiungendo annotazioni e tag personalizzati agli intervalli esistenti oppure puoi creare nuovi intervalli secondari con le proprie annotazioni e tag per tracciare il comportamento dell'applicazione con una granularità più precisa.

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

Forza 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 flag sampled nell'intestazione della traccia 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.

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

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

Correlare metriche e tracce con gli esempi

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

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

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

Abilita API

Per impostazione predefinita, nei progetti Google Cloud sono abilitate l'Cloud Trace API e l'API Telemetry e non è necessario 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, vedi Sviluppa applicazioni in un ambiente Google Cloud vincolato.

Abilita le API Telemetry e API Cloud Trace, se non sono già abilitate.

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 Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Concedi ruoli IAM

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

  • Per ottenere le autorizzazioni necessarie per visualizzare i dati di traccia utilizzando la console Google Cloud , chiedi all'amministratore di concederti il ruolo IAM Cloud Trace User (roles/cloudtrace.user) sul 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 Cloud Trace Agent (roles/cloudtrace.agent) nel progetto.

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

Autentica

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

Esegui su Google Cloud

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

Verifica che nella tua piattaforma Google Cloud sia 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'Cloud Trace API:

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso dell'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 al di fuori di 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 Controlla 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

  • Inserisci il file della chiave 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