Se usó la API de Cloud Translation para traducir esta página.

Usa registros del cliente

En esta página, se describe cómo habilitar los registros de seguimiento 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

Habilitar el registro de seguimiento en las bibliotecas cliente de Cloud Storage te permite supervisar el rendimiento, identificar problemas de latencia y realizar la depuración rápidamente para las solicitudes de Cloud Storage. Los registros de seguimiento te permiten ver la secuencia de una solicitud completada y proporcionan una vista detallada de cómo Cloud Storage recibió, administró y respondió la solicitud. Un solo registro de seguimiento se compone de varios intervalos, que son registros detallados con marcas 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 la propagación de datos de seguimiento proporcionan 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.
Control de errores: Puedes identificar con precisión 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 registro.

Cómo funcionan los registros de rastreo del cliente

En las siguientes secciones, se explica en detalle cómo funciona la recopilación de registros.

Cómo funciona la recopilación de registros 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: Las bibliotecas cliente de Cloud Storage usan el proveedor de seguimiento para crear y administrar el sistema de seguimiento, lo que incluye generar y administrar seguimientos e intervalos en tu aplicación.
Exportador de seguimiento: El SDK de OpenTelemetry usa el exportador de seguimiento para enviar datos de seguimiento a una plataforma de observabilidad de backend, como Cloud Trace, en la que puedes analizar y visualizar los datos de seguimiento. Para obtener más información sobre el exportador de registros, consulta Cómo funcionan los exportadores de registros.

Cómo funcionan los exportadores de registros

La configuración de los registros con el SDK de OpenTelemetry incluye la selección de un backend de observabilidad para exportar tus datos, 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 puedes acceder con la consola Google Cloud y que se integra con otros servicios de Google Cloud .

Una vez que se configuran y habilitan el proveedor y el exportador de registros, puedes ver los datos de seguimiento casi en tiempo real a medida que se generan los registros y los intervalos para cada solicitud de Cloud Storage.

Con el explorador de Cloud Trace en la consola deGoogle Cloud , puedes ver cada registro de 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 y períodos.

Precios

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

Antes de comenzar

Antes de recopilar registros de tu uso de la API de Cloud Storage, debes completar los siguientes pasos:

Instala la biblioteca cliente de Cloud Storage.
Configura la autenticación.
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
Habilita la API de Cloud Storage.

Habilitar la API

Roles requeridos

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

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

También puedes obtener estos permisos con roles predefinidos o crear roles personalizados para otorgar permisos específicos. Si deseas obtener instrucciones para 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 registro de seguimiento para tu aplicación

Sigue estas instrucciones para configurar el registro de seguimiento y comenzar a recopilar datos de seguimiento con la biblioteca cliente de Cloud Storage:

C++

Instala las siguientes versiones:
- Versión 2.16.0 o posterior de la biblioteca cliente de C++
- C++ versión 14 o posterior
Para habilitar la instrumentación de seguimiento de OpenTelemetry en la biblioteca cliente de C++, actualiza la configuración del sistema de compilación para CMake o Bazel.

Crea una instancia del cliente de Cloud Storage con los registros 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

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
Instala el exportador de Cloud Trace para OpenTelemetry. También puedes usar cualquier otro exportador que desees.
Instala el propagador de Cloud Trace.

Crea una instancia del cliente de Cloud Storage con los registros 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

Instala la biblioteca cliente de Cloud Storage para Python:
```
pip install google-cloud-storage[tracing]>=2.18.0
```
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
```
Instala la instrumentación de solicitudes de OpenTelemetry para hacer un seguimiento de las solicitudes HTTP subyacentes.
```
pip install opentelemetry-instrumentation-requests
```
Establece la variable de entorno para habilitar de forma selectiva el registro del cliente de almacenamiento de Python:
```
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
```

Configura el exportador 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 consola de Google Cloud :

En la consola de Google Cloud , ve a la página Explorador de seguimiento:
Ve al Explorador de seguimiento

También puedes usar la barra de búsqueda para encontrar esta página.
En la página Explorador de seguimiento, haz clic en un seguimiento específico en el diagrama de dispersión para ver sus detalles.

En el panel Detalles del seguimiento, se muestra una tabla de intervalos de seguimiento.
Opcional: Haz clic en una fila de intervalo para ver información detallada sobre un intervalo específico, como la siguiente:
- Atributos: Son pares clave-valor que proporcionan información adicional sobre el intervalo.
- Registros y eventos: Son las entradas de registro asociadas con el intervalo.
- Seguimiento de pila: Seguimiento de pila asociado con el intervalo.
- Metadatos y vínculos: Vínculos a otros servicios de Google Cloud asociados con el intervalo.

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