Ayúdanos a definir el futuro de las operaciones de software y haz oír tu voz con la encuesta del estado de DevOps 2021.

Resumen

En esta página, se proporciona una descripción general breve 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 de cada 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 la consola de Cloud Trace.

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, se debe instrumentar. 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 se encuentra activamente en desarrollo y es el paquete preferido.

Instrumenta el seguimiento para aplicaciones

Existen tres maneras de implementar el seguimiento para sus 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.

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

Idioma Biblioteca cliente recomendada
Python OpenTelemetry
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 contiene información sobre el intervalo actual, incluido el ID del seguimiento y si se muestrea el seguimiento. Estas bibliotecas generalmente crean 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 Tracer. Puedes agregar información relevante para tu aplicación mediante anotaciones y etiquetas personalizadas en intervalos existentes, o puedes crear intervalos secundarios nuevos con sus propias anotaciones y etiquetas para hacer un seguimiento del comportamiento de la aplicación con un nivel de detalle más detallado. Debido a que el contexto es global, las aplicaciones de varios subprocesos que actualizan el contexto deben usar el aislamiento apropiado.

Cuándo proporcionar credenciales de autenticación

No necesitas proporcionar credenciales de autenticación a tu aplicación o especificar tu ID del 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 hace un muestreo de cada solicitud. Por ejemplo, si usas Java y OpenCensus, solo se realiza un seguimiento de 1 solicitud de cada 10,000. Si usas App Engine, las muestras se muestre 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 del cliente. Algunos paquetes, como el paquete 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 (sin firmar). Debería generarse de forma aleatoria y única en tu seguimiento. Para las solicitudes posteriores, configura SPAN_ID como el ID de 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 ejemplares de Cloud Trace

OpenCensus crea ejecutables de Cloud Trace cuando escribe datos de serie temporal para servicios de gRPC. Para ver estos archivos, debes crear un gráfico y usar la barra de herramientas del gráfico a fin de habilitar su pantalla. Para obtener más información, consulta Usa la barra de herramientas del gráfico.

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

Si escribes métricas personalizadas, puedes crear ejecutables. El siguiente fragmento de código de Go ilustra cómo crear un único Point en una serie temporal. El primer elemento es el intervalo de tiempo, con la etiqueta 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, el 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 habilitada la API de Cloud Trace y no es necesario que realices ninguna acción. Si modificaste los niveles de acceso de tu proyecto de Google Cloud y quieres 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.

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