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 la ubicación 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 con otros servicios de Google Cloud .
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 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:
-
Enable the Cloud Trace API.
Habilita la API de Cloud Storage.
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 posteriorcom.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.
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.
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.