Utiliser OpenTelemetry avec Go

Vous pouvez activer Cloud Trace pour les applications Go à l'aide d'OpenTelemetry. OpenTelemetry est un ensemble de bibliothèques d'instrumentation permettant de collecter des données de trace et de métrique compatibles avec plusieurs backends. Pour obtenir les dernières informations sur OpenTelemetry pour Go, ainsi que de la documentation supplémentaire et des exemples, consultez la page https://opentelemetry.io/.

Installation et configuration

Pour collecter des traces, procédez comme suit :

  • Installez les bibliothèques clientes OpenTelementry.
  • Importez les packages de trace OpenTelemetry.
  • Configurez OpenTelemetry pour exporter les délais vers Cloud Trace.
  • Activez le niveau d'accès de l'API Cloud Trace.

Installer, initialiser et utiliser le client

Consultez les instructions suivantes pour instrumenter vos applications Go sur Compute Engine et Google Kubernetes Engine.

Instance

Installez le package OpenTelemetry :

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

Importez les packages d'exportation OpenTelemetry et 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"
)

Créez l'exportateur et le fournisseur de traces :

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)
	}
	defer exporter.Shutdown(ctx) // flushes any pending spans

	// 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 := sdktrace.NewTracerProvider(sdktrace.WithConfig(config), ...)
	tp := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exporter))
	global.SetTracerProvider(tp)

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

Ici, example.com/trace fait référence au nom de l'instance de traceur et foo est le nom du délai. L'instance de traceur doit porter le nom du composant tracé, car vous pouvez avoir plusieurs instances de traceur.

GKE

Ajoutez les éléments suivants à votre Dockerfile :

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

Importez les packages d'exportation OpenTelemetry et 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"
)

Créez l'exportateur et le fournisseur de traces :

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)
	}
	defer exporter.Shutdown(ctx) // flushes any pending spans

	// 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 := sdktrace.NewTracerProvider(sdktrace.WithConfig(config), ...)
	tp := sdktrace.NewTracerProvider(sdktrace.WithSyncer(exporter))
	global.SetTracerProvider(tp)

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

Ici, example.com/trace fait référence au nom de l'instance de traceur et foo est le nom du délai. L'instance du traceur porte le nom du composant suivi pour le rendre identifiable ; vous pouvez avoir plusieurs instances de traceur.

Comment créer un délai personnalisé

Vous pouvez ajouter des informations supplémentaires à la trace créée par le système en créant un délai personnalisé.

Pour créer un délai personnalisé, ajoutez les éléments suivants au code source :

// Create custom span.
tracer := global.TracerProvider().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)

Ici, example.com/trace fait référence au nom de l'instance de traceur et foo est le nom du délai. L'instance du traceur porte le nom du composant suivi pour le rendre identifiable ; vous pouvez avoir plusieurs instances de traceur.

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécuter des applications sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

  • Environnement flexible App Engine
  • Environnement standard App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

Si vous utilisez des niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé. Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'indicateur --scopes et incluez le niveau d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :

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

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous fournissez ces identifiants en définissant la variable d'environnement 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"

Optimisation des performances

Pour réduire l'impact sur les performances des données de trace, utilisez un processus en arrière-plan pour envoyer ces données. Pour configurer la création de rapports en arrière-plan sur les données de trace, incluez transport=AsyncTransport lors de l'initialisation de StackdriverExporter.

Afficher les traces

Après le déploiement, vous pouvez afficher les traces dans la visionneuse de traces de Cloud Console.

Accéder à la page Lecteur de traces

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.