Questa pagina descrive come abilitare 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 di traccia utilizzando le seguenti librerie client di Cloud Storage supportate:
Panoramica
L'abilitazione delle tracce nelle librerie client di Cloud Storage 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 di come Cloud Storage ha risposto. Una singola traccia è composta da più intervalli, ovvero record dettagliati con timestamp di ogni funzione o operazione eseguita dalla tua applicazione durante la richiesta di Cloud Storage.
Vantaggi
La raccolta e la propagazione dei dati di traccia offrono i seguenti vantaggi alla tua applicazione:
Maggiore visibilità sulle prestazioni: poiché i dati di traccia vengono generati quasi in tempo reale quando Cloud Storage completa ogni richiesta, puoi identificare rapidamente i colli di bottiglia nelle prestazioni e rilevare i problemi di latenza.
Gestione degli errori: puoi individuare con precisione dove si verificano i problemi, accelerando l'analisi della causa principale e riducendo i tempi di inattività utilizzando le informazioni su ogni richiesta di Cloud Storage fornita in una traccia.
Come funzionano le tracce lato client
Le sezioni seguenti forniscono un'analisi dettagliata del 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 tracce: utilizzato dalle librerie client di Cloud Storage, il provider di tracce è responsabile della creazione e della gestione del sistema di tracciamento, inclusa la generazione e la gestione di tracce e intervalli nell'applicazione.
Esportatore di tracce: utilizzato dall'SDK OpenTelemetry, l'esportatore di tracce è 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à in cui esportare i dati per l'analisi, l'archiviazione e la visualizzazione. Sebbene tu possa esportare i dati di traccia 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 servizi Google Cloud .
Una volta configurati e abilitati il provider e l'esportatore di tracce, puoi visualizzare i dati di traccia quasi in tempo reale man mano che vengono generate tracce e intervalli per ogni richiesta di Cloud Storage.
Utilizzando Esplora tracce di Cloud Trace nella consoleGoogle Cloud , puoi visualizzare ogni traccia che contiene 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 saperne di più su tracce e intervalli, consulta la documentazione di OpenTelemetry su tracce e intervalli.
Prezzi
I dati di Trace sono a pagamento. I costi si basano sul numero di intervalli di traccia importati e scansionati da Cloud Trace. Per scoprire di più sugli intervalli di traccia fatturabili e sugli esempi di prezzi, consulta Costi di Cloud Trace.
Prima di iniziare
Prima di poter raccogliere tracce per l'utilizzo dell'API Cloud Storage, devi completare i seguenti passaggi:
-
Abilita l'Cloud Trace API, se non è già abilitata.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre dell'autorizzazione
serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli. Abilita l'API Storage di Cloud Storage.
Ruoli obbligatori
Per ottenere l'autorizzazione necessaria per scrivere tracce in Cloud Trace, chiedi all'amministratore di concederti il ruolo IAM Cloud Trace Agent (roles/cloudtrace.agent) nel progetto utilizzato dal client.
Questo ruolo predefinito contiene l'autorizzazione cloudtrace.traces.patch, necessaria per scrivere tracce in Cloud Trace.
Potresti anche ottenere queste autorizzazioni con ruoli predefiniti oppure puoi creare ruoli personalizzati per concedere autorizzazioni specifiche. Per istruzioni sulla concessione dei ruoli ai progetti, consulta Concedi o revoca un ruolo. Per saperne di più sul ruolo Agente Cloud Trace, consulta la documentazione di Identity and Access Management (IAM).
Configura il tracciamento per la tua applicazione
Segui queste istruzioni per configurare il tracciamento e iniziare a raccogliere i dati di traccia utilizzando la libreria client di Cloud Storage:
C++
Installa le seguenti versioni:
Libreria client C++ versione v2.16.0 o successive
C++ versione 14 o successive
Per abilitare la strumentazione di tracciamento OpenTelemetry nella libreria client C++, aggiorna la configurazione del sistema di build per CMake o Bazel.
Crea un'istanza del client Cloud Storage con le tracce OpenTelemetry abilitate.
Java
Installa le seguenti versioni della libreria client Java di Cloud Storage:
com.google.cloud:google-cloud-storage:2.47.0o versioni successivecom.google.cloud:libraries-bom:26.53.0o versioni successive
Installa l'esportatore di Cloud Trace per OpenTelemetry. Puoi anche utilizzare qualsiasi esportatore di tua scelta.
Installa il propagatore di Cloud Trace.
Crea un'istanza del client Cloud Storage con le tracce OpenTelemetry abilitate.
Python
Installa la libreria client Python di 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 di tua scelta.
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
Installa la strumentazione delle richieste OpenTelemetry per tracciare le richieste HTTP sottostanti.
pip install opentelemetry-instrumentation-requests
Imposta la variabile di ambiente per attivare selettivamente il tracciamento per il client di archiviazione Python:
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
Configura l'esportatore e il provider di tracce.
Rust
Aggiungi la libreria client Rust di Cloud Storage e i crate
tracinge OpenTelemetry al file manifestCargo.toml:cargo add google-cloud-storage opentelemetry opentelemetry_sdk opentelemetry-otlp tracing tracing-opentelemetry tracing-subscriber
Configura una struttura OpenTelemetry
SdkTracerProvidercon un esportatore OTLP (ad esempio, inviando gli span a un OpenTelemetry Collector o all'API Telemetry), registra un sottoscrittoretracinge crea un clientStoragecon il metodo.with_tracing()abilitato:
Visualizza le tracce
Utilizza Esplora tracce di Cloud Trace per visualizzare i dati di traccia 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 di traccia.
(Facoltativo) Fai clic su una riga di intervallo per visualizzare informazioni dettagliate su un intervallo specifico, ad esempio:
Attributi: coppie chiave-valore che forniscono informazioni aggiuntive sullo span.
Log ed eventi: voci di log associate allo span.
Analisi dello stack: analisi dello stack associate allo span.
Metadati e link: link ad altri servizi Google Cloud associati allo span.
Per saperne di più sull'utilizzo di Esplora tracce di Cloud Trace, consulta Trova ed esplora le tracce.