Instrumento 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 recopilar estos datos.

Puedes instrumentar tu aplicación para que recopile información específica de la aplicación. Varios sistemas de código abierto los frameworks de instrumentación te permiten recopilar métricas, los seguimientos de tu aplicación y enviarlos 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 información sobre cómo instrumentar tus aplicaciones con de instrumentación neutrales para el proveedor, consulta Instrumentación y observabilidad.

Cómo instrumentar aplicaciones

Si quieres instrumentar tus aplicaciones para recopilar datos de seguimiento, puedes hacer lo siguiente: cualquiera de los siguientes:

Cuándo crear intervalos

Por lo general, las bibliotecas cliente de Cloud Trace mantienen un seguimiento global contexto que contiene información sobre el intervalo actual, incluido su ID de seguimiento y si se realizó el muestreo del seguimiento. Por lo general, estas bibliotecas crean intervalos en RPC límites. Sin embargo, podrías necesitar crear intervalos si la configuración el algoritmo no es suficiente para tus necesidades.

El contexto de seguimiento global puede acceder al intervalo activo actual, que es a veces se unen a un objeto Tracer. Puedes agregar información relevante para tu aplicación mediante el uso de anotaciones y etiquetas personalizadas a intervalos existentes, o puedes crear nuevos intervalos secundarios con sus propias anotaciones y etiquetas para hacer un seguimiento del comportamiento de la aplicación con mayor nivel de detalle. Porque el contexto son aplicaciones globales de varios subprocesos que actualizan el contexto usan un aislamiento adecuado.

Cuándo proporcionar credenciales de autenticación

Por lo general, no necesitas proporcionar credenciales de autenticación para tu aplicación o especificar el ID del proyecto de Google Cloud en la cuando los ejecutes 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 Workload Identity, Configurar tu aplicación para usar Workload Identity.

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 haga un muestreo de cada intervalo, por lo general, no es posible forzar el seguimiento de una solicitud de extremo a extremo. ya que cada componente de una solicitud de extremo a extremo tiene su propio decisión de muestra. Sin embargo, puedes influir en el agregando una marca sampled al encabezado de seguimiento. con esta marca establecida en true. Este parámetro de configuración es una sugerencia para los componentes secundarios para muestrear la solicitud. Para obtener más información sobre los encabezados de seguimiento, consulta Protocolos para la propagación de contextos.

Para los componentes downstream cuyo código posees, debes determinar si tu lógica de instrumentación respeta la marca sampled. Por ejemplo, cuando usas OpenTelemetry para la instrumentación, puedes usar ParentBased sampler para garantizar que se respete la marca de muestra superior.

Servicios de Google Cloud que registran la información de seguimiento en Cloud Trace generalmente aceptan la marca de muestreo principal como pista; Sin embargo, la mayoría servicios también usan el muestreo con límite de frecuencia. Cada servicio de Google Cloud determina si admite el seguimiento, cómo el muestreo superior y el límite de frecuencia de muestreo.

Cómo correlacionar datos de métricas y seguimientos

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

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, las restricciones de seguridad definidas podría haber inhabilitado la API. Para solucionar problemas información, consulta Desarrolla aplicaciones en un entorno limitado de Google Cloud.

    Habilita la API de Cloud Trace.

    Habilita la API

  2. Configura tu plataforma.

    Puedes usar Cloud Trace en Google Cloud y otras plataformas.

    • Google Cloud: Cuando tu aplicación se ejecuta en a Google Cloud, no necesitas proporcionar credenciales de autenticación en forma de cuenta de servicio a la biblioteca cliente. Sin embargo, se debe asegurarte de que tu plataforma de Google Cloud tenga los Permiso de acceso a la API de Cloud Trace habilitado.

      Para los siguientes parámetros de configuración, la configuración predeterminada del alcance 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 debe estar habilitado. Por ejemplo, si usas Google Cloud CLI para crear una clúster de GKE y, si especificas la marca --scopes, luego, asegúrate de que el alcance incluya trace.append. El siguiente comando se muestra la configuración de la marca --scopes:

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

    • Ejecución local y en otro lugar: si la aplicación se ejecuta fuera de en Google Cloud, debes proporcionar credenciales de autenticación el formulario de una cuenta de servicio a la biblioteca cliente. La cuenta de servicio debe tener el agente de Cloud Trace (roles/cloudtrace.agent). Para obtener información sobre los roles, consulta Controla el acceso con la 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 en una de de 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 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 como 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"

¿Qué sigue?

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