Usar trazas del lado del cliente

En esta página se describe cómo habilitar las trazas del lado del cliente con OpenTelemetry cuando se usan las bibliotecas de cliente de Cloud Storage para interactuar con Cloud Storage. Puede recoger y ver datos de traza con las siguientes bibliotecas de cliente de Cloud Storage:

Información general

Si habilitas las trazas en las bibliotecas de cliente de Cloud Storage, podrás monitorizar el rendimiento, identificar problemas de latencia y depurar rápidamente las solicitudes de Cloud Storage. Las trazas te permiten ver la secuencia de una solicitud completada y proporcionan una vista detallada de cómo Cloud Storage ha recibido, gestionado y respondido a la solicitud. Una sola traza se compone de varias extensiones, que son registros detallados con marca de tiempo de cada función u operación que ha realizado tu aplicación durante la solicitud de Cloud Storage.

Ventajas

Recoger y propagar datos de seguimiento ofrece las siguientes ventajas a tu aplicación:

  • Mayor visibilidad del rendimiento: como los datos de traza se generan casi en tiempo real a medida que Cloud Storage completa cada solicitud que haces, puedes identificar rápidamente los cuellos de botella en el rendimiento y detectar problemas de latencia.

  • Gestión de errores: puedes identificar dónde surgen los problemas, lo que acelera el análisis de la causa raíz y reduce el tiempo de inactividad. Para ello, puedes usar la información sobre cada solicitud de Cloud Storage que se proporciona en un rastreo.

Cómo funcionan las trazas del lado del cliente

En las siguientes secciones se explica en detalle cómo funciona la recogida de trazas.

Cómo funciona la recogida de trazas con OpenTelemetry

Las bibliotecas de cliente de Cloud Storage admiten la recogida de datos de traza mediante el SDK de OpenTelemetry para configurar los siguientes componentes necesarios para recoger y propagar datos de traza:

  • Proveedor de trazas: usado por las bibliotecas de cliente de Cloud Storage, el proveedor de trazas se encarga de crear y gestionar el sistema de trazas, lo que incluye generar y gestionar trazas y intervalos en tu aplicación.

  • Exportador de trazas: lo usa el SDK de OpenTelemetry. El exportador de trazas se encarga de enviar datos de trazas a una plataforma de observabilidad backend, como Cloud Trace, donde puedes analizar y visualizar los datos de trazas. Para obtener más información sobre el exportador de trazas, consulta Cómo funcionan los exportadores de trazas.

Cómo funcionan los exportadores de trazas

Para configurar los rastreos con el SDK de OpenTelemetry, debe seleccionar un backend de observabilidad al que exportar los datos para analizarlos, almacenarlos y visualizarlos. Aunque puedes exportar tus datos de traza a cualquier backend de observabilidad que elijas, te recomendamos que uses Cloud Trace, al que puedes acceder mediante la Google Cloud consola Google Cloud y que se integra con otros servicios.

Una vez que se hayan configurado y habilitado el proveedor y el exportador de trazas, podrás ver los datos de trazas casi en tiempo real a medida que se generen trazas e intervalos para cada solicitud de Cloud Storage.

Con el explorador de Cloud Trace de laGoogle Cloud consola, puedes ver cada traza, que contiene lo siguiente:

  • Vista general de una solicitud de Cloud Storage de principio a fin.

  • Varios intervalos, cada uno de los cuales registra una operación única con marca de tiempo dentro de la solicitud de Cloud Storage que se ha realizado.

Para obtener más información sobre las trazas y los intervalos, consulta la documentación de OpenTelemetry sobre trazas e intervalos.

Precios

Los datos de traza son facturables. Los cargos se basan en el número de intervalos de trazas que ingiere y analiza Cloud Trace. Para obtener más información sobre los intervalos de traza facturables y ejemplos de precios, consulta Costes de Cloud Trace.

Antes de empezar

Para recoger trazas del uso de la API Cloud Storage, debes completar los siguientes pasos:

  1. Instala la biblioteca de cliente de Cloud Storage.

  2. Configura la autenticación.

  3. Enable the Cloud Trace API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  4. Habilita la API de Cloud Storage.

    Activar la API

Roles obligatorios

Para obtener el permiso que necesitas para escribir trazas en Cloud Trace, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Agente de Cloud Trace (roles/coudtrace.agent) en el proyecto que usa el cliente.

Este rol predefinido contiene el permiso cloudtrace.traces.patch , que es necesario para escribir trazas en Cloud Trace.

También puedes obtener estos permisos con roles predefinidos o crear roles personalizados para conceder permisos específicos. Para obtener instrucciones sobre cómo asignar roles en proyectos, consulta Asignar o revocar un rol. Para obtener más información sobre el rol de agente de Cloud Trace, consulta la documentación de Gestión de Identidades y Accesos (IAM).

Configurar el rastreo de tu aplicación

Sigue estas instrucciones para configurar el rastreo y empezar a recoger datos de rastreo con la biblioteca de cliente de Cloud Storage:

C++

  1. Instala las siguientes versiones:

    • Versión 2.16.0 o posterior de la biblioteca de cliente de C++

    • C++ versión 14 o posterior

  2. Para habilitar la instrumentación de seguimiento de OpenTelemetry en la biblioteca de cliente de C++, actualiza la configuración del sistema de compilación de CMake o Bazel.

  3. Crea una instancia del cliente de Cloud Storage con las trazas de OpenTelemetry habilitadas. 

    #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. Instala las siguientes versiones de la biblioteca de cliente de Java de Cloud Storage:

    • com.google.cloud:google-cloud-storage:2.47.0 o versiones posteriores

    • com.google.cloud:libraries-bom:26.53.0 o versiones posteriores

  2. Instala el exportador de Cloud Trace para OpenTelemetry. También puedes usar el exportador que quieras.

  3. Instala el propagador de Cloud Trace.

  4. Crea una instancia del cliente de Cloud Storage con las trazas de OpenTelemetry habilitadas.

    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. Instala la biblioteca de cliente de Python de Cloud Storage:

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

  2. Instala el exportador y el propagador de Cloud Trace. También puedes usar cualquier exportador que elijas.

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

  3. Instala la instrumentación de solicitudes de OpenTelemetry para monitorizar las solicitudes HTTP subyacentes.

    pip install opentelemetry-instrumentation-requests

  4. Define la variable de entorno para habilitar selectivamente el rastreo del cliente de almacenamiento de Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configura el exportador y el proveedor de trazas. 

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

Ver tus trazas

Usa el explorador de Cloud Trace para ver tus datos de traza en la Google Cloud consola:

  1. En la Google Cloud consola, ve a la página Explorador de trazas:

    Ir a Explorador de trazas

    También puedes encontrar esta página mediante la barra de búsqueda.

  2. En la página Explorador de trazas, haz clic en una traza específica del gráfico de dispersión para ver sus detalles.

    En el panel Detalles de la traza se muestra una tabla de intervalos de traza.

  3. Opcional: Haz clic en una fila de intervalo para ver información detallada sobre un intervalo específico, como la siguiente:

    • Atributos: pares clave-valor que proporcionan información adicional sobre el intervalo.

    • Registros y eventos: entradas de registro asociadas al intervalo.

    • Rastreo de la pila: rastreo de la pila asociado al intervalo.

    • Metadatos y enlaces: enlaces a otros servicios Google Cloud asociados al intervalo.

Para obtener más información sobre cómo usar el explorador de Cloud Trace, consulta Buscar y explorar trazas.

Siguientes pasos