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 da Google Cloud servizi e applicazioni strumentate, Trace ti aiuta a capire come vengono elaborate le richieste in un'architettura di microservizi e a identificare i log pertinenti.

Trace ti aiuta a rispondere a domande come le seguenti:

  • Quanto tempo impiega la tua applicazione per gestire una determinata richiesta?
  • Perché una richiesta impiega così tanto tempo per essere completata?
  • Perché alcune richieste richiedono più tempo di altre?
  • Qual è la latenza complessiva delle richieste alla tua applicazione?
  • La latenza dell'applicazione è aumentata o diminuita nel tempo?
  • Come puoi ridurre la latenza dell'applicazione?
  • Quali sono le dipendenze della tua applicazione?

Per informazioni su come utilizzare insieme tracce e log per l'analisi della causa principale, consulta il post del blog Risoluzione dei problemi delle applicazioni distribuite: utilizzo congiunto di tracce e log per l'analisi della causa principale.

Per informazioni sulla profilazione dell'applicazione, consulta Cloud Profiler.

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 Google Cloud progetto. Puoi quindi utilizzare la Google Cloud console per visualizzare e analizzare i dati raccolti dal client di tracciamento. Per informazioni sul modello dei dati, consulta Tracce e intervalli.

Client di tracciamento

Un client di tracciamento raccoglie i dati di latenza e intervallo dalla tua applicazione e li esporta nel tuo Google Cloud progetto. 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 intervalli, puoi utilizzare le pagine Esplora tracce e Observability Analytics nella Google Cloud console:

  • Esplora tracce: mostra informazioni aggregate sui dati di traccia e ti consente di esaminare in dettaglio le singole tracce. I dati di latenza aggregati vengono visualizzati in 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 di 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 di 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 Programma di 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 l'applicazione per raccogliere informazioni specifiche che ti aiutino a comprenderne il rendimento e a risolvere i problemi di errore. 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 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 strumentare l'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 Strumentazione e osservabilità e Scegliere un approccio di strumentazione.

Gli esempi di strumentazione che forniamo utilizzano OpenTelemetry:

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

Cloud Trace e applicazioni agentiche

Per comprendere il comportamento delle applicazioni agentiche, configurale in modo che raccolgano prompt e risposte o generino intervalli quando chiamano i server MCP di Google Cloud remoti. I prompt e le risposte ti aiutano a comprendere il ragionamento utilizzato dall'applicazione agentica. Gli intervalli che registrano le chiamate agli strumenti ti aiutano a confermare la chiamata dello 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 esempi si basano su OpenTelemetry. Per saperne di più, consulta Come strumentare le applicazioni di AI generativa.

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

API che importano i dati di traccia

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

  • L'API fornisce la compatibilità con l'ecosistema OpenTelemetry open source e i suoi limiti sono spesso più generosi di quelli dell' API Cloud Trace, che è un' Google Cloud API 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 dei dati di traccia basata su raccoglitore, la strumentazione non si basa su un Google Cloud-esportatore specifico.

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

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

  • Google Cloud i servizi 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 scarta i dati di traccia inviati all'endpoint dell'API Telemetry specifico per le tracce. Non disattivare l'API Telemetry, perché questa API può ricevere dati di log, metriche e tracce.

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

Supporto dei Controlli di servizio VPC

Trace è un servizio supportato dai Controlli di servizio VPC. Il nome del servizio Trace è cloudtrace.googleapis.com. Eventuali limitazioni dei Controlli di servizio VPC create per il servizio Trace si applicano solo a quel servizio. Queste limitazioni non si applicano ad altri servizi, inclusi servizi come il servizio telemetry.googleapis.com, che possono anche importare dati di traccia.

Per ulteriori informazioni, consulta le seguenti risorse:

Cloud Trace e residenza dei dati

Se utilizzi Assured Workloads perché hai requisiti di localizzazione dei dati o livello di impatto 4 (IL4), non utilizzare l'Cloud Trace API per inviare gli intervalli di traccia.

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

Conservazione delle Trace

Categoria Periodo di conservazione
Intervalli archiviati nel _Trace bucket 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 dell'API 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 di concedere al account di servizio dell'applicazione l'autorizzazione a utilizzare questa 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