Go e OpenTelemetry

Questa pagina è progettata per gli sviluppatori di applicazioni che vogliono raccogliere dati di Cloud Trace per le applicazioni Go utilizzando OpenTelemetry. OpenTelemetry è un framework di strumentazione indipendente dal fornitore che puoi usare per raccogliere dati di tracce e metriche. Per informazioni sulla strumentazione del tuo codice, consulta Strumentazione e osservabilità.

  • Installare i pacchetti OpenTelemetry.
  • Configura la tua applicazione per esportare gli intervalli in Cloud Trace.
  • Configura la tua piattaforma.

Per informazioni sulla release, consulta le pagine seguenti:

Per i contenuti di riferimento di OpenTelemetry, vedi quanto segue:

Per i dettagli più recenti su OpenTelemetry for Go, oltre alla documentazione e agli esempi aggiuntivi, consulta OpenTelemetry.

Prima di iniziare

  1. Nel pannello di navigazione della console Google Cloud, seleziona API e servizi, fai clic su Abilita API e servizi e poi abilita l'Cloud Trace API:

    Vai alle impostazioni dell'API Cloud Trace

  2. Se viene visualizzato API abilitata, significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Installazione, inizializzazione e utilizzo del client

Consulta le istruzioni seguenti per strumentare le applicazioni Go su Compute Engine e Google Kubernetes Engine. Per un esempio generale sull'utilizzo di OpenTelemetry, consulta il repository GitHub di OpenTelemetry per Go.

Compute Engine

Installa il pacchetto OpenTelemetry:

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

Importa i pacchetti di esportazione di OpenTelemetry e Cloud Trace:

import (
	"context"
	"errors"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

Crea l'esportatore e il provider di traccia:

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.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err)
	} else if err != nil {
		log.Fatalf("resource.New: %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),
		sdktrace.WithResource(res),
	)
	defer tp.Shutdown(ctx) // flushes any pending spans, and closes connections.
	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)
}

Quando crei l'esportatore, devi fornire informazioni sull'identificatore del progetto Google Cloud. In questo esempio, l'identificatore è archiviato nella variabile di ambiente GOOGLE_CLOUD_PROJECT.

L'applicazione di esempio chiama la funzione WithBatcher per configurare il provider di traccia in modo che invii intervalli a Cloud Monitoring utilizzando un processo in background. L'esempio è inoltre configurato per chiamare la funzione Shutdown dell'esportatore all'uscita dall'applicazione. Quando viene eseguito Shutdown, tutti gli intervalli in attesa vengono inviati a Cloud Monitoring. La configurazione mostrata nell'esempio è l'implementazione consigliata per tutti gli ambienti operativi, incluso per Cloud Run, in cui i container possono essere arresto in qualsiasi momento.

Quando crei l'istanza Tracer, gli devi assegnare un nome. Nell'esempio, il nome è example.com/trace. Ti consigliamo di assegnare a queste istanze il nome in base al componente che viene tracciato, in quanto questa strategia consente di avere più istanze.

Quando viene eseguito l'esempio, viene creata una singola traccia denominata foo.

GKE

Aggiungi il seguente codice a Dockerfile:

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

Importa i pacchetti di esportazione di OpenTelemetry e Cloud Trace:

import (
	"context"
	"errors"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

Crea l'esportatore e il provider di traccia:

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.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err)
	} else if err != nil {
		log.Fatalf("resource.New: %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),
		sdktrace.WithResource(res),
	)
	defer tp.Shutdown(ctx) // flushes any pending spans, and closes connections.
	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)
}

Quando crei l'esportatore, devi fornire informazioni sull'identificatore del progetto Google Cloud. In questo esempio, l'identificatore è archiviato nella variabile di ambiente GOOGLE_CLOUD_PROJECT.

L'applicazione di esempio chiama la funzione WithBatcher per configurare il provider di traccia in modo che invii intervalli a Cloud Monitoring utilizzando un processo in background. L'esempio è inoltre configurato per chiamare la funzione Shutdown dell'esportatore all'uscita dall'applicazione. Quando viene eseguito Shutdown, tutti gli intervalli in attesa vengono inviati a Cloud Monitoring. La configurazione mostrata nell'esempio è l'implementazione consigliata per tutti gli ambienti operativi, incluso per Cloud Run, in cui i container possono essere arresto in qualsiasi momento.

Quando crei l'istanza Tracer, gli devi assegnare un nome. Nell'esempio, il nome è example.com/trace. Ti consigliamo di assegnare a queste istanze il nome in base al componente che viene tracciato, in quanto questa strategia consente di avere più istanze.

Quando viene eseguito l'esempio, viene creata una singola traccia denominata foo.

Come creare un intervallo personalizzato

Puoi aggiungere ulteriori informazioni alla traccia creata dal sistema creando un intervallo personalizzato.

Per creare un intervallo personalizzato con il nome foo, aggiungi quanto segue al codice sorgente:

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

Qui, example.com/trace si riferisce al nome dell'istanza del tracer.

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

In esecuzione su Google Cloud

Quando la tua applicazione è in esecuzione su Google Cloud, non è necessario fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. Tuttavia, devi assicurarti che per la tua piattaforma Google Cloud sia abilitato l'ambito di accesso all'API Cloud Trace.

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina relativa all'assistenza per gli ambienti.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di accesso abilitano l'Cloud Trace API:

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato:

  • Per informazioni su come configurare gli ambiti di accesso per il tuo ambiente utilizzando la console Google Cloud, consulta Configurazione del progetto Google Cloud.

  • Per gli utenti gcloud, specifica gli ambiti di accesso utilizzando il flag --scopes e includi l'ambito di accesso all'Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE in cui è abilitata solo l'Cloud Trace API:

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

Esecuzione in locale e altrove

Se la tua applicazione viene eseguita al di fuori di Google Cloud, devi fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. L'account di servizio deve contenere il ruolo agente Cloud Trace. Per le istruzioni, vedi Creazione di un account di servizio.

Le librerie client di Google Cloud utilizzano le Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione.

Puoi fornire queste credenziali in uno dei tre modi seguenti:

  • Esegui gcloud auth application-default login

  • Inserisci l'account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono elencati i percorsi predefiniti per Windows e Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso al tuo account di servizio:

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"

Visualizza tracce

Nel pannello di navigazione della console Google Cloud, seleziona Trace e poi Trace Explorer:

Vai a Trace Explorer

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alla pagina Risoluzione dei problemi.