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 con agenti o risolvi un errore. Ad esempio, può aiutarti a capire come vengono elaborate le richieste in un'architettura di microservizi complessa e può aiutarti a identificare i log da esaminare.

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

Quanto tempo impiega la mia applicazione a gestire una determinata richiesta?
Perché la mia applicazione richiede così tanto tempo per 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 vuoi scoprire 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 della tua 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 istruzioni di configurazione per lingua, vedi Strumento per la traccia.

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 Trace. Questi runtime inviano automaticamente i dati di latenza a Trace per le richieste agli URI delle applicazioni. Le richieste includono dati di latenza per le chiamate RPC round trip ai servizi App Engine. Trace funziona con tutte le API App Engine Admin, 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 importano i dati di traccia

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

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 proprietaria Google Cloud .
I dati di traccia vengono archiviati in un formato generalmente coerente con i file proto definiti dal protocollo OpenTelemetry OTLP. 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 basata sul collettore 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 traccia all'API Telemetry.

Se vuoi impedire al tuo progetto Google Cloud di archiviare i dati di traccia, disattiva l&#39Cloud Trace APIe. La disattivazione dellCloud Trace API comporta quanto segue:

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 della 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 span quando chiamano server Google Cloud MCP remoti. Prompt e risposte ti aiutano a comprendere il ragionamento utilizzato dalla tua applicazione con agenti. Gli intervalli che registrano le chiamate agli strumenti 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.

Per scoprire quali server MCP Google Cloud remoti supportano la generazione di tracce e per scoprire come configurare l'applicazione in modo da indicare a questi server di creare span, consulta Esaminare le chiamate MCP utilizzando Trace.

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

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 strumentazione che forniamo utilizzano OpenTelemetry:

Per gli esempi che utilizzano un'esportazione basata su un collettore, vedi quanto segue:
- Go
- Java
- Node.js
- Python
Questi esempi inviano dati di traccia all'API Telemetry.
Per informazioni su come utilizzare un'esportazione diretta dei dati di traccia e inviarli all'API Telemetry, consulta Eseguire la migrazione dall'esportatore di Trace all'endpoint OTLP.
Per 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 configurare l'applicazione per indicare a questi server di creare span, consulta Esaminare le chiamate MCP utilizzando Trace.

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

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

Client di tracciamento

Se è disponibile una libreria OpenTelemetry per il tuo linguaggio di programmazione, puoi semplificare il processo di creazione e invio dei dati di traccia utilizzando OpenTelemetry. Oltre a essere più semplice da usare, OpenTelemetry implementa il batching, che potrebbe migliorare le prestazioni.

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 progetto Google Cloud .

Interfaccia di tracciamento

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

Per visualizzare e analizzare i dati degli span, puoi utilizzare le pagine Esplora trace e Analisi dell'osservabilità nella consoleGoogle Cloud :

Esplora tracce: mostra informazioni aggregate sui dati di traccia e consente di esaminare in dettaglio le singole tracce. I dati aggregati sulla latenza vengono visualizzati in 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 singoli intervalli e tracce:
- Per informazioni su come visualizzare i dati di traccia archiviati in più progetti, vedi Creare e gestire l'ambito della traccia.
- Per informazioni sul filtraggio e la visualizzazione dei dati di traccia, consulta Trovare ed esplorare le tracce.
Observability Analytics: questa pagina consente di eseguire query che eseguono un'analisi aggregata dei tuoi span utilizzando SQL. Le query SQL possono anche unire i dati di traccia e log. Puoi visualizzare i risultati della query in formato tabellare o con grafici. Se crei un set di dati collegato, puoi utilizzare BigQuery per analizzare gli span. 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 di Trace è cloudtrace.googleapis.com. Eventuali limitazioni dei Controlli di servizio VPC che crei per il servizio Trace si applicano solo a quel servizio. Queste limitazioni non si applicano ad altri servizi, inclusi quelli come il servizio telemetry.googleapis.com, che possono anche importare dati di traccia.

Per ulteriori informazioni, consulta le seguenti risorse:

Cloud Trace e localizzazione dei dati

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