Go et OpenTelementry

Cette page est conçue pour les développeurs d'applications qui souhaitent collecter des données 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. Ces bibliothèques fonctionnent avec plusieurs backends. Pour collecter des traces avec OpenTelementry et Go, procédez comme suit :

  • Installez les packages OpenTelementry.
  • Configurez votre application pour exporter les délais vers Cloud Trace.
  • Configurez votre plate-forme.

Pour en savoir plus sur les versions, consultez les articles suivants :

Pour obtenir les dernières informations sur OpenTelemetry pour Go, ainsi que de la documentation supplémentaire et des exemples, consultez la section OpenTelemetry.

Avant de commencer

Vérifiez que l'API Cloud Trace est activée pour votre projet Google Cloud :

  1. Cliquez sur le bouton suivant ou, dans Google Cloud Console, sélectionnez API et services, puis API Cloud Trace :

    Accéder à l'API Trace

  2. Sur la page API Cloud Trace, si un bouton Activer s'affiche, cliquez dessus. Si ce bouton n'est pas affiché, l'API Cloud Trace est activée pour le projet sélectionné.

Installer, initialiser et utiliser le client

Consultez les instructions suivantes pour instrumenter vos applications Go sur Compute Engine et Google Kubernetes Engine. Pour obtenir un exemple général d'utilisation d'OpenTelemetry, consultez le dépôt GitHub OpenTelemetry pour Go.

Compute Engine

Installez le package OpenTelemetry :

go get go.opentelemetry.io/otel
go get 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"
	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.New(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)
}

Lorsque vous créez l'exportateur, vous fournissez des informations sur votre identifiant de projet Google Cloud. Dans cet exemple, l'identifiant est stocké dans la variable d'environnement GOOGLE_CLOUD_PROJECT.

L'exemple d'application appelle la fonction WithBatcher pour configurer le fournisseur de traces afin d'envoyer des délais à Cloud Monitoring à l'aide d'un processus en arrière-plan. L'exemple est également configuré pour appeler la fonction Shutdown de l'exportateur sur la sortie de l'application. Lorsque Shutdown s'exécute, il envoie tous les délais en attente à Cloud Monitoring. La configuration présentée dans l'exemple est la mise en œuvre recommandée pour tous les environnements d'exploitation, y compris pour Cloud Run où les conteneurs peuvent être arrêtés à tout moment.

Lorsque vous créez l'instance Tracer, vous lui attribuez un nom. Dans l'exemple, le nom est example.com/trace. Nous vous recommandons de nommer ces instances en fonction du composant tracé, car cette stratégie vous permet d'en avoir plusieurs.

Lorsque l'exemple est exécuté, une seule trace nommée foo est créée.

GKE

Ajoutez les éléments suivants à votre Dockerfile :

RUN go get go.opentelemetry.io/otel
RUN go get 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"
	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.New(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)
}

Lorsque vous créez l'exportateur, vous fournissez des informations sur votre identifiant de projet Google Cloud. Dans cet exemple, l'identifiant est stocké dans la variable d'environnement GOOGLE_CLOUD_PROJECT.

L'exemple d'application appelle la fonction WithBatcher pour configurer le fournisseur de traces afin d'envoyer des délais à Cloud Monitoring à l'aide d'un processus en arrière-plan. L'exemple est également configuré pour appeler la fonction Shutdown de l'exportateur sur la sortie de l'application. Lorsque Shutdown s'exécute, il envoie tous les délais en attente à Cloud Monitoring. La configuration présentée dans l'exemple est la mise en œuvre recommandée pour tous les environnements d'exploitation, y compris pour Cloud Run où les conteneurs peuvent être arrêtés à tout moment.

Lorsque vous créez l'instance Tracer, vous lui attribuez un nom. Dans l'exemple, le nom est example.com/trace. Nous vous recommandons de nommer ces instances en fonction du composant tracé, car cette stratégie vous permet d'en avoir plusieurs.

Lorsque l'exemple est exécuté, une seule trace nommée foo est créée.

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é nommé foo, ajoutez les éléments suivants au code source :

// 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)

Ici, example.com/trace fait référence au nom de l'instance 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 obtenir la liste des environnements Google Cloud compatibles, consultez la page Environnements compatibles.

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

  • Cloud Run

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 en savoir plus sur la configuration des niveaux d'accès pour votre environnement à l'aide de Google Cloud Console, consultez la section Configurer votre projet Google Cloud.

  • 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"

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.