Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

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

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

Beneficios

Recopilar y propagar 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 con rapidez los cuellos de botella en el rendimiento y detectar problemas de latencia.
Manejo 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 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 analiza en detalle 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: El proveedor de seguimiento, que usan las bibliotecas cliente de Cloud Storage, es responsable de crear y administrar el sistema de seguimiento, lo que incluye generar y administrar seguimientos y lapsos en tu aplicación.
Exportador de seguimientos: El SDK de OpenTelemetry usa el exportador de seguimientos, que 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 seguimientos, consulta Cómo funcionan los exportadores de seguimientos.

Cómo funcionan los exportadores de seguimientos

La configuración de seguimientos con el SDK de OpenTelemetry incluye la selección de un backend de observabilidad para exportar tus datos al lugar 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 consola de Google Cloud y que proporciona integración en otros servicios de Google Cloud .

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

Con el Explorador de Cloud Trace en la consola deGoogle Cloud , 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 se cobran. Los cargos se basan en la cantidad de intervalos de seguimiento transferidos y analizados por Cloud Trace. Para obtener más información sobre los intervalos de seguimiento que se cobran y ejemplos de precios, consulta Costos de Cloud Trace.

Antes de comenzar

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

Instala la biblioteca cliente de Cloud Storage.
Configura la autenticación.
Habilita la API de Cloud Trace si aún no está habilitada.
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 obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.
Habilitar la API
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 permiso cloudtrace.traces.patch, que se requiere para escribir seguimientos en Cloud Trace.

También puedes obtener estos permisos con roles predefinidos o puedes 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

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

C++

Instala las siguientes versiones:
- Versión v2.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 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

Instala las siguientes versiones de la biblioteca cliente de Java para Cloud Storage:
- 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 elijas.
Instala el propagador de Cloud Trace.

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

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
```
Configura la variable de entorno para habilitar de forma selectiva el seguimiento del cliente de almacenamiento de Python:
```
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
```

Configura el exportador y el proveedor de seguimientos.


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

Rust

Agrega la biblioteca cliente de Rust para Cloud Storage y los crates tracing y OpenTelemetry a tu archivo de manifiesto Cargo.toml:

cargo add google-cloud-storage opentelemetry opentelemetry_sdk opentelemetry-otlp tracing tracing-opentelemetry tracing-subscriber

Configura un struct SdkTracerProvider de OpenTelemetry con un exportador de OTLP (por ejemplo, enviando intervalos a un recopilador de OpenTelemetry o a la API de Telemetry), registra un suscriptor tracing y compila un cliente Storage con el método .with_tracing() habilitado:

use google_cloud_storage::client::Storage;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample(bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "enable-otel-tracing.txt";

    // Create an OTLP exporter to send spans to an OpenTelemetry Collector
    // running on localhost (the default).
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("storage-quickstart");

    // Create a tracing layer and register the subscriber for the current scope.
    // In an application's `main`, use `tracing::subscriber::set_global_default` instead.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);
    let subscriber = Registry::default().with(telemetry);
    let _guard = tracing::subscriber::set_default(subscriber);

    // Build a Storage client with client-side tracing enabled.
    let client = Storage::builder().with_tracing().build().await?;

    let object = client
        .write_object(
            format!("projects/_/buckets/{bucket_id}"),
            NAME,
            "Hello, world!",
        )
        .set_if_generation_match(0)
        .send_unbuffered()
        .await?;
    println!("Uploaded object {} to bucket {bucket_id}.", object.name);

    let mut reader = client
        .read_object(format!("projects/_/buckets/{bucket_id}"), NAME)
        .send()
        .await?;
    let mut contents = Vec::new();
    while let Some(chunk) = reader.next().await.transpose()? {
        contents.extend_from_slice(&chunk);
    }
    println!(
        "Downloaded {} bytes from object {NAME} in bucket {bucket_id}.",
        contents.len()
    );

    Ok(())
}

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 los detalles del seguimiento.

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.
- Seguimientos de pila: Son los seguimientos de pila asociados con el intervalo.
- Metadatos y vínculos: vínculos a otros servicios de Google Cloud que están asociados con el intervalo.

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