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 frameworks de instrumentación de código abierto te permiten recopilar métricas, registros y seguimientos de 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 neutrales al proveedor, consulta Instrumentación y observabilidad.
Cómo instrumentar aplicaciones
Si quieres instrumentar tus aplicaciones para que recopilen 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 Go Ejemplo de seguimiento y métricas para Go SDK de Java Ejemplo de seguimiento y métricas para Java SDK de Node.js Ejemplo de seguimiento y métricas para Node.js Python SDK Ejemplo de seguimiento y métricas para Python SDK de C++ Ejemplo de Trace para C++ 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 de 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 tu lenguaje sea compatible con esa biblioteca.
Puedes configurar un servidor Zipkin para recibir seguimientos de los clientes de Zipkin y, luego, reenviar esos seguimientos a Cloud Trace para analizarlos. Para obtener información sobre este enfoque, consulta Cómo usar Cloud Trace con Zipkin.
Puedes configurar las aplicaciones de Spring Boot para reenviar 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 el seguimiento se muestrea o no. 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 con el contexto de seguimiento global, que a veces está unido a un objeto Tracer. Puedes agregar información relevante para tu aplicación mediante el uso de anotaciones y etiquetas personalizadas para los 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. 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
Por lo general, no es necesario que proporciones credenciales de autenticación a la aplicación ni que especifiques el ID del proyecto de Google Cloud en la aplicación cuando se ejecuta 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 tu 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 muestrea cada intervalo, en general, no es posible forzar el seguimiento de una solicitud de extremo a extremo porque cada componente 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
. Esta configuración es una sugerencia para que los componentes secundarios hagan un muestreo de la solicitud.
Si quieres obtener más información sobre los encabezados de seguimiento, consulta Protocolos para la propagación de contextos.
Para los componentes descendentes 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 el muestreo ParentBased
para asegurarte de que se respete la marca muestreada superior.
Por lo general, los servicios de Google Cloud que registran la información de seguimiento en Cloud Trace aceptan la marca de muestreo superior como sugerencia. Sin embargo, la mayoría de los servicios también incluyen el muestreo de límite de frecuencia. 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 del muestreo.
Configura tu proyecto y plataforma
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 por tu organización pueden haber inhabilitado la API. Para obtener información sobre la solución de problemas, consulta Desarrolla aplicaciones en un entorno limitado de Google Cloud.
Habilita la API de Cloud Trace.
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 cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que Google Cloud Platform tenga habilitado el permiso de acceso a la API de Cloud Trace.
Para los siguientes parámetros 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 permiso incluyatrace.append
. El siguiente comando ilustra 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 otro lugar: 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. La cuenta de servicio debe tener la función de agente de Cloud Trace (
roles/cloudtrace.agent
). Para obtener información sobre las funciones, consulta Cómo controlar 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 de una de estas tres maneras:
Ejecución
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
Establece la variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
en la ruta de acceso a la 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, muestras y vínculos a GitHub y otros repositorios de código abierto, ve a la página de configuración de tu lenguaje.
Ejemplos de OpenTelemetry:
Ejemplos de bibliotecas cliente: