Instrumentar para Cloud Trace

En este documento se ofrece 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 de cada lenguaje.

Cloud Trace proporciona datos de análisis de trazas distribuidos de tus aplicaciones. Después de instrumentar tu aplicación, puedes inspeccionar los datos de latencia de una sola solicitud y ver la latencia agregada de toda la aplicación en la consola de Cloud Trace.

Cuándo instrumentar tu aplicación

Cuando los datos de la traza no se capturan automáticamente, debe instrumentar su aplicación para recogerlos.

Puede instrumentar su aplicación para que recoja información específica de la aplicación. Hay varios frameworks de instrumentación de código abierto que te permiten recoger métricas, registros y trazas de tu aplicación, así como enviar esos datos a cualquier proveedor, incluido Google Cloud. Para instrumentar tu aplicación, te recomendamos que uses un framework de instrumentación de código abierto independiente del proveedor, como OpenTelemetry, en lugar de APIs o bibliotecas de cliente específicas de un proveedor o un producto.

Para obtener información sobre cómo instrumentar tus aplicaciones mediante frameworks de instrumentación independientes del proveedor, consulta Instrumentación y observabilidad.

Cómo instrumentar aplicaciones

Para instrumentar tus aplicaciones y recoger datos de traza, puedes hacer lo siguiente:

Cuándo crear intervalos

Las bibliotecas de cliente de Cloud Trace suelen mantener un contexto de traza global que contiene información sobre el intervalo actual, incluido su ID de traza y si se ha muestreado la traza. Estas bibliotecas suelen crear intervalos en los límites de RPC. Sin embargo, es posible que tengas que crear intervalos si el algoritmo de creación predeterminado no es suficiente para tus necesidades.

Se puede acceder al intervalo activo actual mediante el contexto de seguimiento global, que a veces se incluye en un objeto Tracer. Puedes añadir información relevante para tu aplicación mediante anotaciones y etiquetas personalizadas a los intervalos que ya tengas, o bien crear nuevos intervalos secundarios con sus propias anotaciones y etiquetas para monitorizar el comportamiento de la aplicación con mayor granularidad. Como el contexto es global, las aplicaciones multiproceso que actualizan el contexto deben usar el aislamiento adecuado.

Cuándo proporcionar credenciales de autenticación

Por lo general, no es necesario que proporciones credenciales de autenticación a tu aplicación ni que especifiques tu ID de proyecto en ella cuando se ejecute en Google Cloud. Google Cloud En algunos idiomas, debes especificar el ID de tu proyecto aunque estés usando Google Cloud. Google Cloud Además, si usas el modo Autopilot de Google Kubernetes Engine o habilitas Workload Identity Federation para GKE, debes configurar tu aplicación para que use Workload Identity Federation para GKE.

Si se ejecuta fuera de Google Cloud, debe proporcionar credenciales de autenticación a su aplicación. También debes especificar elGoogle Cloud ID de proyecto en tu aplicación.

Para obtener más información, consulta las páginas de configuración específicas de cada idioma.

Cómo forzar el seguimiento de una solicitud

A menos que tu aplicación siempre muestree cada intervalo, por lo general, no es posible forzar que se trace una solicitud de principio a fin, ya que cada componente de una solicitud de principio a fin toma su propia decisión de muestreo. Sin embargo, puede influir en la decisión añadiendo al encabezado de la traza una marca sampled con el valor true. Este ajuste es una pista 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.

En el caso de los componentes posteriores cuyo código sea de tu propiedad, debes determinar si tu lógica de instrumentación respeta la marca sampled. Por ejemplo, al usar OpenTelemetry para la instrumentación, puede usar el ParentBased muestreador para asegurarse de que se respeta la marca de muestreo principal.

LosGoogle Cloud 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 de muestreo. Cada Google Cloud servicio 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 datos de métricas y de trazas

Puedes correlacionar los datos de métricas con valores de distribución con los rastreos adjuntando ejemplares a los puntos de datos de las métricas. Si completas los pasos de configuración necesarios, OpenTelemetry, que es la biblioteca de instrumentación recomendada, añade automáticamente estos ejemplares. Para obtener más información, consulta el artículo sobre cómo correlacionar métricas y trazas mediante ejemplares.

Configurar el proyecto y la plataforma

  1. Comprueba que la API Cloud Trace esté habilitada.

    De forma predeterminada, Google Cloud los proyectos tienen habilitada la API Cloud Trace y no es necesario que hagas nada. Sin embargo, es posible que las restricciones de seguridad definidas por tu organización hayan inhabilitado la API. Para obtener información sobre cómo solucionar problemas, consulta Desarrollar aplicaciones en un entorno limitado Google Cloud .

    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 es necesario que proporciones credenciales de autenticación en forma de cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma tenga habilitado el Google Cloud ámbito de acceso de la API Cloud Trace.

      En las siguientes configuraciones, los ajustes de access-scope predeterminados 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 de la API Cloud Trace esté habilitado. Por ejemplo, si usas la CLI de Google Cloud para crear un clúster de GKE y especificas la marca --scopes, asegúrate de que el permiso incluya trace.append. El siguiente comando muestra cómo definir 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 cuenta de servicio a la biblioteca de cliente. Se debe conceder a la cuenta de servicio el rol de agente de Cloud Trace (roles/cloudtrace.agent). Para obtener información sobre los roles, consulta Controlar el acceso con gestión de identidades y accesos.

      Las bibliotecas de clienteGoogle Cloud usan las credenciales de aplicación predeterminadas (ADC) para encontrar las credenciales de tu aplicación. Puedes proporcionar estas credenciales de tres formas:

      • Ejecutar gcloud auth application-default login

      • Coloca la cuenta de servicio en una ruta predeterminada de 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

      • Asigna a la variable de entorno GOOGLE_APPLICATION_CREDENTIALS la ruta 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"

Siguientes pasos

Para obtener información detallada sobre la configuración, ejemplos y enlaces a GitHub y otros repositorios de código abierto, ve a la página de configuración de tu idioma.