Questa pagina descrive come attivare le tracce lato client con OpenTelemetry quando utilizzi le librerie client di Cloud Storage per interagire con Cloud Storage. Puoi raccogliere e visualizzare i dati traccia utilizzando le seguenti librerie client di Cloud Storage supportate:
Panoramica
L'attivazione delle tracce nelle librerie client di Cloud Storage ti consente di monitorare le prestazioni, individuare i problemi di latenza ed eseguire rapidamente il debug delle richieste di Cloud Storage. Le tracce ti consentono di visualizzare la sequenza di una richiesta completata, fornendo una visualizzazione dettagliata di come la richiesta è stata ricevuta, gestita e a cui è stata data risposta da Cloud Storage. Una singola traccia è composta da più span, ovvero record dettagliati con timestamp di ogni funzione o operazione eseguita dall'applicazione durante la richiesta di Cloud Storage.
Vantaggi
La raccolta e la propagazione dei dati traccia offre i seguenti vantaggi alla tua applicazione:
Maggiore visibilità sulle prestazioni: poiché i dati di traccia vengono generati in quasi tempo reale quando Cloud Storage completa ogni richiesta che effettui, puoi identificare rapidamente i colli di bottiglia delle prestazioni e rilevare i problemi di latenza.
Gestione degli errori: puoi individuare dove si verificano i problemi, accelerare l'analisi della causa principale e ridurre il tempo di riposo utilizzando le informazioni su ogni richiesta di Cloud Storage fornite in una traccia.
Come funzionano le tracce lato client
Le sezioni seguenti descrivono in dettaglio il funzionamento della raccolta delle tracce.
Come funziona la raccolta delle tracce con OpenTelemetry
Le librerie client di Cloud Storage supportano la raccolta dei dati di traccia utilizzando l'SDK OpenTelemetry per configurare i seguenti componenti necessari per raccogliere e propagare i dati di traccia:
Provider di traccia: utilizzato dalle librerie client di Cloud Storage, il provider di traccia è responsabile della creazione e della gestione del sistema di monitoraggio, inclusa la generazione e la gestione di tracce e intervalli nell'applicazione.
Esportatore di traccia: utilizzato dall'SDK OpenTelemetry, l'esportatore di traccia è responsabile dell'invio dei dati di traccia a una piattaforma di osservabilità di backend come Cloud Trace, dove puoi analizzare e visualizzare i dati di traccia. Per scoprire di più sull'esportatore di tracce, consulta Come funzionano gli esportatori di tracce.
Come funzionano gli esportatori di tracce
La configurazione delle tracce utilizzando l'SDK OpenTelemetry include la selezione di un backend di osservabilità per esportare i dati in un luogo in cui vengono analizzati, archiviati e visualizzati. Sebbene tu possa esportare i dati di tracciamento in qualsiasi backend di osservabilità di tua scelta, ti consigliamo di utilizzare Cloud Trace, a cui puoi accedere utilizzando la console Google Cloud e che fornisce l'integrazione con altri Google Cloud servizi.
Una volta configurati e attivati il provider di traccia e l'esportatore di traccia, puoi visualizzare i dati di traccia in tempo quasi reale man mano che le tracce e gli intervalli vengono generati per ogni richiesta di Cloud Storage.
Utilizzando Trace Explorer in Google Cloud Console, puoi visualizzare ogni traccia contenente quanto segue:
Una visualizzazione di alto livello di una richiesta Cloud Storage end-to-end.
Più intervalli, ognuno dei quali acquisisce una singola operazione con timestamp all'interno della richiesta Cloud Storage eseguita.
Per scoprire di più su tracce e span, consulta la documentazione di OpenTelemetry su tracce e span.
Prezzi
I dati traccianti sono a pagamento. Gli addebiti si basano sul numero di intervalli di traccia importati e scansionati da Cloud Trace. Per scoprire di più sugli intervalli di tracciabilità soggetti a pagamento e sugli esempi di prezzi, consulta Costi di Cloud Trace.
Prima di iniziare
Prima di poter raccogliere le tracce per l'utilizzo dell'API Cloud Storage, devi completare i seguenti passaggi:
-
Enable the Cloud Trace API.
Attiva l'API Cloud Storage.
Ruoli obbligatori
Per ottenere l'autorizzazione necessaria per scrivere le tracce in Cloud Trace,
chiedi all'amministratore di concederti il ruolo IAM Agente Cloud Trace (roles/coudtrace.agent
) nel progetto utilizzato dal cliente.
Questo ruolo predefinito contiene l'autorizzazione
cloudtrace.traces.patch
necessaria per scrivere le tracce in Cloud Trace.
Potresti anche ottenere queste autorizzazioni con i ruoli predefiniti oppure creare ruoli personalizzati per concedere autorizzazioni specifiche. Per istruzioni sulla concessione dei ruoli nei progetti, consulta Concedere o revocare un ruolo. Per ulteriori informazioni sul ruolo Agente di monitoraggio in Cloud, consulta la documentazione di Identity and Access Management (IAM).
Configurare il monitoraggio per l'applicazione
Segui le istruzioni riportate di seguito per configurare il monitoraggio e iniziare a raccogliere i dati delle tracce utilizzando la libreria client di Cloud Storage:
Java
Installa le seguenti versioni della libreria client Java di Cloud Storage:
com.google.cloud:google-cloud-storage:2.47.0
o versioni successivecom.google.cloud:libraries-bom:26.53.0
o versioni successive
Installa l'esportatore Cloud Trace per OpenTelemetry. Puoi anche utilizzare qualsiasi esportatore a tua scelta.
Installa il propagatore Cloud Trace.
Crea un'istanza del client Cloud Storage con le tracce OpenTelemetry attivate.
Python
Installa la libreria client di Python per Cloud Storage:
pip install google-cloud-storage[tracing]>=2.18.0
Installa l'esportatore e il propagatore di Cloud Trace. Puoi anche utilizzare qualsiasi esportatore a tua scelta.
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
Installa la misurazione delle richieste OpenTelemetry per monitorare le richieste HTTP sottostanti.
pip install opentelemetry-instrumentation-requests
Imposta la variabile di ambiente per attivare in modo selettivo il monitoraggio per il client di archiviazione Python:
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
Configura l'esportatore di tracce e il provider di tracce.
Visualizzare le tracce
Utilizza Esplora tracce di Cloud per visualizzare i dati delle tracce nella console Google Cloud:
-
Nella console Google Cloud, vai alla pagina Esplora tracce.
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
Nella pagina Trace Explorer, fai clic su una traccia specifica nel grafico a dispersione per visualizzarne i dettagli.
Il riquadro Dettagli su Trace mostra una tabella degli intervalli della traccia.
(Facoltativo) Fai clic su una riga di intervallo per visualizzare informazioni dettagliate su un intervallo specifico, ad esempio le seguenti:
Attributi: coppie chiave-valore che forniscono informazioni aggiuntive sull'intervallo.
Log ed eventi: le voci di log associate all'intervallo.
Tracce dello stack: le tracce dello stack associate all'intervallo.
Metadati e link: link ad altri Google Cloud servizi associati all'intervallo.
Per ulteriori informazioni sull'utilizzo di Esplora tracce di Cloud, consulta Trovare ed esplorare le tracce.