Panoramica di Cloud Trace

Cloud Trace è un sistema di tracciamento distribuito per Google Cloud che monitora la latenza delle richieste e ti aiuta a risolvere i colli di bottiglia delle prestazioni tra servizi e applicazioni di AI generativa. Raccogliendo i dati di latenza dai serviziGoogle Cloud e dalle applicazioni strumentate, Trace ti aiuta a capire come vengono elaborate le richieste in un'architettura di microservizi e a identificare i log pertinenti.

Con Trace, puoi misurare la latenza delle richieste end-to-end, confrontare le tendenze delle prestazioni nel tempo e individuare le dipendenze downstream che causano ritardi. Per una procedura dettagliata per correlare tracce e log, consulta Utilizzare tracce e log insieme per l'analisi della causa principale.

Supporto dell'ambiente

Trace viene eseguito su Linux nei seguenti ambienti:

Componenti

Trace è costituito da un client di tracciamento, che raccoglie le tracce e le invia al tuo progetto Google Cloud . Puoi quindi utilizzare la consoleGoogle Cloud per visualizzare e analizzare i dati raccolti dal client di tracciamento. Per informazioni sul modello dei dati, consulta Tracce e intervalli.

Tracciamento del client

Un client di tracciamento raccoglie i dati di latenza e span dalla tua applicazione e li esporta nel tuo progetto Google Cloud . A seconda dell'ambiente e dei requisiti, puoi raccogliere i dati di traccia automaticamente o manualmente strumentando il codice dell'applicazione.

Interfaccia di tracciamento

Per visualizzare e analizzare i dati degli span, puoi utilizzare le pagine Esplora tracce e Observability Analytics nella consoleGoogle Cloud :

  • Esplora tracce: mostra informazioni aggregate sui dati di traccia e ti consente di esaminare in dettaglio le singole tracce. I dati aggregati sulla latenza vengono visualizzati su una mappa termica, che puoi esplorare con il puntatore. Per limitare i dati visualizzati, puoi aggiungere filtri. Puoi anche visualizzare ed esplorare singoli intervalli e tracce:

  • Observability Analytics: fornisce un'interfaccia di query SQL. Le query possono unire i dati di traccia e log e puoi visualizzare i risultati della query come tabella o grafico. Puoi utilizzare BigQuery per analizzare i dati di traccia se crei un set di dati BigQuery collegato. Per saperne di più, consulta Eseguire query e analizzare le tracce.

Configurazioni con tracciamento automatico

Le seguenti configurazioni acquisiscono automaticamente i dati di traccia:

  • ambiente standard App Engine

    • I runtime di prima generazione intercettano e inviano automaticamente gli intervalli di traccia a Cloud Trace. Per saperne di più, consulta Panoramica dei servizi in bundle legacy.

    • I runtime di seconda generazione acquisiscono automaticamente la latenza complessiva delle richieste e aggiungono l'intestazione HTTP X-Cloud-Trace-Context alle richieste. Per saperne di più, consulta Pianificazione del supporto del runtime.

  • Cloud Run Functions e Cloud Run

    Per le richieste HTTP in entrata e in uscita, i dati di latenza vengono inviati automaticamente a Trace.

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

Gli esempi di instrumentazione che forniamo utilizzano OpenTelemetry:

Sebbene tu possa utilizzare le librerie client Cloud Trace per instrumentare la tua applicazione, ti consigliamo di utilizzare OpenTelemetry. Le librerie OpenTelemetry sono preferibili alle librerie client Trace perché sono più semplici ed esportano i dati di traccia in formato OTLP, definito da OpenTelemetry. Per saperne di più, consulta Strumentazione per Trace e Librerie client per Cloud Trace.

Cloud Trace e applicazioni agentiche

Per comprendere il comportamento delle tue applicazioni con agenti, configurale in modo che raccolgano prompt e risposte o generino intervalli quando chiamano server Google Cloud MCP remoti. Prompt e risposte ti aiutano a comprendere il ragionamento utilizzato dalla tua applicazione con agenti. Gli span che registrano le chiamate allo strumento ti aiutano a confermare la chiamata allo strumento, gli stati delle chiamate e le latenze delle richieste.

Diversi esempi di strumentazione mostrano come configurare un'applicazione per raccogliere prompt e risposte. Questi campioni si basano su OpenTelemetry. Per saperne di più, vedi Come instrumentare le applicazioni di AI generativa.

I server MCP di Google Cloud possono generare intervalli di traccia. Per saperne di più, consulta Analizzare le chiamate MCP utilizzando Trace.

API che importano dati di traccia

Puoi inviare dati di traccia al tuo progetto utilizzando l'API Telemetry o l'Cloud Trace API. Consigliamo l'API Telemetry per i seguenti motivi:

  • L'API offre compatibilità con l'ecosistema open source OpenTelemetry e i suoi limiti sono spesso più generosi di quelli dell'Cloud Trace API, che è un'API Google Cloud proprietaria.

  • I dati di traccia vengono archiviati in un formato generalmente coerente con i file proto definiti da OTLP. Alcuni campi potrebbero essere convertiti da un tipo di dati specifico di OpenTelemetry a un tipo di dati JSON prima dell'archiviazione. Per informazioni sul formato di archiviazione, consulta Schema per i dati di traccia.

  • Per l'esportazione basata su collector dei dati di traccia, la strumentazione non si basa su un esportatore specifico per Google Cloud.

  • Alcune funzionalità, come il monitoraggio delle applicazioni, si basano su informazioni disponibili solo quando invii dati di tracciamento all'API Telemetry.

Per impedire al tuo progetto Google Cloud di archiviare i dati di traccia, disattiva l'Cloud Trace API. La disabilitazione dellCloud Trace API ha i seguenti effetti:

  • I serviziGoogle Cloud non inviano dati di traccia al tuo progetto.
  • Google Cloud risponde alle richieste inviate a un endpoint API Cloud Trace con un codice di errore.
  • Google Cloud Observability elimina i dati di traccia inviati all'endpoint API Telemetry specifico per le tracce. Non disattivare l'API Telemetry, in quanto può ricevere dati di log, metriche e tracce.

Se gestisci un'organizzazione e vuoi impedire l'utilizzo di Cloud Trace, crea un vincolo dei criteri dell'organizzazione.

Supporto dei Controlli di servizio VPC

I serviziGoogle Cloud e le tue applicazioni possono inviare dati di traccia al tuo progetto utilizzando l'Cloud Trace API o l'API Telemetry. I servizi di visualizzazione forniti da Cloud Trace utilizzano l'Cloud Trace API per recuperare i dati di traccia visualizzati:

  • Cloud Trace è un servizio supportato dai Controlli di servizio VPC. Il nome del servizio di Trace è cloudtrace.googleapis.com. Per dettagli e limitazioni, consulta Prodotti supportati: Cloud Trace.

  • L'API Telemetry è un servizio supportato dai Controlli di servizio VPC. Il nome del servizio è telemetry.googleapis.com. Per dettagli e limitazioni, consulta Prodotti supportati: API Telemetry.

Per impostare i valori predefiniti che specificano la Google Cloud regione in cui vengono archiviati i dati di traccia e se una chiave gestita dal cliente cripta i dati, utilizza l'API Observability. Puoi anche utilizzare questa API per configurare set di dati BigQuery collegati, che ti consentono di eseguire query sui dati di traccia utilizzando i servizi BigQuery e per configurare ambiti di traccia, che ti consentono di aggregare i dati di traccia archiviati in più progetti.

  • L'API Observability è un servizio supportato dai Controlli di servizio VPC. Il nome del servizio è observability.googleapis.com. Per dettagli e limitazioni, consulta Prodotti supportati: API Observability.

Per ulteriori informazioni, consulta le seguenti risorse:

Cloud Trace e residenza dei dati

Se utilizzi Assured Workloads perché hai requisiti di residenza dei dati o Impact Level 4 (IL4), non utilizzare l'Cloud Trace API per inviare gli span di traccia.

Per impedire al tuo progetto Google Cloud di archiviare i dati di traccia, disattiva l'Cloud Trace API. Non disattivare l'API Telemetry, in quanto può ricevere dati di log, metriche e tracce.

Conservazione delle Trace

Categoria Periodo di conservazione
Span archiviati nel bucket _Trace 30 giorni

Ruoli IAM

Cloud Trace utilizza Identity and Access Management (IAM) per controllare l'accesso alle risorse. Per un elenco dei ruoli dell'Cloud Trace API e Telemetry, consulta Controllare l'accesso con IAM.

Poiché l'API Telemetry è un'API consumer, l'invio di dati all'API Telemetry richiede di specificare un progetto di quota e concedere all'account di servizio dell'applicazione l'autorizzazione a utilizzare la quota. Per saperne di più, consulta API Telemetry: autenticazione.

Prezzi

Per informazioni sui prezzi di Cloud Trace, consulta la pagina Prezzi di Google Cloud Observability.

Passaggi successivi