Usa OpenTelemetry con Go

Puedes habilitar Cloud Trace para las aplicaciones de Go mediante OpenTelemetry. OpenTelemetry es un conjunto de bibliotecas de instrumentación para recopilar datos de seguimiento y de métricas que funcionan con varios backends. Si deseas obtener los detalles más recientes sobre OpenTelemetry para Go, junto con documentación y ejemplos adicionales, ve a https://opentelemetry.io/.

Instalación y configuración

Para recopilar seguimientos, debes hacer lo siguiente:

  • Instalar las bibliotecas cliente de OpenTelemetry
  • Importar los paquetes de seguimiento de OpenTelemetry
  • Configurar OpenTelemetry para exportar intervalos a Cloud Trace
  • Habilita el permiso de acceso a la API de Cloud Trace.

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.

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/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crea el exportador y el proveedor de seguimiento:

func main() {
	// Create exporter.
	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
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().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)
}

Aquí, example.com/trace hace referencia al nombre de la instancia del rastreador y foo es el nombre del intervalo. La instancia de rastreador debe llamarse como el componente en el que se realiza el seguimiento porque podrías tener varias instancias de rastreador.

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/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crea el exportador y el proveedor de seguimiento:

func main() {
	// Create exporter.
	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
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().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)
}

Aquí, example.com/trace hace referencia al nombre de la instancia del rastreador y foo es el nombre del intervalo. El nombre de la instancia del rastreador recibe el nombre del componente que se está rastreando para que sea identificable. Es posible que tengas varias instancias de Trace.

Cómo crear un intervalo personalizado

Puedes agregar información adicional al seguimiento creado por el sistema con un intervalo personalizado.

Para crear un intervalo personalizado, agrega lo siguiente al código fuente:

ctx := context.Background()
// Create custom span.
tracer := global.TraceProvider().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)

Aquí, example.com/trace hace referencia al nombre de la instancia del rastreador y foo es el nombre del intervalo. El nombre de la instancia del rastreador recibe el nombre del componente que se está rastreando para que pueda identificarse. Es posible que tengas varias instancias de Trace.

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 forma de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud tenga habilitado el nivel de acceso a la API de Cloud Trace.

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

Si usas niveles de acceso personalizados, debes asegurarte de que el nivel de acceso a la API de Cloud Trace esté habilitado. Para los usuarios de gcloud, especifica los niveles de acceso con 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"

Optimización del rendimiento

A fin de reducir el impacto en el rendimiento de los datos de seguimiento de informes, usa un proceso en segundo plano para enviar estos datos. Para configurar los informes en segundo plano de datos de seguimiento, incluye transport=AsyncTransport cuando inicialices el StackdriverExporter.

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.