Resumen

En esta página, 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, ve a las páginas de configuración específicas del lenguaje.

Cloud Trace proporciona datos de seguimiento distribuidos para tus aplicaciones. Después de instrumentar tu aplicación, puedes inspeccionar datos de latencia para una sola solicitud y ver la latencia agregada de una aplicación completa en la consola de Cloud Trace.

Cloud Trace recomienda usar OpenTelemetry. OpenTelemetry es un producto de código abierto de la fusión entre OpenCensus y OpenTracing.

Instrumenta el seguimiento para aplicaciones

Existen tres formas de implementar el seguimiento para tus aplicaciones:

  • Usa OpenTelemetry y la biblioteca cliente de Cloud Trace asociada. Esta es la forma recomendada de instrumentar tus aplicaciones.

  • Usa OpenCensus si una biblioteca cliente de OpenTelemetry no está disponible para tu idioma.

  • Usa la API de Cloud Trace y escribe métodos personalizados para enviar datos de seguimiento a Cloud Trace.

OpenTelemetry aún no está disponible para todos los idiomas. Consulta la siguiente tabla para ver la biblioteca cliente recomendada para el lenguaje que estás usando:

Idioma Biblioteca cliente recomendada
Python OpenCensus
Java OpenCensus
Node.js OpenTelemetry
Go OpenTelemetry
C# .NET Cloud Trace API
PHP OpenCensus
Ruby Cloud Trace API

Cuándo instrumentar tu aplicación

Para que tu aplicación envíe seguimientos a Cloud Trace, debe estar instrumentada. Puedes instrumentar tu código con las bibliotecas cliente de Google. Sin embargo, se recomienda usar OpenTelemetry o bien OpenCensus para instrumentar tu aplicación. Estos son paquetes de seguimiento de código abierto. OpenTelemetry está en desarrollo de manera activa y es el paquete preferido.

Crea 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 muestra. Estas bibliotecas suelen crear 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.

El contexto activo actual puede acceder al intervalo activo actual, que a veces se une en un objeto de Tracer. Puedes agregar información relevante para tu aplicación mediante el uso de anotaciones y etiquetas personalizadas en intervalos existentes, o puedes crear nuevos intervalos secundarios con sus propias anotaciones y etiquetas para rastrear el comportamiento de la aplicación con mayor detalle. Debido a que el contexto es global, las aplicaciones de varios subprocesos que actualizan el contexto deben usar el aislamiento adecuado.

Autenticación

No necesitas proporcionar credenciales de autenticación a tu aplicación ni especificar tu ID del proyecto de Google Cloud en tu aplicación cuando la ejecutas en Google Cloud. Para algunos lenguajes, debes especificar tu ID del proyecto de Google Cloud, incluso si ejecutas en Google Cloud.

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.

Configura un proyecto de Google Cloud

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 habilitada la API de Cloud Trace y no debes realizar ninguna acción. Si modificaste los niveles de acceso de tu proyecto de Google Cloud y deseas verificar tu configuración, haz lo siguiente:

  1. En Google Cloud Console, ve a API y servicios:

    Ir a API y servicios

  2. Haz clic en Habilitar API y servicios.

  3. En la barra de búsqueda, ingresa API de Trace.

  4. Si se muestra API habilitada, esta API ya está habilitada y no necesitas hacer nada. De lo contrario, haz clic en Habilitar.

Tasa de muestreo

Cloud Trace no realiza un muestreo de cada solicitud. Por ejemplo, si usas Java y OpenCensus, solo se realiza el seguimiento de una solicitud de cada 10,000. Si usas App Engine, las solicitudes se muestrean a una velocidad de 0.1 solicitudes por segundo para cada instancia de App Engine. Si usas la API de Cloud Trace, puedes configurar las tarifas de los clientes. Algunos paquetes, como el paquete de Java OpenCensus, admiten la configuración de la tasa de muestreo.

Fuerza el seguimiento de una solicitud

Para forzar el seguimiento de una solicitud específica, agrega un encabezado X-Cloud-Trace-Context a la solicitud. La especificación del encabezado es la siguiente:

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

Aquí:

  • TRACE_ID es un valor hexadecimal de 32 caracteres que representa un número de 128 bits. Debería ser único entre las solicitudes, a menos que desees que las solicitudes se agrupen intencionalmente. Puedes usar los UUID.

  • SPAN_ID es la representación decimal del ID de intervalo (no asignado). Debería ser 0 para el primer intervalo en el seguimiento. Para las solicitudes posteriores, configura SPAN_ID como el ID del intervalo de la solicitud superior. Consulta la descripción de TraceSpan (REST, RPC) para obtener más información sobre los seguimientos anidados.

  • TRACE_TRUE debe ser 1 para realizar el seguimiento de esta solicitud. Especifica 0 para que no se realice el seguimiento de la solicitud.

Por ejemplo, para forzar el seguimiento con curl, haz lo siguiente:

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b120001000/0;o=1"

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: