Vai e OpenTelemetry

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina è progettata per gli sviluppatori di applicazioni che vogliono raccogliere dati Cloud Trace per le applicazioni Go utilizzando OpenTelemetry. OpenTelemetry è un set di librerie di strumentazione per la raccolta di dati di tracce e metriche; queste librerie funzionano con più backend. Per raccogliere tracce con OpenTelemetry e Go, procedi come descritto di seguito:

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

Per informazioni sulla versione, consulta quanto segue:

Per i dettagli più recenti su OpenTelemetry per Go, oltre a documentazione ed esempi aggiuntivi, consulta OpenTelemetry.

Prima di iniziare

Verifica che l'API Cloud Trace sia abilitata per il tuo progetto Google Cloud:

  1. Fai clic sul pulsante seguente o, in Google Cloud Console, seleziona API e servizi, quindi seleziona API Cloud Trace:

    Vai all'API Trace

  2. Nella pagina dell'API Cloud Trace, se viene visualizzato un pulsante con l'etichetta Abilita, fai clic su di esso. Se questo pulsante non viene visualizzato, significa che l'API Cloud Trace è abilitata per il progetto selezionato.

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 di 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"
	"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.7.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 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.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)
}

Quando crei l'esportatore, fornisci 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 per inviare gli intervalli a Cloud Monitoring utilizzando un processo in background. L'esempio è configurato anche per chiamare la funzione Shutdown dell'esportatore all'uscita dall'applicazione. Quando Shutdown viene eseguito, invia tutti gli intervalli in sospeso a Cloud Monitoring. La configurazione mostrata nell'esempio è l'implementazione consigliata per tutti gli ambienti operativi, tra cui Cloud Run in cui i container possono essere arresto in qualsiasi momento.

Quando crei l'istanza Tracer, le assegni un nome. Nell'esempio, il nome è example.com/trace. Consigliamo di assegnare un nome a queste istanze dopo che il componente è stato monitorato poiché questa strategia ti consente di avere più istanze.

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

GKE

Aggiungi i seguenti elementi 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"
	"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.7.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 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.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)
}

Quando crei l'esportatore, fornisci 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 per inviare gli intervalli a Cloud Monitoring utilizzando un processo in background. L'esempio è configurato anche per chiamare la funzione Shutdown dell'esportatore all'uscita dall'applicazione. Quando Shutdown viene eseguito, invia tutti gli intervalli in sospeso a Cloud Monitoring. La configurazione mostrata nell'esempio è l'implementazione consigliata per tutti gli ambienti operativi, tra cui Cloud Run in cui i container possono essere arresto in qualsiasi momento.

Quando crei l'istanza Tracer, le assegni un nome. Nell'esempio, il nome è example.com/trace. Consigliamo di assegnare un nome a queste istanze dopo che il componente è stato monitorato poiché questa strategia ti 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 denominato 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)

In questo caso, example.com/trace si riferisce al nome dell'istanza di traccia.

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

Esecuzione in Google Cloud

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

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina Assistenza per l'ambiente.

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

  • Ambiente flessibile di App Engine
  • Ambiente standard di App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

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 Google Cloud Console, 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 API Cloud Trace trace.append. Ad esempio, per creare un cluster GKE con solo l'API Cloud Trace abilitata, segui questi passaggi:

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

Esecuzione locale e altrove

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

Le librerie client di Google Cloud utilizzano le credenziali predefinite dell'applicazione per trovare le credenziali dell'applicazione.

Per fornire queste credenziali, puoi utilizzare uno dei tre metodi seguenti:

  • Esegui gcloud auth application-default login

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

Visualizzazione delle tracce

Dopo il deployment, puoi visualizzare le tracce in Visualizzatore Trace di Google Cloud Console.

Vai alla pagina Visualizzatore tracce

Risolvere i problemi

Per informazioni sulla risoluzione dei problemi con Cloud Trace, consulta la pagina per la risoluzione dei problemi.