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 que recopile estos datos.
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 información sobre cómo instrumentar tus aplicaciones con frameworks de instrumentación neutros para proveedores, consulta Instrumentación y observabilidad.
Cómo instrumentar aplicaciones
Si deseas obtener recomendaciones sobre cómo instrumentar tus aplicaciones para recopilar registros, métricas y seguimientos, consulta Elige un enfoque de instrumentación.
Para instrumentar tus aplicaciones con el objetivo de recopilar datos de seguimiento, puedes realizar cualquiera de las siguientes acciones:
Puedes usar OpenTelemetry y el exportador de Cloud Trace asociado para los siguientes lenguajes de programación:
SDK de OpenTelemetry Ejemplo SDK de C++ Ejemplo de C++ SDK de Go Ejemplo de Go SDK de Java Ejemplo de Java SDK de Node.js Ejemplo de Node.js Python SDK Ejemplo de Python SDK de Ruby Consulta la documentación de OpenTelemetry. 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 la descripción general del agente de operaciones.
Puedes usar las bibliotecas cliente o llamar directamente a la API de Cloud Trace para enviar datos de seguimiento a Cloud Trace. Sin embargo, te recomendamos que uses OpenTelemetry cuando esa biblioteca admita tu lenguaje.
Puedes configurar un servidor Zipkin con el objetivo de recibir seguimientos de los clientes de Zipkin y reenviar esos seguimientos a Cloud Trace para analizarlos. Para obtener información sobre este enfoque, consulta Usa Cloud Trace con Zipkin.
Puedes configurar las aplicaciones de Spring Boot para que reenvíen los datos de seguimiento que recopila a Cloud Trace. Si deseas obtener información sobre este procedimiento, consulta Spring Cloud para Google Cloud: Cloud 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 muestra 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 es suficiente para tus necesidades.
Se puede acceder al intervalo activo actual mediante el contexto de seguimiento global, que a veces se une a un objeto Tracer. Puedes agregar información relevante para tu aplicación con anotaciones y etiquetas personalizadas a los intervalos existentes, o puedes crear nuevos intervalos secundarios con sus propias anotaciones y etiquetas para realizar un seguimiento del comportamiento de la aplicación con un nivel de detalle más exacto. Debido a que 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 necesitas proporcionar credenciales de autenticación a tu aplicación ni especificar el ID del proyecto de Google Cloud en tu 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 Workload Identity, debes configurar la aplicación para que use 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 muestree cada intervalo, por lo general, no es posible hacer que se realice el 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
. Esta configuración es una sugerencia para los componentes secundarios para que realicen una muestra de la solicitud.
Para obtener más información sobre los encabezados de seguimiento, consulta Protocolos para la propagación de contexto.
Para los componentes downstream 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 utilizar el muestreo ParentBased
para asegurarte de que se respete la marca de muestra superior.
Los servicios de Google Cloud que registran la información de seguimiento en Cloud Trace suelen aceptar la marca de muestreo superior como sugerencia. Sin embargo, la mayoría de los servicios también usan el muestreo con límite de frecuencia. Cada servicio de Google Cloud determina si admite el seguimiento, cómo se utiliza la marca de muestreo superior y el límite de frecuencia de muestreo.
Habilita la API de Cloud Trace
Para usar Cloud Trace, tu proyecto de Google Cloud debe tener la API de Cloud Trace habilitada. Esta configuración permite que tu proyecto de Google Cloud reciba datos de seguimiento de fuentes autenticadas. 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 debas habilitar la API de Cloud Trace si modificaste los permisos de acceso de tu proyecto de Google Cloud.
Para habilitar la API de Cloud Trace, sigue estos pasos:
-
En el panel de navegación de la consola de Google Cloud, selecciona APIs y servicios, haz clic en Habilitar APIs y servicios y, luego, habilita la API de Cloud Trace:
Si aparece API habilitada, la API ya está habilitada. De lo contrario, haz clic en el botón Habilitar.
¿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:
Ejemplos de OpenTelemetry:
Ejemplos de bibliotecas cliente: