Utiliser des traces côté client

Cette page explique comment activer les traces côté client avec OpenTelemetry lorsque vous utilisez les bibliothèques clientes Cloud Storage pour interagir avec Cloud Storage. Vous pouvez collecter et afficher des données de trace à l'aide des bibliothèques clientes Cloud Storage compatibles suivantes :

Présentation

L'activation des traces dans les bibliothèques clientes Cloud Storage vous permet de surveiller les performances, d'identifier les problèmes de latence et de déboguer rapidement les requêtes Cloud Storage. Les traces vous permettent de voir la séquence d'une requête terminée, en fournissant une vue détaillée de la façon dont la requête a été reçue, gérée et traitée par Cloud Storage. Une trace unique est composée de plusieurs spans, qui sont des enregistrements détaillés et horodatés de chaque fonction ou opération effectuée par votre application tout au long de la requête Cloud Storage.

Avantages

La collecte et la propagation des données de trace offrent les avantages suivants à votre application :

  • Visibilité améliorée sur les performances : les données de trace étant générées en temps quasi réel à mesure que Cloud Storage traite chaque requête que vous effectuez, vous pouvez rapidement identifier les goulots d'étranglement et détecter les problèmes de latence.

  • Gestion des erreurs : vous pouvez identifier précisément les problèmes, ce qui accélère l'analyse des causes premières et réduit les temps d'arrêt grâce aux informations sur chaque requête Cloud Storage fournies dans une trace.

Fonctionnement des traces côté client

Les sections suivantes expliquent en détail comment fonctionne la collecte de traces.

Fonctionnement de la collecte de traces avec OpenTelemetry

Les bibliothèques clientes Cloud Storage sont compatibles avec la collecte de données de trace à l'aide du SDK OpenTelemetry pour configurer les composants suivants requis pour collecter et propager les données de trace :

  • Fournisseur de trace : utilisé par les bibliothèques clientes Cloud Storage, le fournisseur de trace est responsable de la création et de la gestion du système de traçage, y compris de la génération et de la gestion des traces et des spans dans votre application.

  • Exportateur de trace : utilisé par le SDK OpenTelemetry, l'exportateur de trace est chargé d'envoyer les données de trace à une plate-forme d'observabilité de backend telle que Cloud Trace, où vous pouvez analyser et visualiser les données de trace. Pour en savoir plus sur l'exportateur de trace, consultez Fonctionnement des exportateurs de trace.

Fonctionnement des exportateurs de trace

La configuration des traces à l'aide du SDK OpenTelemetry inclut la sélection d'un backend d'observabilité vers lequel exporter vos données pour qu'elles soient analysées, stockées et visualisées. Bien que vous puissiez exporter vos données de trace vers le backend d'observabilité de votre choix, nous vous recommandons d'utiliser Cloud Trace, accessible depuis la console Google Cloud et qui s'intègre à d'autres services Google Cloud .

Une fois le fournisseur et l'exportateur de trace configurés et activés, vous pouvez afficher les données de trace en quasi-temps réel à mesure que les traces et les spans sont générés pour chaque requête Cloud Storage.

L'explorateur Cloud Trace de la consoleGoogle Cloud vous permet d'afficher chaque trace, qui contient les éléments suivants :

  • Vue d'ensemble d'une requête Cloud Storage de bout en bout.

  • Plusieurs portées, chacune capturant une opération unique horodatée dans la requête Cloud Storage qui a été effectuée.

Pour en savoir plus sur les traces et les spans, consultez la documentation OpenTelemetry sur les traces et les spans.

Tarifs

Les données de trace sont payantes. Les frais dépendent du nombre de segments de trace ingérés et analysés par Cloud Trace. Pour en savoir plus sur les spans de trace facturables et les exemples de tarification, consultez Coûts de Cloud Trace.

Avant de commencer

Avant de pouvoir collecter des traces pour votre utilisation de l'API Cloud Storage, vous devez effectuer les étapes suivantes :

  1. Installez la bibliothèque cliente Cloud Storage.

  2. Configurez l'authentification.

  3. Enable the Cloud Trace API.

    Enable the API

  4. Activez l'API Cloud Storage.

    Activer l'API

Rôles requis

Pour obtenir l'autorisation nécessaire pour écrire des traces dans Cloud Trace, demandez à votre administrateur de vous accorder le rôle IAM Agent Cloud Trace (roles/coudtrace.agent) sur le projet utilisé par le client.

Ce rôle prédéfini contient l'autorisation cloudtrace.traces.patch, qui est nécessaire pour écrire des traces dans Cloud Trace.

Vous pouvez également obtenir ces autorisations avec des rôles prédéfinis ou créer des rôles personnalisés pour accorder des autorisations spécifiques. Pour savoir comment attribuer des rôles aux projets, consultez Attribuer ou révoquer un rôle. Pour en savoir plus sur le rôle d'agent Cloud Trace, consultez la documentation sur Identity and Access Management (IAM).

Configurer le traçage pour votre application

Suivez les instructions ci-dessous pour configurer le traçage et commencer à collecter des données de trace à l'aide de la bibliothèque cliente Cloud Storage :

C++

  1. Installez les versions suivantes :

    • Bibliothèque cliente C++ version v2.16.0 ou ultérieure

    • C++ version 14 ou ultérieure

  2. Pour activer l'instrumentation de traçage OpenTelemetry dans la bibliothèque cliente C++, mettez à jour la configuration de votre système de compilation pour CMake ou Bazel.

  3. Créez une instance du client Cloud Storage avec les traces OpenTelemetry activées. 

    #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. Installez les versions suivantes de la bibliothèque cliente Java Cloud Storage :

    • com.google.cloud:google-cloud-storage:2.47.0 ou version ultérieure

    • com.google.cloud:libraries-bom:26.53.0 ou version ultérieure

  2. Installez l'exportateur Cloud Trace pour OpenTelemetry. Vous pouvez également utiliser l'exportateur de votre choix.

  3. Installez le propagateur Cloud Trace.

  4. Créez une instance du client Cloud Storage avec les traces OpenTelemetry activées.

    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. Installez la bibliothèque cliente Python Cloud Storage :

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

  2. Installez l'exportateur et le propagateur Cloud Trace. Vous pouvez également utiliser l'exportateur de votre choix.

    pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp

  3. Installez l'instrumentation des requêtes OpenTelemetry pour suivre les requêtes HTTP sous-jacentes.

    pip install opentelemetry-instrumentation-requests

  4. Définissez la variable d'environnement pour activer sélectivement le traçage pour le client de stockage Python :

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configurez l'exportateur et le fournisseur de trace. 

    
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))

Afficher vos traces

Utilisez l'explorateur Cloud Trace pour afficher vos données de trace dans la console Google Cloud  :

  1. Dans la console Google Cloud , accédez à la page Explorateur Trace :

    Accéder à Explorateur Trace

    Vous pouvez également accéder à cette page à l'aide de la barre de recherche.

  2. Sur la page Trace explorer (Explorateur de traces), cliquez sur une trace spécifique dans le graphique en nuage de points pour afficher ses détails.

    Le volet Détails des traces affiche un tableau des délais de trace.

  3. Facultatif : Cliquez sur une ligne de portée pour afficher des informations détaillées sur une portée spécifique, telles que les suivantes :

    • Attributs : paires clé/valeur qui fournissent des informations supplémentaires sur la portée.

    • Journaux et événements : entrées de journaux associées à la période.

    • Traces de pile : traces de pile associées à la portée.

    • Métadonnées et liens : liens vers d'autres services Google Cloud associés à la portée.

Pour en savoir plus sur l'utilisation de l'explorateur Cloud Trace, consultez la page Rechercher et explorer des traces.

Étapes suivantes