Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Panoramica di Cloud Trace

Cloud Trace, un sistema di tracciamento distribuito per Google Cloud, ti aiuta a capire quanto tempo impiega la tua applicazione a gestire le richieste in entrata da utenti o altre applicazioni e quanto tempo impiega a completare operazioni come le chiamate RPC eseguite durante la gestione delle richieste. Trace può aiutarti anche quando sviluppi un servizio, un'applicazione agentica o risolvi un errore. Ad esempio, può aiutarti a capire come vengono elaborate le richieste in un'architettura di microservizi complessa e potrebbe aiutarti a identificare i log da esaminare.

Poiché Trace riceve i dati di latenza da Google Cloud servizi come App Engine e dalle applicazioni che instrumenti, può aiutarti a rispondere alle seguenti domande:

Quanto tempo impiega la mia applicazione a gestire una determinata richiesta?
Perché la mia applicazione impiega così tanto tempo a gestire una richiesta?
Perché alcune delle mie richieste richiedono più tempo di altre?
Qual è la latenza complessiva delle richieste alla mia applicazione?
La latenza della mia applicazione è aumentata o diminuita nel tempo?
Cosa posso fare per ridurre la latenza dell'applicazione?
Quali sono le dipendenze della mia applicazione?

Se ti interessa sapere come utilizzare Trace per gestire le tue applicazioni, leggi 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:

Trace fornisce librerie client per instrumentare l'applicazione in modo da acquisire informazioni di traccia. Per le istruzioni di configurazione per lingua, consulta Instrumentare per Trace.

Configurazioni con tracciamento automatico

Alcune configurazioni comportano l'acquisizione automatica dei dati di traccia:

Ambiente standard di App Engine

Le applicazioni Java 8, Python 2 e PHP 5 non devono utilizzare le librerie client di Trace. Questi runtime inviano automaticamente i dati di latenza a Trace per le richieste agli URI delle applicazioni. Le richieste includono i dati di latenza per le chiamate RPC di andata e ritorno ai servizi App Engine. Trace funziona con tutte le API di amministrazione di App Engine, ad eccezione di Cloud SQL.
Cloud Run Functions e Cloud Run

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

API che acquisiscono 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 il seguente motivo:

L'API fornisce la compatibilità con l'ecosistema OpenTelemetry open source e i suoi limiti sono spesso più generosi dei limiti di Cloud Trace API, che è un'API proprietaria Google Cloud
I dati di traccia vengono archiviati in un formato generalmente coerente con i file proto definiti dal protocollo di linea OpenTelemetry. Alcuni campi potrebbero essere convertiti da un tipo di dati specifico di OpenTelemetry a un tipo di dati JSON prima dell'archiviazione. Per saperne di più sul formato di archiviazione, consulta Schema per i dati di traccia.
Per l'esportazione dei dati di traccia basata su collector, 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.

Se vuoi impedire al tuo Google Cloud progetto di archiviare i dati di traccia, disattiva l'Cloud Trace API. La disattivazione dell'Cloud Trace API comporta quanto segue:

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.

Cloud Trace e applicazioni agentiche

Per comprendere il comportamento delle tue applicazioni agentiche, configurale in modo che raccolgano prompt e risposte o generino durate quando chiamano i server MCP Google Cloud remoti Google Cloud. I prompt e le risposte ti aiutano a comprendere il ragionamento utilizzato dalla tua applicazione agentica. Le durate 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 instrumentare le applicazioni di AI generativa.

Per scoprire quali server MCP Google Cloud remoti supportano la generazione di tracce e come configurare l'applicazione in modo che questi server creino durate, consulta Esaminare le chiamate MCP utilizzando Trace.

Come instrumentare l'applicazione

Instrumenta l'applicazione per raccogliere informazioni specifiche che ti aiutino a comprenderne il rendimento 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 agentiche, alcuni framework possono raccogliere i prompt e le risposte o passare il contesto che consente il tracciamento di alcune chiamate ai server MCP Google Cloud remoti.

Per instrumentare 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:

Per gli esempi che utilizzano un'esportazione basata su collector, consulta quanto segue:
- Go
- Java
- Node.js
- Python
Questi esempi inviano i dati di traccia all'API Telemetry.
Per informazioni su come utilizzare un'esportazione diretta dei dati di traccia e inviare tali dati all'API Telemetry, consulta Eseguire la migrazione dall'esportatore di Trace all'endpoint OTLP.
Per gli esempi che mostrano come configurare un'applicazione agentica per raccogliere prompt e risposte, consulta Come instrumentare le applicazioni di AI generativa.

Per scoprire quali server MCP Google Cloud remoti supportano la generazione di tracce e come scoprire come configurare l'applicazione in modo che questi server creino durate, consulta Esaminare le chiamate MCP utilizzando Trace.

Puoi anche utilizzare le librerie client di Cloud Trace per instrumentare l'applicazione. Tuttavia, 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 Librerie client per Cloud Trace.

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 dall'agente. Per informazioni sul modello dei dati, consulta Tracce e durate.

Client di tracciamento

OpenTelemetry Oltre a essere più semplice da utilizzare, OpenTelemetry implementa il batching, che potrebbe migliorare il rendimento.

Se non esiste una libreria OpenTelemetry, instrumenta il codice importando la libreria SDK Trace e utilizzando l'Cloud Trace API. L'API Cloud Trace invia i dati di traccia al tuo Google Cloud progetto.

Interfaccia di tracciamento

Puoi visualizzare e analizzare i dati di traccia in tempo reale nell'interfaccia di Trace.

Per visualizzare e analizzare i dati delle durate, 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 su una mappa termica, che puoi esplorare con il puntatore. Per limitare i dati visualizzati, puoi aggiungere filtri. Questa pagina ti consente anche di visualizzare ed esplorare le singole durate e tracce:
- Per informazioni su come visualizzare i dati di traccia archiviati in più progetti, consulta Creare e gestire l'ambito di traccia.
- Per informazioni sul filtraggio e la visualizzazione dei dati di traccia, consulta Trovare ed esplorare le tracce.
Observability Analytics: questa pagina ti consente di eseguire query che eseguono un'analisi aggregata delle durate utilizzando SQL. Le query SQL possono anche unire i dati di traccia e di log. Puoi visualizzare i risultati della query in formato tabellare o con grafici. Se crei un set di dati BigQuery collegato, puoi utilizzare BigQuery per analizzare le durate. Per saperne di più, consulta Eseguire query e analizzare le tracce.

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 quelli come il telemetry.googleapis.com servizio, che può anche acquisire dati di traccia.

Per ulteriori informazioni, consulta le seguenti risorse:

Cloud Trace e localizzazione 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 le durate di traccia.