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 d'effectuer rapidement le débogage des requêtes Cloud Storage. Les traces vous permettent de voir la séquence d'une requête terminée, ce qui vous donne une vue détaillée de la façon dont Cloud Storage a reçu, géré et répondu à la requête. Une trace unique est composée de plusieurs spans, qui sont des enregistrements détaillés avec horodatage 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 présentent les avantages suivants pour votre application:

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

  • Gestion des erreurs: vous pouvez identifier les problèmes, accélérer l'analyse des causes et réduire les temps d'arrêt à l'aide des informations sur chaque requête Cloud Storage fournies dans une trace.

Fonctionnement des traces côté client

Les sections suivantes décrivent en détail le fonctionnement de la collecte des 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 traces: utilisé par les bibliothèques clientes Cloud Storage, le fournisseur de traces est chargé de créer et de gérer le système de traçage, y compris de générer et de gérer les traces et les segments dans votre application.

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

Fonctionnement des exportateurs de traces

La configuration des traces à l'aide du SDK OpenTelemetry inclut la sélection d'un backend d'observabilité pour exporter vos données vers l'emplacement où elles sont analysées, stockées et visualisées. Bien que vous puissiez exporter vos données de trace vers n'importe quel backend d'observabilité de votre choix, nous vous recommandons d'utiliser Cloud Trace, accessible via la console Google Cloud et qui permet l'intégration avec d'autres services Google Cloud .

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

L'explorateur Cloud Trace de la console Google Cloud vous permet d'afficher chaque trace contenant les éléments suivants:

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

  • Plusieurs périodes, chacune capturant une seule opération avec horodatage dans la requête Cloud Storage effectuée.

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

Tarifs

Les données de trace sont facturées. Les frais dépendent du nombre de délais de trace ingérés et analysés par Cloud Trace. Pour en savoir plus sur les périodes de suivi facturables et les exemples de tarification, consultez la section Coûts de Cloud Trace.

Avant de commencer

Avant de pouvoir collecter des traces de votre utilisation de l'API Cloud Storage, vous devez suivre la procédure suivante:

  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 dont vous avez besoin 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 la page 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 suivantes pour configurer le traçage et commencer à collecter des données de traçage à l'aide de la bibliothèque cliente Cloud Storage:

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 de manière sélective le traçage pour le client de stockage Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

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

    
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 (Explorer 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 délai pour afficher des informations détaillées sur un délai spécifique, comme les informations suivantes:

    • Attributs: paires clé-valeur qui fournissent des informations supplémentaires sur la période.

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

    • Traces de pile: traces de pile associées à la période.

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

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

Étape suivante