Strumento per Cloud Trace

Puoi instrumentare le tue applicazioni per Cloud Trace per acquisire dati di tracciamento distribuiti, esaminare la latenza per le 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 la lingua.

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 tuoi prompt e le tue risposte o trasmettere il contesto che consente di tracciare alcune chiamate ai server MCP di Google Cloud.

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 l'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 Cloud Trace per OpenTelemetry.

Esempi di strumentazione

Gli esempi di instrumentazione che forniamo utilizzano OpenTelemetry:

Crea intervalli personalizzati

Anche se OpenTelemetry e le librerie client ti consentono di creare intervalli personalizzati, potresti non doverli creare manualmente perché queste librerie creano automaticamente 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ù precisa.

Le librerie in genere mantengono un contesto della traccia globale che contiene informazioni sullo span 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 multithread propagano il contesto tra i thread per mantenere dati di traccia accurati.

Forza il campionamento delle tracce

Non puoi forzare il campionamento degli span 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: configuri 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 parent sia rispettato.

  • Google Cloud services: ogni servizio determina il proprio supporto per la tracciabilità. In generale, i servizi accettano il flag di campionamento principale come suggerimento mentre applicano 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 della metrica. Ad esempio, un esemplare 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 Correlare metriche e tracce utilizzando gli esemplari.

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 Generare e visualizzare gli esemplari di traccia.

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, i progetti Google Cloud hanno abilitate 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, vedi Sviluppa applicazioni in un ambiente Google Cloud vincolato.

Abilita le API Telemetry e 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 disponi già di 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

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 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 su Google Cloud e quando vengono eseguite altrove.

Esegui il giorno Google Cloud

Quando la tua 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 sono ospitate su Google Cloud.

Verifica che la tua Google Cloud piattaforma abbial'ambito di accesso all'API Cloud Trace abilitato. 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

Esegui localmente e altrove

Se la tua applicazione viene eseguita all'esterno 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 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 file della chiave del 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