Utilizza le tracce lato client

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 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ù intervalli, che sono 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 di traccia offrono i seguenti vantaggi per la tua applicazione:

  • Visibilità delle prestazioni migliorata: 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 dove si verificano i problemi, accelerare l'analisi della causa principale e ridurre i tempi di inattività utilizzando le informazioni su ogni richiesta di Cloud Storage fornite in una traccia.

Come funzionano le tracce lato client

Le sezioni seguenti forniscono una descrizione dettagliata di come funziona la 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 nella tua 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 saperne 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 Google Cloud console e che fornisce l'integrazione con altri Google Cloud servizi.

Una volta configurati e abilitati il provider di tracce e l'esportatore di tracce, puoi visualizzare i dati di traccia quasi in tempo reale man mano che vengono generati tracce e intervalli per ogni richiesta di Cloud Storage.

Utilizzando Esplora tracce nella Google Cloud console, puoi visualizzare ogni traccia che contiene quanto segue:

  • Una visualizzazione di alto livello di una richiesta di Cloud Storage end-to-end.

  • Più intervalli, ognuno dei quali acquisisce una singola operazione con timestamp eseguita all'interno della richiesta di Cloud Storage.

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. Gli addebiti si basano sul numero di intervalli di traccia importati e scansionati da Cloud Trace. Per saperne di più sugli intervalli di traccia addebitabili 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:

  1. Installa la libreria client di Cloud Storage.

  2. Configura l'autenticazione.

  3. Abilita l'Cloud Trace API.

    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 utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  4. Abilita l'API Storage di Cloud Storage.

    Abilitare l'API

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/cloudtrace.agent) nel progetto utilizzato dal client.

Questo ruolo predefinito contiene l' cloudtrace.traces.patch autorizzazione, necessaria per scrivere le 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 nei progetti, consulta Concedere o revocare un ruolo. Per saperne di più sul ruolo Agente Cloud Trace, consulta la documentazione di Identity and Access Management (IAM).

Configurare il tracciamento per l'applicazione

Segui queste istruzioni per configurare il tracciamento e iniziare a raccogliere i dati di traccia utilizzando la libreria client di Cloud Storage:

C++

  1. Installa le seguenti versioni:

    • Libreria client C++ versione v2.16.0 o successive

    • C++ versione 14 o successive

  2. Per abilitare la strumentazione di tracciamento OpenTelemetry nella libreria client C++, aggiorna la configurazione del sistema di compilazione per CMake o Bazel.

  3. Crea un'istanza del client Cloud Storage con le tracce OpenTelemetry abilitate. 

    #include "google/cloud/opentelemetry/configure_basic_tracing.h"
#include "google/cloud/storage/client.h"
#include "google/cloud/opentelemetry_options.h"
#include <iostream>

int main(int argc, char* argv[]) {
  if (argc != 3) {
    std::cerr << "Usage: " << argv[0] << " <bucket-name> <project-id>\n";
    return 1;
  }
  std::string const bucket_name = argv[1];
  std::string const project_id = argv[2];

  // Create aliases to make the code easier to read.
  namespace gc = ::google::cloud;
  namespace gcs = ::google::cloud::storage;

  // Instantiate a basic tracing configuration which exports traces to Cloud
  // Trace. By default, spans are sent in batches and always sampled.
  auto project = gc::Project(project_id);
  auto configuration = gc::otel::ConfigureBasicTracing(project);

  // Create a client with OpenTelemetry tracing enabled.
  auto options = gc::Options{}.set<gc::OpenTelemetryTracingOption>(true);
  auto client = gcs::Client(options);

  auto writer = client.WriteObject(bucket_name, "quickstart.txt");
  writer << "Hello World!";
  writer.Close();
  if (!writer.metadata()) {
    std::cerr << "Error creating object: " << writer.metadata().status()
              << "\n";
    return 1;
  }
  std::cout << "Successfully created object: " << *writer.metadata() << "\n";

  auto reader = client.ReadObject(bucket_name, "quickstart.txt");
  if (!reader) {
    std::cerr << "Error reading object: " << reader.status() << "\n";
    return 1;
  }

  std::string contents{std::istreambuf_iterator<char>{reader}, {}};
  std::cout << contents << "\n";

  // The basic tracing configuration object goes out of scope. The collected
  // spans are flushed to Cloud Trace.

  return 0;
}

Java

  1. Installa le seguenti versioni della libreria client Java di Cloud Storage:

    • com.google.cloud:google-cloud-storage:2.47.0 o versioni successive

    • com.google.cloud:libraries-bom:26.53.0 o versioni successive

  2. Installa l'esportatore di Cloud Trace per OpenTelemetry. Puoi anche utilizzare qualsiasi esportatore di tua scelta.

  3. Installa il propagatore di Cloud Trace.

  4. Crea un'istanza del client Cloud Storage con le tracce OpenTelemetry abilitate.

    public class QuickstartOpenTelemetrySample {
  public static void main(String... args) throws Exception {
    SpanExporter spanExporter = TraceExporter.createWithDefaultConfiguration();
    TextMapPropagator propagators =
        TextMapPropagator.composite(
            W3CTraceContextPropagator.getInstance(),
            new XCloudTraceContextPropagator(/* oneway= */ true));

    OpenTelemetrySdk openTelemetry =
        OpenTelemetrySdk.builder()
            .setPropagators(ContextPropagators.create(propagators))
            .setTracerProvider(
                SdkTracerProvider.builder()
                    // Sample Rate is set to alwaysOn
                    // It is recommended to sample based on a ratio for standard use ie.
                    // .setSampler(Sampler.traceIdRatioBased(0.2)) // sample only 20% of trace ids
                    .setSampler(Sampler.alwaysOn())
                    .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
                    .build())
            .build();
    StorageOptions options = StorageOptions.newBuilder().setOpenTelemetry(openTelemetry).build();
    Storage storage = options.getService();
    System.out.println("Created an instance of storage with OpenTelemetry configured");
  }
}

Python

  1. Installa la libreria client Python di Cloud Storage:

    pip install google-cloud-storage[tracing]>=2.18.0

  2. 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

  3. Installa la strumentazione delle richieste OpenTelemetry per tracciare le richieste HTTP sottostanti.

    pip install opentelemetry-instrumentation-requests

  4. Imposta la variabile di ambiente per attivare selettivamente il tracciamento per il client di archiviazione Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configura l'esportatore di tracce e il provider di tracce. 

    
from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.resourcedetector.gcp_resource_detector import (
    GoogleCloudResourceDetector,
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
# Optional: Enable traces emitted from the requests HTTP library.
from opentelemetry.instrumentation.requests import RequestsInstrumentor

from google.cloud import storage

# The ID of your GCS bucket
# bucket_name = "your-bucket-name"
# The ID of your GCS object
# blob_name = "your-object-name"
# The contents to upload to the file
# data = "The quick brown fox jumps over the lazy dog."

# In this sample, we use Google Cloud Trace to export the OpenTelemetry
# traces: https://cloud.google.com/trace/docs/setup/python-ot
# Choose and configure the exporter for your environment.

tracer_provider = TracerProvider(
    # Sampling is set to ALWAYS_ON.
    # It is recommended to sample based on a ratio to control trace ingestion volume,
    # for instance, sampler=TraceIdRatioBased(0.2)
    sampler=ALWAYS_ON,
    resource=GoogleCloudResourceDetector().detect(),
)

# Export to Google Cloud Trace.
tracer_provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Optional: Enable traces emitted from the requests HTTP library.
RequestsInstrumentor().instrument(tracer_provider=tracer_provider)

# Get the tracer and create a new root span.
tracer = tracer_provider.get_tracer("My App")
with tracer.start_as_current_span("trace-quickstart"):
    # Instantiate a storage client and perform a write and read workload.
    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    blob.upload_from_string(data)
    print(f"{blob_name} uploaded to {bucket_name}.")

    blob.download_as_bytes()
    print("Downloaded storage object {} from bucket {}.".format(blob_name, bucket_name))

Visualizzare le tracce

Utilizza Esplora tracce per visualizzare i dati di traccia nella Google Cloud console:

  1. Nella Google Cloud console, vai alla Esplora tracce pagina:

    Vai a Esplora tracce

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nella pagina Esplora tracce, 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.

  3. (Facoltativo) Fai clic su una riga dell'intervallo per visualizzare informazioni dettagliate su un intervallo specifico, ad esempio le seguenti informazioni:

    • Attributi: coppie chiave-valore che forniscono informazioni aggiuntive su l'intervallo.

    • Log ed eventi: voci di log associate all'intervallo.

    • Tracce dello stack: tracce dello stack associate all'intervallo.

    • Metadati e link: link ad altri Google Cloud servizi associati all'intervallo.

Per saperne di più sull'utilizzo di Esplora tracce, consulta Trovare ed esplorare le tracce.

Passaggi successivi