Descripción general de Cloud Trace

Cloud Trace, un sistema de seguimiento distribuido para Google Cloud, te ayuda a comprender cuánto tiempo le lleva a tu aplicación manejar las solicitudes entrantes de usuarios o de otras aplicaciones y cuánto tiempo lleva completar las operaciones como las llamadas RPC realizadas cuando se manejan las solicitudes. Trace también puede ayudarte cuando desarrollas un servicio, una aplicación de agente o solucionas una falla. Por ejemplo, puede ayudarte a entender cómo se procesan las solicitudes en una arquitectura de microservicios complicada y podría ayudarte a identificar qué registros examinar.

Debido a que Trace recibe datos de latencia de Google Cloud servicios como App Engine y de las aplicaciones que instrumentas, puede ayudarte a responder las siguientes preguntas:

¿Cuánto tiempo tardará mi aplicación en manejar una solicitud determinada?
¿Por qué mi aplicación tarda mucho tiempo en manejar una solicitud?
¿Por qué algunas de mis solicitudes tardan más tiempo que otras?
¿Cuál es la latencia general de las solicitudes de mi aplicación?
¿Aumentó o disminuyó la latencia de mi aplicación en el tiempo?
¿Qué puedo hacer para reducir la latencia de mi aplicación?
¿Cuáles son las dependencias de mi aplicación?

Si tienes curiosidad sobre cómo puedes usar Trace para administrar tus aplicaciones, lee la entrada de blog Solución de problemas de aplicaciones distribuidas: usa seguimientos y registros en conjunto para el análisis de la causa raíz.

Para obtener información sobre cómo crear perfiles de tu aplicación, consulta Cloud Profiler.

Compatibilidad con el entorno

Trace se ejecuta en Linux en los siguientes entornos:

Compute Engine
Google Kubernetes Engine (GKE)
Apigee (versión preliminar pública)
Entorno flexible de App Engine
Entorno estándar de App Engine
Cloud Run
Cloud Service Mesh
Estadísticas de consulta en SQL SQL
Entornos que no son de Google CloudGoogle Cloud

Trace proporciona bibliotecas cliente para instrumentar tu aplicación a fin de capturar información de seguimiento. Para obtener instrucciones de configuración por lenguaje, consulta Instrumenta para Trace.

Configuraciones con seguimiento automático

Algunas configuraciones dan como resultado la captura automática de datos de seguimiento:

Entorno estándar de App Engine

Las aplicaciones de Java 8, Python 2 y PHP 5 no necesitan usar las bibliotecas cliente de Trace. Estos entornos de ejecución envían automáticamente datos de latencia a Trace para solicitudes a los URI de aplicaciones. Las solicitudes incluyen datos de latencia para llamadas RPC de ida y vuelta a servicios de App Engine. Trace funciona con todas las APIs de administrador de App Engine, con la excepción de Cloud SQL.
Cloud Run Functions y Cloud Run

Para las solicitudes HTTP entrantes y salientes, los datos de latencia se envían automáticamente a Trace.

APIs que incorporan datos de seguimiento

Puedes enviar datos de seguimiento a tu proyecto con la API de Telemetry o la API de Cloud Trace. Te recomendamos la API de Telemetry por el siguiente motivo:

La API proporciona compatibilidad con el ecosistema de OpenTelemetry de código abierto y sus límites suelen ser más generosos que los de la API de Cloud Trace, que es una API propietaria Google Cloud
Tus datos de seguimiento se almacenan en un formato que suele ser coherente con los archivos proto definidos por el protocolo OTLP de OpenTelemetry. Algunos campos pueden convertirse de un tipo de datos específico de OpenTelemetry a un tipo de datos JSON antes del almacenamiento. Para obtener más información sobre el formato de almacenamiento, consulta Esquema para datos de seguimiento.
Para la exportación de datos de seguimiento basada en el recopilador, tu instrumentación no depende de un Google Cloud-exportador específico.
Algunas funciones, como Application Monitoring, dependen de la información que solo está disponible cuando envías datos de seguimiento a la API de Telemetry.

Si deseas evitar que tu Google Cloud proyecto almacene datos de seguimiento, inhabilita la API de Cloud Trace. Si inhabilitas la API de Cloud Trace, se producirá lo siguiente:

Google Cloud Los servicios no envían datos de seguimiento a tu proyecto.
Google Cloud responde a las solicitudes enviadas a un extremo de API de Cloud Trace con un código de error.
Google Cloud Observability descarta los datos de seguimiento enviados al extremo de API de Telemetry específico del seguimiento. No inhabilite la API de Telemetry, ya que esa API puede recibir datos de registro, métricas y seguimiento.

Si administras una organización y deseas evitar el uso de Cloud Trace, entonces crea una restricción de políticas de la organización.

Cloud Trace y aplicaciones de agente

Para comprender el comportamiento de tus aplicaciones de agente, configúralas para recopilar instrucciones y respuestas o para generar intervalos cuando llamen a servidores MCP remotos de Google Cloud. Las instrucciones y las respuestas te ayudan a comprender el razonamiento que usa tu aplicación de agente. Los intervalos que registran llamadas a herramientas te ayudan a confirmar la invocación de herramientas, los estados de las llamadas y las latencias de las solicitudes.

En varias muestras de instrumentación, se muestra cómo configurar una aplicación para recopilar instrucciones y respuestas. Estas muestras dependen de OpenTelemetry. Para obtener más información, consulta Cómo instrumentar tus aplicaciones de IA generativa.

Para obtener información sobre qué servidores MCP remotos de Google Cloud admiten la generación de seguimiento y cómo configurar tu aplicación para indicarle a estos servidores que creen intervalos, consulta Investiga las llamadas a MCP con Trace.

Cómo instrumentar tu aplicación

Instrumenta tu aplicación para recopilar información específica que te ayude a comprender su rendimiento y solucionar problemas. Varios frameworks de instrumentación de código abierto recopilan datos de registro, métricas y seguimiento y pueden enviar esos datos a cualquier proveedor, incluido Google Cloud. Para tus aplicaciones de agente, algunos frameworks pueden recopilar tus instrucciones y respuestas o pasar el contexto que permite el seguimiento de algunas llamadas a servidores MCP remotos de 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 APIs específicas de proveedor y producto. o bibliotecas cliente. Para obtener información sobre estos frameworks, consulta Instrumentación y observabilidad y Elige un enfoque de instrumentación.

En las muestras de instrumentación que proporcionamos, se usa OpenTelemetry:

Para obtener muestras que usan una exportación basada en el recopilador, consulta lo siguiente:
- Go
- Java
- Node.js
- Python
Estas muestras envían datos de seguimiento a la API de Telemetry.
Para obtener información sobre cómo usar una exportación directa de datos de seguimiento y enviar esos datos a la API de Telemetry, consulta Migra del exportador de Trace al extremo de OTLP.
Para obtener muestras que te muestran cómo configurar una aplicación de agente para recopilar instrucciones y respuestas, consulta Cómo instrumentar tus aplicaciones de IA generativa.

Para obtener información sobre qué servidores MCP remotos de Google Cloud admiten la generación de seguimiento y cómo configurar tu aplicación para indicarle a estos servidores que creen intervalos, consulta Investiga las llamadas a MCP con Trace.

También puedes usar las bibliotecas cliente de Cloud Trace para instrumentar tu aplicación. Sin embargo, te recomendamos que uses OpenTelemetry. Las bibliotecas de OpenTelemetry son preferibles a las bibliotecas cliente de Trace porque son más simples y exportan datos de seguimiento en formato OTLP, que define OpenTelemetry. Para obtener más información, consulta Bibliotecas cliente de Cloud Trace.

Componentes

Trace consta de un cliente de seguimiento, que recopila seguimientos y los envía a tu Google Cloud proyecto. Luego, puedes usar la Google Cloud consola para ver y analizar los datos que recopila el agente. Para obtener información sobre el modelo de datos, consulta Seguimientos e intervalos.

Seguimiento del cliente

Si hay una biblioteca de OpenTelemetry disponible para tu lenguaje de programación, puedes simplificar el proceso de creación y envío de datos de seguimiento con OpenTelemetry. Además de ser más fácil de usar, OpenTelemetry implementa lotes, lo que puede mejorar el rendimiento.

Si no existe una biblioteca de OpenTelemetry, instrumenta tu código con la importación de la biblioteca del SDK de Trace y la API de Cloud Trace. La API de Cloud Trace envía datos de seguimiento a tu Google Cloud proyecto.

Interfaz de seguimiento

Puedes ver y analizar tus datos de seguimiento casi en tiempo real en la interfaz de Trace.

Para ver y analizar tus datos de intervalos, puedes usar las páginas Explorador de seguimiento y Estadísticas de observabilidad en la Google Cloud consola:

Explorador de seguimiento: Muestra información agregada sobre tus datos de seguimiento y te permite examinar seguimientos individuales en detalle. Los datos de latencia agregados se muestran en un mapa de calor, que puedes explorar con el puntero. Para restringir los datos que se muestran, puedes agregar filtros. Esta página también te permite ver y explorar intervalos y seguimientos individuales:
- Para obtener información sobre cómo ver datos de seguimiento almacenados en varios proyectos, consulta Crea y administra el alcance del seguimiento.
- Para obtener información sobre cómo filtrar y ver tus datos de seguimiento, consulta Busca y explora seguimientos.
Estadísticas de observabilidad: Esta página te permite ejecutar consultas que realizan un análisis agregado de tus intervalos con SQL. Tus consultas en SQL también pueden unir tus datos de seguimiento y registro. Puedes ver los resultados de tu consulta en formato tabular o con gráficos. Si creas un conjunto de datos vinculado, puedes usar BigQuery para analizar tus intervalos. Para obtener más información, consulta Consulta y analiza seguimientos.

Compatibilidad con los Controles del servicio de VPC

Trace es un servicio compatible con los Controles del servicio de VPC. El nombre del servicio de Trace es cloudtrace.googleapis.com. Cualquier restricción de los Controles del servicio de VPC que crees para el servicio de Trace se aplica solo a ese servicio. Esas restricciones no se aplican a ningún otro servicio, incluidos los que son como el telemetry.googleapis.com servicio, que también pueden incorporar datos de seguimiento.

Para obtener más información, consulta lo siguiente:

Cloud Trace y residencia de datos

Si usas Assured Workloads porque tienes requisitos de residencia de datos o nivel de impacto 4 (IL4), no uses la API de Cloud Trace para enviar intervalos de seguimiento.