Instrumenta para Cloud Trace

Puedes instrumentar tus aplicaciones para Cloud Trace y capturar datos de seguimiento distribuido, examinar la latencia de solicitudes individuales y ver la latencia agregada en todos 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 específicas de cada lenguaje.

Cuándo instrumentar tu aplicación

Cuando no se capturan automáticamente los datos de registro para validar el rendimiento o solucionar problemas, instrumenta tu aplicación.

Instrumenta tu aplicación para recopilar información específica que te ayude a comprender su rendimiento y solucionar fallas. Existen varios frameworks de instrumentación de código abierto que recopilan datos de registros, métricas y seguimientos, y pueden enviar esos datos a cualquier proveedor, incluido Google Cloud. En el caso de tus aplicaciones basadas en agentes, algunos frameworks pueden recopilar tus instrucciones y respuestas, o bien 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 con proveedor neutro, como OpenTelemetry, en lugar de las APIs o bibliotecas cliente específicas de proveedor y producto. Para obtener información sobre estos frameworks, consulta Instrumentación y observabilidad 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:

  • Para ver ejemplos que usan una exportación basada en el recopilador, consulta lo siguiente:

    Estos ejemplos envían datos de métricas y de seguimiento que siguen el formato del protocolo de OpenTelemetry (OTLP) a tu proyecto a través de la API de Telemetry. En los ejemplos, se usa un exportador de Google Cloud para los datos de registro.

  • Si deseas obtener información para usar una exportación directa de datos de seguimiento y enviar esos datos a la API de Telemetry, consulta Migra del exportador de Trace al extremo de OTLP.

  • Para ver ejemplos que te muestran cómo configurar una aplicación basada en agentes para recopilar instrucciones y respuestas, consulta Cómo instrumentar tus aplicaciones de IA generativa.

Cómo crear 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 bien puedes crear intervalos secundarios nuevos con sus propias anotaciones y etiquetas para hacer un seguimiento del comportamiento de la aplicación con una granularidad más fina.

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

Forzar el muestreo de registros

No puedes forzar que se muestreen los tramos, ya que cada componente de la ruta de solicitud toma una decisión de muestreo independiente. Sin embargo, puedes influir en los componentes posteriores configurando la marca sampled en el encabezado de seguimiento como true. Este parámetro de configuración es una sugerencia para que los componentes secundarios muestren una muestra de la solicitud. Para obtener más información sobre los encabezados de seguimiento, consulta Protocolos para la propagación del contexto.

  • Tus aplicaciones: Configuras cómo la lógica de la 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.

  • Google Cloud services: Cada servicio determina su propia compatibilidad con el registro. En general, los servicios aceptan la marca de muestreo principal como una sugerencia y, al mismo tiempo, aplican sus propios límites de frecuencia de muestreo.

Correlaciona métricas y registros de seguimiento con ejemplares

Puedes correlacionar los datos de métricas con los registros de seguimiento usando ejemplares. Un ejemplar es una solicitud o un intervalo de muestra representativos asociados con una medición de métricas. Por ejemplo, un ejemplar puede contener un vínculo a un seguimiento, lo 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 las consultas en SQL para los datos de seguimiento. Estos ejemplos vinculan resultados de búsquedas específicos directamente con los registros. Para obtener más información, consulta Cómo generar y mostrar 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 Google Cloud tienen habilitadas la API de Cloud Trace y la API de Telemetry, por lo que no es necesario que realices ninguna acción. Sin embargo, es posible que las restricciones de seguridad definidas por 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 alguna aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar 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 obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

Asigna roles de IAM

Los roles de IAM requeridos dependen de si ves los datos de seguimiento en la consola de Google Cloud o si escribes 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 autenticarse cuando las aplicaciones se ejecutan enGoogle 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 Google Cloud plataforma tenga habilitado el permiso de acceso a la API de Cloud Trace. En las siguientes configuraciones, la configuración predeterminada de los permisos de acceso incluye 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 alcance incluya trace.append. En el siguiente comando, se muestra 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.

Google Cloud Las bibliotecas cliente usan las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación. Puedes proporcionar estas credenciales de 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 enumeran las rutas predeterminadas para Windows y Linux:

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

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

  • Configura 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?