Go y OpenTelemetry

Esta página está diseñada para desarrolladores de aplicaciones que deseen recopilar datos de Cloud Trace para aplicaciones de Go mediante OpenTelemetry. OpenTelemetry es un conjunto de bibliotecas de instrumentación para recopilar datos de seguimiento y métricas, que funcionan con varios backends. Para recopilar seguimientos con OpenTelemetry y Go, sigue estos pasos, como se describe en esta página:

  • Instala los paquetes de OpenTelemetry.
  • Configurar tu aplicación para exportar intervalos a Cloud Trace
  • Configura tu plataforma.

Para obtener información sobre las versiones, consulta los siguientes vínculos:

Para obtener los detalles más recientes sobre OpenTelemetry para Go, junto con documentación y ejemplos adicionales, consulta OpenTelemetry.

Antes de comenzar

Verifica que la API de Cloud Trace esté habilitada para tu proyecto de Google Cloud:

  1. Haz clic en el siguiente botón o, en Google Cloud Console, selecciona API y servicios y, luego, selecciona API de Cloud Trace:

    Ir a la API de Trace

  2. En la página API de Cloud Trace, si se muestra un botón etiquetado como Habilitar, haz clic en él. Si no se muestra este botón, la API de Cloud Trace está habilitada para el proyecto seleccionado.

Instala, inicializa y usa el cliente

Consulta las siguientes instrucciones a fin de instrumentar tus aplicaciones de Go en Compute Engine y Google Kubernetes Engine. Si deseas obtener un ejemplo general del uso de OpenTelemetry, consulta el repositorio de GitHub de OpenTelemetry para Go.

Compute Engine

Instala el paquete de OpenTelemetry:

go get -u go.opentelemetry.io/otel
go get -u github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace

Importa los paquetes de exportación de OpenTelemetry y Cloud Trace:

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crea el exportador y el proveedor de seguimiento:

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.NewExporter: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer tp.ForceFlush(ctx) // flushes any pending spans
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

Cuando creas el exportador, proporcionas información sobre el identificador del proyecto de Google Cloud. En este ejemplo, el identificador se almacena en la variable de entorno GOOGLE_CLOUD_PROJECT.

La aplicación de ejemplo llama a la función WithBatcher para configurar el proveedor de seguimiento a fin de enviar intervalos a Cloud Monitoring mediante un proceso en segundo plano. El ejemplo también está configurado para llamar a la función Shutdown del exportador cuando se sale de la aplicación. Cuando se ejecuta Shutdown, envía todos los intervalos pendientes a Cloud Monitoring. La configuración que se muestra en la muestra es la implementación recomendada para todos los entornos operativos, incluido Cloud Run en el que los contenedores se pueden cerrar en cualquier momento.

Cuando creas la instancia Tracer, le asignas un nombre. En el ejemplo, el nombre es example.com/trace. Te recomendamos asignar un nombre a estas instancias después del seguimiento del componente, ya que esta estrategia te permite tener varias instancias.

Cuando se ejecuta el ejemplo, se crea un seguimiento único denominado foo.

GKE

Agrega lo siguiente a tu Dockerfile:

RUN go get -u go.opentelemetry.io/otel

Importa los paquetes de exportación de OpenTelemetry y Cloud Trace:

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crea el exportador y el proveedor de seguimiento:

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.NewExporter: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer tp.ForceFlush(ctx) // flushes any pending spans
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

Cuando creas el exportador, proporcionas información sobre el identificador del proyecto de Google Cloud. En este ejemplo, el identificador se almacena en la variable de entorno GOOGLE_CLOUD_PROJECT.

La aplicación de ejemplo llama a la función WithBatcher para configurar el proveedor de seguimiento a fin de enviar intervalos a Cloud Monitoring mediante un proceso en segundo plano. El ejemplo también está configurado para llamar a la función Shutdown del exportador cuando se sale de la aplicación. Cuando se ejecuta Shutdown, envía todos los intervalos pendientes a Cloud Monitoring. La configuración que se muestra en la muestra es la implementación recomendada para todos los entornos operativos, incluido Cloud Run en el que los contenedores se pueden cerrar en cualquier momento.

Cuando creas la instancia Tracer, le asignas un nombre. En el ejemplo, el nombre es example.com/trace. Te recomendamos asignar un nombre a estas instancias después del seguimiento del componente, ya que esta estrategia te permite tener varias instancias.

Cuando se ejecuta el ejemplo, se crea un seguimiento único denominado foo.

Cómo crear un intervalo personalizado

Puedes agregar información adicional al seguimiento creado por el sistema mediante la creación de un intervalo personalizado.

Para crear un intervalo personalizado con el nombre foo, agrega lo siguiente al código fuente:

// Create custom span.
tracer := otel.GetTracerProvider().Tracer("example.com/trace")
err = func(ctx context.Context) error {
	ctx, span := tracer.Start(ctx, "foo")
	defer span.End()

	// Do some work.

	return nil
}(ctx)

En este caso, example.com/trace hace referencia al nombre de la instancia del rastreador.

Configura tu plataforma

Puedes usar Cloud Trace en Google Cloud y otras plataformas.

Ejecuta en Google Cloud

Cuando tu aplicación se ejecuta en Google Cloud, no necesitas proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud tenga habilitado el permiso de acceso a la API de Cloud Trace.

Para obtener una lista de los entornos compatibles de Google Cloud, consulta Compatibilidad con el entorno.

Para las siguientes opciones de configuración, la configuración predeterminada del permiso de acceso habilita la API de Cloud Trace:

  • Entorno flexible de App Engine
  • Entorno estándar de App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API de Cloud Trace esté habilitado:

  • Para obtener información sobre cómo configurar los permisos de acceso para tu entorno mediante Google Cloud Console, consulta Configura tu proyecto de Google Cloud.

  • Para los usuarios gcloud, especifica los permisos de acceso mediante la marca --scopes y, también, incluye el permiso de acceso a la API de Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE solo con la API de Cloud Trace habilitada, sigue estos pasos:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Ejecuta de forma local y en otros lugares

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 contener la función de agente de Cloud Trace. Para obtener más instrucciones, consulta Cómo crear una cuenta de servicio.

Las bibliotecas cliente de Google Cloud usan las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación. Estas credenciales se proporcionan mediante la configuración de la variable de entorno GOOGLE_APPLICATION_CREDENTIALS:

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"

Cómo ver los seguimientos

Después de la implementación, puedes ver los seguimientos en el visor de seguimientos de Cloud Console.

Ir a la página del Lector de seguimiento

Soluciona problemas

Para obtener información sobre cómo solucionar problemas con Cloud Trace, ve a la página de solución de problemas.