Instrumenta para Cloud Trace

En este documento, se proporciona una breve descripción general sobre cómo instrumentar tu aplicación para Cloud Trace. Para obtener instrucciones detalladas sobre cómo configurar Cloud Trace, consulta las páginas de configuración específicas del lenguaje.

Cloud Trace proporciona datos de seguimiento distribuido para tus aplicaciones. Después de instrumentar tu aplicación, puedes inspeccionar los datos de latencia de una sola solicitud y ver la latencia total de una aplicación completa en la consola de Cloud Trace.

Cuándo instrumentar tu aplicación

Cuando no se capturan automáticamente los datos de seguimiento 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 errores. 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 del proveedor y el 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.

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

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

Las muestras de instrumentación que proporcionamos usan OpenTelemetry:

  • Para saber qué servidores MCP remotos de Google Cloud admiten la generación de registros y cómo configurar tu aplicación para indicarles a estos servidores que creen intervalos, consulta Investiga las llamadas a MCP con Trace.

Cuándo crear intervalos

Por lo general, las bibliotecas cliente de Cloud Trace mantienen un contexto de seguimiento global que contiene información sobre el intervalo actual, incluido su ID de seguimiento y si se muestreó el seguimiento. Por lo general, estas bibliotecas crean intervalos en los límites de RPC. Sin embargo, es posible que debas crear intervalos si el algoritmo de creación predeterminado no satisface tus necesidades.

Se puede acceder al intervalo activo actual a través del contexto de seguimiento global, que a veces se incluye en un objeto Tracer. Puedes agregar información relevante para tu aplicación con 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 mayor granularidad. Dado que el contexto es global, las aplicaciones de varios subprocesos que actualizan el contexto deben usar el aislamiento adecuado.

Cuándo proporcionar credenciales de autenticación

En general, no necesitas proporcionar credenciales de autenticación a tu aplicación ni especificar tu ID del proyecto Google Cloud en la aplicación cuando ejecutas en Google Cloud. Para algunos lenguajes, debes especificar el ID del proyecto Google Cloud incluso si lo ejecutas en Google Cloud. Además, si usas el modo Autopilot para Google Kubernetes Engine o si habilitas la federación de identidades para cargas de trabajo para GKE, debes configurar tu aplicación para que use la federación de identidades para cargas de trabajo para GKE.

Si ejecutas tu aplicación fuera de Google Cloud, debes proporcionar credenciales de autenticación. También debes especificar el ID del proyecto deGoogle Cloud en la aplicación.

Para obtener más detalles, ve a las páginas de configuración específicas del lenguaje.

Cómo forzar el seguimiento de una solicitud

A menos que tu aplicación siempre muestree cada intervalo, en general, no es posible forzar que se realice un seguimiento de una solicitud de extremo a extremo, ya que cada componente de una solicitud de extremo a extremo toma su propia decisión de muestreo. Sin embargo, puedes influir en la decisión si agregas una marca sampled al encabezado de seguimiento, con esta marca establecida en true. Este parámetro de 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.

En el caso de los componentes posteriores cuyo código te pertenece, debes determinar si tu lógica de instrumentación respeta la marca sampled. Por ejemplo, cuando usas OpenTelemetry para la instrumentación, puedes usar el muestreador ParentBased para asegurarte de que se respete la marca de muestreo principal.

Google Cloud Los servicios que registran información de seguimiento en Cloud Trace suelen aceptar la marca de muestreo principal como sugerencia. Sin embargo, la mayoría de los servicios también limitan la frecuencia del muestreo. Cada servicio de Google Cloud determina si admite el seguimiento, cómo se utiliza la marca de muestreo principal y el límite de frecuencia del muestreo.

Cómo correlacionar los datos de métricas y de seguimiento

Puedes correlacionar los datos de métricas con valores de distribución con los registros adjuntando ejemplos a los datos de métricas. Si completas los pasos de configuración necesarios, OpenTelemetry, que es la biblioteca de instrumentación recomendada, agregará automáticamente estos ejemplares. Para obtener más información, consulta Correlaciona las métricas y los registros con ejemplares.

Configura tu proyecto y plataforma

  1. Asegúrate de que la API de Cloud Trace esté habilitada.

    De forma predeterminada, Google Cloud los proyectos tienen la API de Cloud Trace habilitada y no es necesario realizar ninguna acción. Sin embargo, es posible que las restricciones de seguridad definidas por tu organización hayan inhabilitado la API. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno Google Cloud restringido.

    Habilita la API de Cloud Trace.

    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 la API

  2. Configura tu plataforma.

    Puedes usar Cloud Trace en Google Cloud y otras plataformas.

    • Google Cloud: Cuando tu aplicación se ejecuta enGoogle Cloud, no necesitas proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud 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. El siguiente comando ilustra cómo establecer la marca --scopes:

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

    • Ejecución local y en otros lugares: Si tu aplicación se ejecuta fuera deGoogle Cloud, debes proporcionar credenciales de autenticación en forma de una cuenta de servicio a la biblioteca cliente. Se le debe otorgar a la cuenta de servicio 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 la cuenta de servicio en una ruta predeterminada para tu sistema operativo. A continuación, se indican 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?

Si deseas obtener información de configuración detallada, muestras y vínculos a GitHub y a otros repositorios de código abierto, ve a la página de configuración para tu idioma.