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 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 compatibles de Cloud Storage:

Descripción general

Si habilitas los registros en las bibliotecas cliente de Cloud Storage, podrás supervisar el rendimiento, detectar problemas de latencia y depurar rápidamente las solicitudes de Cloud Storage. Los registros 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 registro de seguimiento se compone de varios períodos, 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

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

Visibilidad del rendimiento mejorada: Como los datos de seguimiento se generan en casi 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 registro.

Cómo funcionan los registros del cliente

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

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: Las bibliotecas cliente de Cloud Storage usan el proveedor de seguimiento, que es responsable de crear y administrar el sistema de seguimiento, lo que incluye generar y administrar seguimientos y intervalos en tu aplicación.
Exportador de seguimiento: El SDK de OpenTelemetry usa el exportador de seguimiento, que es responsable de enviar datos de seguimiento a una plataforma de observabilidad de backend, como Cloud Trace, donde puedes analizar y visualizar los 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 seleccionar 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 puedes acceder con la consola de Google Cloud y que proporciona integración con otros servicios de Google Cloud .

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

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

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 intervalos.

Precios

Los datos de seguimiento son cobrados. Los cargos se basan en la cantidad de intervalos de seguimiento que transfiere y analiza Cloud Trace. 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 registros del 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.
Enable the 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/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 puedes crear roles personalizados para otorgar permisos específicos. Si deseas obtener instrucciones para otorgar roles a 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).

Cómo configurar 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:

Java

Instala las siguientes versiones de la biblioteca cliente de Java de 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 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 Python de Cloud Storage:
```
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 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 período.
- Registros y eventos: Son las entradas de registro asociadas con el intervalo.
- Seguimiento de pila: Son los 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.