Instrumenta para Cloud Trace

Puedes instrumentar tus aplicaciones para que Cloud Trace capture datos de seguimiento distribuidos, examine la latencia de las solicitudes individuales y vea la latencia agregada en tus servicios en la consola de Trace.

En este documento, se proporciona una descripción general de los enfoques de instrumentación y las opciones de configuración. Para obtener instrucciones paso a paso sobre lenguajes de programación específicos, consulta las páginas de configuración de cada lenguaje.

Cuándo instrumentar tu aplicación

Instrumenta tu aplicación para recopilar información específica que te ayude a comprender su rendimiento y solucionar problemas. Varios frameworks de instrumentación de código abierto recopilan datos de registros, métricas y seguimientos, y pueden enviar esos datos a cualquier proveedor, incluido Google Cloud. Para tus aplicaciones de agentes, algunos frameworks pueden recopilar tus instrucciones y respuestas, o pasar contexto que permita hacer un seguimiento de algunas llamadas remotas a los servidores de MCP de Google Cloud.

Para instrumentar tu aplicación, te recomendamos que uses un framework de instrumentación de código abierto y neutral con respecto al proveedor, como OpenTelemetry, en lugar de las APIs o bibliotecas cliente específicas del proveedor y del producto. Para obtener información sobre estos frameworks, consulta Observabilidad para desarrolladores de aplicaciones y Elige un enfoque de instrumentación.

Cómo instrumentar aplicaciones

Existen varios enfoques que puedes usar para instrumentar tu aplicación:

  • Recomendado: Usa OpenTelemetry, configura tu aplicación con un exportador de OTLP que envíe datos de seguimiento a un recopilador y configura el recopilador para que envíe datos de seguimiento a tu proyecto de Google Cloud con la API de Telemetry (OTLP). Para obtener más información sobre nuestras recomendaciones, consulta Elige un enfoque de instrumentación.

  • Usa OpenTelemetry y configura tu aplicación con un exportador de OTLP que envíe tus datos de seguimiento a tu proyecto de Google Cloud con la API de Telemetry.

  • Si escribes aplicaciones que se ejecutan en Compute Engine, puedes usar el Agente de operaciones y el receptor del protocolo OpenTelemetry (OTLP) para recopilar seguimientos y métricas de tu aplicación. El Agente de operaciones también puede recopilar registros, pero no con OTLP. Para obtener más información, consulta Usa el Agente de operaciones y OTLP y Descripción general del Agente de operaciones.

  • Invoca directamente la API de Telemetry o la API de Cloud Trace.

  • En el caso de las aplicaciones de Spring Boot, configúralas para que reenvíen los datos de seguimiento que recopilan a Cloud Trace. Para obtener información sobre este procedimiento, consulta Spring Cloud para Google Cloud: Cloud Trace.

  • Usa las bibliotecas cliente de Cloud Trace o el exportador de Cloud Trace para OpenTelemetry.

Ejemplos de instrumentación

Las muestras de instrumentación que proporcionamos usan OpenTelemetry:

Crea intervalos personalizados

Si bien OpenTelemetry y las bibliotecas cliente te permiten crear intervalos personalizados, es posible que no necesites crearlos de forma manual, ya que estas bibliotecas crean intervalos automáticamente en los límites de RPC.

También puedes agregar información relevante para tu aplicación agregando anotaciones y etiquetas personalizadas a los intervalos existentes, o puedes crear intervalos secundarios nuevos con sus propias anotaciones y etiquetas para hacer un seguimiento del comportamiento de la aplicación con mayor nivel de detalle.

Por lo general, las bibliotecas mantienen un contexto de seguimiento global que contiene información sobre el intervalo actual, incluidos su ID de seguimiento y su estado de muestreo. Las aplicaciones pueden acceder al intervalo actual a través del contexto de seguimiento global. Debido a que el contexto es global, asegúrate de que las aplicaciones de varios subprocesos propaguen el contexto entre los subprocesos para mantener datos de seguimiento precisos.

Forzar el muestreo de seguimientos

No puedes forzar el muestreo de los intervalos porque cada componente de la ruta de acceso de la solicitud toma una decisión de muestreo independiente. Sin embargo, puedes influir en los componentes downstream si configuras la marca sampled en el encabezado de seguimiento como true. Este parámetro de configuración es una sugerencia para que los componentes secundarios muestreen la solicitud. Para obtener más información sobre los encabezados de seguimiento, consulta Protocolos para la propagación de contexto.

  • Tus aplicaciones: Configura cómo la lógica de instrumentación respeta la marca sampled. Por ejemplo, cuando usas OpenTelemetry, puedes usar el muestreador ParentBased para asegurarte de que se respete la marca de muestreo del elemento superior.

  • Servicios deGoogle Cloud : Cada servicio determina su propia compatibilidad con el seguimiento. En general, los servicios aceptan la marca de muestreo superior como una sugerencia mientras aplican sus propios límites de frecuencia.

Correlaciona las métricas y los seguimientos con ejemplares

Puedes correlacionar los datos de métricas con los seguimientos usando ejemplares. Un ejemplo es una solicitud o un intervalo de muestra representativo asociado con una medición de métrica. Por ejemplo, un ejemplar puede contener un vínculo a un seguimiento, que te permite correlacionar tus datos de seguimiento y métrica. Para ver un ejemplo basado en OpenTelemetry, consulta Correlaciona las métricas y los seguimientos con ejemplares.

Es posible que veas ejemplos generados por el sistema en los gráficos del panel que muestran los resultados de la consulta en SQL para los datos de seguimiento. Estos ejemplos vinculan resultados de consultas específicos directamente con los seguimientos. Para obtener más información, consulta Genera y muestra ejemplos de seguimiento.

Configura tu proyecto y plataforma

En esta sección, se describen las APIs y los roles de Identity and Access Management (IAM) necesarios, y se explica cómo configurar las credenciales de autenticación para tu plataforma.

Habilita las APIs

De forma predeterminada,los proyectos de Google Cloud tienen habilitadas la API de Cloud Trace y la API de Telemetry, y no es necesario que realices ninguna acción. Sin embargo, es posible que las restricciones de seguridad que define tu organización hayan inhabilitado una o ambas APIs. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno Google Cloud restringido.

Habilita las APIs de Telemetry y Cloud Trace, si aún no están habilitadas.

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 información para otorgar roles.

Habilitar las API

Asigna roles de IAM

Los roles de IAM requeridos dependen de si estás viendo datos de seguimiento en la consola de Google Cloud o escribiendo datos de seguimiento en tu proyecto:

  • Para obtener los permisos que necesitas para ver los datos de seguimiento con la consola de Google Cloud , pídele a tu administrador que te otorgue el rol de IAM de Usuario de Cloud Trace (roles/cloudtrace.user) en tu proyecto.

  • Para obtener los permisos que necesitas para escribir datos de seguimiento con la API de Cloud Trace, pídele a tu administrador que te otorgue el rol de IAM de Agente de Cloud Trace (roles/cloudtrace.agent) en tu proyecto.

  • Para obtener los permisos que necesitas para escribir datos de seguimiento con la API de Telemetry, pídele a tu administrador que te otorgue el rol de IAM de Escritor de telemetría de Cloud (roles/telemetry.writer) en tu proyecto.

Autenticar

En esta sección, se describe cómo autenticarte cuando tus aplicaciones se ejecutan en Google Cloud y cuando se ejecutan en otro lugar.

Ejecutar en Google Cloud

Cuando tu aplicación se ejecuta en Google Cloud, por lo general, no necesitas proporcionar credenciales de autenticación. Sin embargo, algunas bibliotecas cliente de lenguaje requieren el ID del proyecto, incluso cuando se alojan en Google Cloud.

Verifica que tu plataforma de Google Cloud tenga habilitado el permiso de acceso a la API de Cloud Trace. Para los siguientes parámetros de configuración, los parámetros de configuración predeterminados del permiso de acceso incluyen el permiso de acceso a la API de Cloud Trace:

Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API de Cloud Trace esté habilitado. Por ejemplo, si usas Google Cloud CLI para crear un clúster de GKE y especificas la marca --scopes, asegúrate de que el permiso incluya trace.append. En el siguiente comando, se ilustra cómo configurar la marca --scopes:

gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Ejecuta de forma local y en otros lugares

Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación a la biblioteca cliente. A la cuenta de servicio se le debe otorgar el rol de agente de Cloud Trace (roles/cloudtrace.agent). Para obtener información sobre los roles, consulta Controla el acceso con IAM.

Las bibliotecas cliente deGoogle Cloud usan credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación. Puedes proporcionar estas credenciales de una de las siguientes tres maneras:

  • Ejecuta gcloud auth application-default login

  • Coloca el archivo de claves de la cuenta de servicio en una ruta de acceso predeterminada para tu sistema operativo. A continuación, se indican las rutas de acceso predeterminadas para Windows y Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso a tu cuenta de servicio:

    Linux/macOS

        export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

    Windows

        set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

    PowerShell:

        $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

¿Qué sigue?