Instrumenta para Cloud Trace

Puedes instrumentar tus aplicaciones para Cloud Trace para capturar datos de seguimiento distribuido, examinar la latencia de solicitudes individuales y ver la latencia total 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 para lenguajes de programación específicos, consulta las páginas de configuración específicas del lenguaje.

Cuándo instrumentar tu aplicación

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

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

Para instrumentar tu aplicación, te recomendamos que uses un framework de instrumentación con proveedor neutro y que sea de código abierto, como OpenTelemetry, en lugar de las APIs específicas de proveedor y producto. o bibliotecas cliente. 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:

Ejemplos de instrumentación

Las muestras de instrumentación que proporcionamos usan OpenTelemetry:

  • Para obtener muestras que usan una exportación basada en recopiladores, consulta lo siguiente:

    Estas muestras envían datos de métricas y seguimientos que siguen el formato del protocolo OpenTelemetry (OTLP) a tu proyecto con la API de Telemetry. Las muestras usan un Google Cloud exportador para los datos de registro.

  • Para obtener información sobre cómo 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 obtener muestras que te muestran cómo configurar una aplicación de agente 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 porque 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 una granularidad más precisa.

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 el 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 subprocesos múltiples propaguen el contexto en todos los subprocesos para mantener datos de seguimiento precisos.

Forzar el muestreo de seguimientos

No puedes forzar el muestreo de intervalos porque cada componente en la ruta de acceso de la solicitud toma una decisión de muestreo independiente. Sin embargo, puedes influir en los componentes descendentes si configuras la sampled marca en el encabezado de seguimiento como true. Esta configuración es una sugerencia para que los componentes secundarios muestren 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 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 servicios: 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 de muestreo.

Correlaciona las métricas y los seguimientos con ejemplares

Puedes correlacionar datos de métricas con seguimientos mediante ejemplares. Un ejemplar es una solicitud o un intervalo de muestra representativa asociado con una medición de métricas. 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 ejemplares generados por el sistema en los gráficos del panel que muestran los resultados de las consultas de SQL para los datos de seguimiento. Estos ejemplares vinculan resultados de consultas específicos directamente a los seguimientos. Para obtener más información, consulta Genera y muestra ejemplares 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, Google Cloud los proyectos tienen habilitadas la API de Cloud Trace y la API de Telemetry y no es necesario realizar 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 Google Cloud entorno restringido.

Habilita las APIs de Telemetry y Cloud Trace.

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 obtener este permiso 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 necesarios dependen de si ves datos de seguimiento en la Google Cloud consola o escribes datos de seguimiento en tu proyecto:

  • Para obtener los permisos que necesitas para ver los datos de seguimiento con la Google Cloud consola, 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 Cloud Telemetry (roles/telemetry.writer) en tu proyecto.

Autenticar

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

Ejecuta pruebas 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. Para las siguientes opciones de configuración, la configuración predeterminada del permiso 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 Google Cloud, debes proporcionar credenciales de autenticación a la biblioteca cliente. La cuenta de servicio debe tener 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 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 enumeran las rutas de acceso 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?