Resumen

En esta página, se proporciona una breve descripción general de 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 los datos de latencia de una sola solicitud y ver la latencia agregada de una aplicación completa en Cloud Trace Console.

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

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 que uses OpenTelemetry o OpenCensus para instrumentar tu aplicación. Estos son paquetes de seguimiento de código abierto. OpenTelemetry está en desarrollo activamente y es el paquete preferido.

Instrumenta el seguimiento para aplicaciones

Existen tres maneras de implementar el seguimiento de tus aplicaciones:

  • Usa OpenTelemetry y la biblioteca cliente de Cloud Trace asociada. Esta es la manera 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.

En la siguiente tabla, se muestra la biblioteca cliente recomendada para cada lenguaje de programación:

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

Cuándo crear intervalos

Las bibliotecas cliente de Cloud Trace suelen mantener un contexto de seguimiento global que conserva información sobre el intervalo actual, incluido su ID de seguimiento y si la muestra está muestreada. Estas bibliotecas suelen crear intervalos en 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 en un objeto Trace. Puedes agregar información relevante para tu aplicación con anotaciones y etiquetas personalizadas en intervalos existentes, o puedes crear nuevos intervalos secundarios con sus propias anotaciones y etiquetas a fin de rastrear el comportamiento de la aplicación con un nivel de detalle más preciso. Debido a que el contexto es global, las aplicaciones de múltiples subprocesos que actualizan el contexto deben usar el aislamiento adecuado.

Cuándo proporcionar credenciales de autenticación

No necesitas proporcionar credenciales de autenticación a tu aplicación o especificar el ID de tu proyecto de Google Cloud en tu aplicación cuando 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.

Cómo forzar el seguimiento de una solicitud

Cloud Trace no realiza un muestreo de cada solicitud. Por ejemplo, si usas Java y OpenCensus, solo se rastrea 1 solicitud de cada 10,000. Si usas App Engine, tus solicitudes se muestren a una tasa 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 de OpenCensus de Java, admiten la configuración de la tasa de muestreo.

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:

"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 firmado). Debe generarse de forma aleatoria y única en tu 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:
  105445aa7843bc8bf206b12000100000/1;o=1"

Cómo crear archivos de Cloud Trace

OpenCensus crea archivos de Cloud Trace cuando escribe datos de series temporales para los servicios de gRPC. Para ver estos ejemplos, crea un gráfico y usa la barra de herramientas del gráfico para habilitar su pantalla. Para obtener más información, consulta Usa la barra de herramientas del gráfico.

Si deseas escribir tus propias métricas personalizadas, consulta los siguientes recursos:

Si escribes métricas personalizadas, puedes crear ejecutores. En el siguiente fragmento de código de Go, se ilustra la creación de un único Point en una serie temporal. El primer elemento es el intervalo de tiempo, etiquetado por Interval, y el segundo es el valor. El valor es una instancia de un objeto TypedValue y debe resolverse en un distributionValue.

import (
	"time"

	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

func createDataPointWithExemplar() *monitoringpb.Point {
	end := time.Now().Unix()
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					&distributionpb.Distribution_Exemplar{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
					&distributionpb.Distribution_Exemplar{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint
}

Configura un proyecto de Google Cloud

Para usar Cloud Trace, tu proyecto de Google Cloud debe tener habilitada la API de Cloud Trace. 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 necesitas realizar ninguna acción. Si modificaste los permisos de acceso de tu proyecto de Google Cloud y deseas verificar la 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.

¿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: