Usa registros del cliente

En esta página, se describe cómo habilitar los seguimientos del cliente con OpenTelemetry cuando usas las bibliotecas cliente de Cloud Storage para interactuar con Cloud Storage. Puedes recopilar y ver datos de seguimiento con las siguientes bibliotecas cliente de Cloud Storage compatibles:

Descripción general

Si habilitas los seguimientos en las bibliotecas cliente de Cloud Storage, puedes supervisar el rendimiento, identificar problemas de latencia y realizar depuraciones rápidamente para las solicitudes de Cloud Storage. Los seguimientos te permiten ver la secuencia de una solicitud completada y proporcionan una vista detallada de cómo Cloud Storage recibió, administró y respondió a la solicitud. Un solo seguimiento se compone de varios intervalos, que son registros detallados con marca de tiempo de cada función u operación que realizó tu aplicación durante la solicitud de Cloud Storage.

Beneficios

La recopilación y propagación de datos de seguimiento proporciona los siguientes beneficios a tu aplicación:

  • Visibilidad mejorada del rendimiento: Debido a que los datos de seguimiento se generan casi en tiempo real a medida que Cloud Storage completa cada solicitud que realizas, puedes identificar rápidamente los cuellos de botella en el rendimiento y detectar problemas de latencia.

  • Manejo de errores: Puedes identificar dónde surgen los problemas, acelerar el análisis de la causa raíz y reducir el tiempo de inactividad con la información sobre cada solicitud de Cloud Storage que se proporciona en un seguimiento.

Cómo funcionan los seguimientos del cliente

En las siguientes secciones, se proporciona una descripción detallada de cómo funciona la recopilación de seguimientos.

Cómo funciona la recopilación de seguimientos con OpenTelemetry

Las bibliotecas cliente de Cloud Storage admiten la recopilación de datos de seguimiento con el SDK de OpenTelemetry para configurar los siguientes componentes necesarios para recopilar y propagar datos de seguimiento:

  • **Proveedor de seguimiento**: Usado por las bibliotecas cliente de Cloud Storage, el proveedor de seguimiento es responsable de crear y administrar el sistema de seguimiento, incluida la generación y administración de seguimientos e intervalos en tu aplicación.

  • Exportador de seguimiento: Usado por el SDK de OpenTelemetry, el exportador de seguimiento es responsable de enviar datos de seguimiento a una plataforma de observabilidad de backend, como Cloud Trace, en la que puedes analizar y visualizar datos de seguimiento. Para obtener más información sobre el exportador de seguimiento, consulta Cómo funcionan los exportadores de seguimiento.

Cómo funcionan los exportadores de seguimiento

La configuración de seguimientos con el SDK de OpenTelemetry incluye la selección de un backend de observabilidad para exportar tus datos a donde se analizan, almacenan y visualizan. Si bien puedes exportar tus datos de seguimiento a cualquier backend de observabilidad que elijas, te recomendamos que uses Cloud Trace, al que se puede acceder con la Google Cloud consola y que proporciona integración con otros Google Cloud servicios.

Una vez que el proveedor de seguimiento y el exportador de seguimiento estén configurados y habilitados, podrás ver los datos de seguimiento casi en tiempo real a medida que se generen seguimientos e intervalos para cada solicitud de Cloud Storage.

Con el explorador de Cloud Trace en la Google Cloud consola, puedes ver cada seguimiento que contiene lo siguiente:

  • Una vista de alto nivel de una solicitud de Cloud Storage de extremo a extremo

  • Varios intervalos, cada uno de los cuales captura una sola operación con marca de tiempo dentro de la solicitud de Cloud Storage que se realizó

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

Precios

Los datos de seguimiento son facturables. Los cargos se basan en la cantidad de intervalos de seguimiento que Cloud Trace transfirió y analizó. Para obtener más información sobre los intervalos de seguimiento facturables y los ejemplos de precios, consulta Costos de Cloud Trace.

Antes de comenzar

Antes de poder recopilar seguimientos para el uso de la API de Cloud Storage, debes completar los siguientes pasos:

  1. Instala la biblioteca cliente de Cloud Storage.

  2. Configura la autenticación.

  3. Habilita la API de Cloud Trace.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

    Habilitar la API

  4. Habilita la API de Cloud Storage.

    Habilitar la API

Roles obligatorios

Para obtener el permiso que necesitas para escribir seguimientos en Cloud Trace, pídele a tu administrador que te otorgue el rol de IAM de agente de Cloud Trace (roles/cloudtrace.agent) en el proyecto que usa el cliente.

Este rol predefinido contiene el cloudtrace.traces.patch permiso, que se requiere para escribir seguimientos en Cloud Trace.

También puedes obtener estos permisos con roles predefinidos o crear roles personalizados para otorgar permisos específicos. Para obtener instrucciones sobre cómo otorgar roles en proyectos, consulta Otorga o revoca un rol. Para obtener más información sobre el rol de agente de Cloud Trace, consulta la documentación de Identity and Access Management (IAM).

Configura el seguimiento para tu aplicación

Usa las siguientes instrucciones para configurar el seguimiento y comenzar a recopilar datos de seguimiento con la biblioteca cliente de Cloud Storage:

C++

  1. Instala las siguientes versiones:

    • Biblioteca cliente de C++ versión v2.16.0 o posterior

    • C++ versión 14 o posterior

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

  3. Crea una instancia del cliente de Cloud Storage con los seguimientos de OpenTelemetry habilitados. 

    #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 cliente de Cloud Storage para Java:

    • com.google.cloud:google-cloud-storage:2.47.0 o posterior

    • com.google.cloud:libraries-bom:26.53.0 o posterior

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

  3. Instala el propagador de Cloud Trace.

  4. Crea una instancia del cliente de Cloud Storage con los seguimientos de OpenTelemetry habilitados.

    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 cliente de Cloud Storage para Python:

    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 rastrear las solicitudes HTTP subyacentes.

    pip install opentelemetry-instrumentation-requests

  4. Configura la variable de entorno para habilitar de forma selectiva el seguimiento para el cliente de almacenamiento de Python:

    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

  5. Configura el exportador de seguimiento y el proveedor de seguimiento. 

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

Ve tus seguimientos

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

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

    Ir al Explorador de seguimiento

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

  2. En la página Explorador de seguimiento, haz clic en un seguimiento específico en el diagrama de dispersión para ver los detalles del seguimiento.

    En el panel Detalles del seguimiento , se muestra una tabla de intervalos de seguimiento.

  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 con el intervalo.

    • Seguimientos de pila: Seguimientos de pila asociados con el intervalo.

    • Metadatos y vínculos: Vínculos a otros Google Cloud servicios asociados con el intervalo.

Si deseas obtener más información para usar el explorador de Cloud Trace, consulta Busca y explora seguimientos.

¿Qué sigue?