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 los datos de seguimiento no se capturan automáticamente, debes instrumentar tu aplicación para recopilarlos.

Puedes instrumentar tu aplicación para que recopile información específica de la aplicación. Varios frameworks de instrumentación de código abierto te permiten recopilar métricas, registros y seguimientos desde tu aplicación y enviar esos datos a cualquier proveedor, incluido 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 API específicas de proveedor y producto. o bibliotecas cliente.

Para obtener más información sobre la instrumentación de tus aplicaciones con marcos de instrumentación independientes del proveedor, consulta Instrumentación y observabilidad.

Cómo instrumentar aplicaciones

Para instrumentar tus aplicaciones y recopilar datos de seguimiento, puedes hacer lo siguiente:

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 toma una muestra del seguimiento. Por lo general, estas bibliotecas crean tramos en los límites de RPC. Sin embargo, es posible que debas crear tramos si el algoritmo de creación predeterminado no es suficiente para tus necesidades.

El contexto de seguimiento global puede acceder al intervalo activo actual, que a veces se une en un objeto Tracer. Puedes agregar información relevante para tu aplicación usando anotaciones y etiquetas personalizadas en los intervalos existentes, o bien puedes crear intervalos secundarios nuevos con sus propias anotaciones y etiquetas para rastrear el comportamiento de la aplicación con mayor nivel de detalle. Debido a 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

Por lo general, no necesitas proporcionar credenciales de autenticación a tu aplicación ni especificar tu ID del proyecto de Google Cloud en la aplicación cuando ejecutas en Google Cloud. Para algunos lenguajes, debes especificar el ID del proyecto de 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 usar la federación de identidades para cargas de trabajo para GKE.

Si lo ejecutas fuera de Google Cloud, debes proporcionar credenciales de autenticación para tu aplicación. También debes especificar el ID de tu proyecto de Google 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 tome muestras de 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 al encabezado de seguimiento una marca sampled, con esta marca establecida en true. Este parámetro de configuración es una sugerencia para los componentes secundarios para que tomen una muestra de la solicitud. Para obtener más información sobre los encabezados de seguimiento, consulta Protocolos para la propagación de contexto.

En el caso de los componentes descendentes cuyo código es de tu propiedad, 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 sampler ParentBased para asegurarte de que se respete la marca de muestreo superior.

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

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

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

Configura tu proyecto y plataforma

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

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

    Enable the Cloud Trace API.

    Enable the API

  2. Configura tu plataforma.

    Puedes usar Cloud Trace en Google Cloud y otras plataformas.

    • Google Cloud: Cuando tu aplicación se ejecuta en Google Cloud, no necesitas proporcionar credenciales de autenticación en forma 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 niveles de acceso personalizados, debes asegurarte de que el nivel 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

    • Ejecución local y en otros lugares: Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en forma de una cuenta de servicio a la biblioteca cliente. Se 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.

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

      • Ejecuta gcloud auth application-default login

      • Coloca la cuenta de servicio en una ruta de acceso predeterminada para tu sistema operativo. A continuación, se muestran 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?

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.