Go und OpenTelemetry

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für Go-Anwendungen mit OpenTelemetry erfassen möchten. OpenTelemetry ist ein anbieterneutrales Instrumentierungs-Framework, mit dem Sie Trace- und Messwertdaten erfassen können. Informationen zum Instrumentieren des Codes finden Sie unter Instrumentierung und Beobachtbarkeit.

  • Installieren Sie die OpenTelemetry-Pakete.
  • Anwendung für den Export von Spans nach Cloud Trace konfigurieren
  • Konfigurieren Sie Ihre Plattform.

Releaseinformationen finden Sie hier:

Referenzinhalte zu OpenTelemetry finden Sie hier:

Aktuelle Informationen zu OpenTelemetrie für Go sowie zusätzliche Dokumentation und Beispiele finden Sie unter OpenTelemetry.

Hinweise

  1. Wählen Sie im Navigationsbereich der Google Cloud Console APIs und Dienste aus, klicken Sie auf APIs und Dienste aktivieren und aktivieren Sie dann die Cloud Trace API:

    Zu den Einstellungen für die Cloud Trace API

  2. Wenn API aktiviert angezeigt wird, ist die API bereits aktiviert. Falls nicht, klicken Sie auf die Schaltfläche Aktivieren.

Client installieren, initialisieren und verwenden

Im Folgenden finden Sie eine Anleitung zur Instrumentierung Ihrer Go-Anwendungen in Compute Engine und in Google Kubernetes Engine. Ein allgemeines Beispiel für die Verwendung von OpenTelemetry finden Sie im GitHub-Repository für Go.

Compute Engine

Installieren Sie das OpenTelemetry-Paket:

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

Importieren Sie OpenTelemetry- und Cloud Trace-Exportpakete:

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

Erstellen Sie den Exporter und den Trace-Anbieter:

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

Wenn Sie den Exporter erstellen, geben Sie Informationen über Ihre Google Cloud-Projekt-ID an. In diesem Beispiel wird die ID in der Umgebungsvariable GOOGLE_CLOUD_PROJECT gespeichert.

Die Beispielanwendung ruft die Funktion WithBatcher auf, um den Trace-Anbieter so zu konfigurieren, dass Spans über einen Hintergrundprozess an Cloud Monitoring gesendet werden. Das Beispiel ist auch so konfiguriert, dass die Funktion Shutdown des Exporters beim Beenden der Anwendung aufgerufen wird. Wenn Shutdown ausgeführt wird, werden alle ausstehenden Spans an Cloud Monitoring gesendet. Die im Beispiel gezeigte Konfiguration ist die empfohlene Implementierung für alle Betriebsumgebungen, einschließlich für Cloud Run, in dem Container jederzeit heruntergefahren werden können.

Wenn Sie die Instanz Tracer erstellen, geben Sie ihr einen Namen. In diesem Beispiel lautet der Name example.com/trace. Wir empfehlen, diese Instanzen nach der Komponente zu benennen, die verfolgt werden soll, da Sie mit dieser Strategie mehrere Instanzen haben können.

Wenn das Beispiel ausgeführt wird, wird ein einzelner Trace mit dem Namen foo erstellt.

GKE

Fügen Sie zum Dockerfile Folgendes hinzu:

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

Importieren Sie OpenTelemetry- und Cloud Trace-Exportpakete:

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

Erstellen Sie den Exporter und den Trace-Anbieter:

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

Wenn Sie den Exporter erstellen, geben Sie Informationen über Ihre Google Cloud-Projekt-ID an. In diesem Beispiel wird die ID in der Umgebungsvariable GOOGLE_CLOUD_PROJECT gespeichert.

Die Beispielanwendung ruft die Funktion WithBatcher auf, um den Trace-Anbieter so zu konfigurieren, dass Spans über einen Hintergrundprozess an Cloud Monitoring gesendet werden. Das Beispiel ist auch so konfiguriert, dass die Funktion Shutdown des Exporters beim Beenden der Anwendung aufgerufen wird. Wenn Shutdown ausgeführt wird, werden alle ausstehenden Spans an Cloud Monitoring gesendet. Die im Beispiel gezeigte Konfiguration ist die empfohlene Implementierung für alle Betriebsumgebungen, einschließlich für Cloud Run, in dem Container jederzeit heruntergefahren werden können.

Wenn Sie die Instanz Tracer erstellen, geben Sie ihr einen Namen. In diesem Beispiel lautet der Name example.com/trace. Wir empfehlen, diese Instanzen nach der Komponente zu benennen, die verfolgt werden soll, da Sie mit dieser Strategie mehrere Instanzen haben können.

Wenn das Beispiel ausgeführt wird, wird ein einzelner Trace mit dem Namen foo erstellt.

Benutzerdefinierten Span erstellen

Sie können dem vom System erstellten Trace zusätzliche Informationen hinzufügen, indem Sie einen benutzerdefinierten Span erstellen.

Zum Erstellen eines benutzerdefinierten Spans mit dem Namen foo fügen Sie dem Quellcode Folgendes hinzu:

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

Hier bezieht sich example.com/trace auf den Namen der Tracer-Instanz.

Plattform konfigurieren

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in der Clientbibliothek angeben. Für die Google Cloud Platform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein.

Eine Liste der unterstützten Google Cloud-Umgebungen finden Sie unter Umgebungsunterstützung.

Für die folgenden Konfigurationen wird die Cloud Trace API über die Standardeinstellungen für den Zugriffsbereich aktiviert:

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein:

  • Informationen zum Konfigurieren der Zugriffsbereiche für Ihre Umgebung mit der Google Cloud Console finden Sie unter Google Cloud-Projekt konfigurieren.

  • Geben Sie für gcloud-Nutzer mithilfe des Flags --scopes Zugriffsbereiche an und beziehen Sie den Zugriffsbereich der Cloud Trace API trace.append ein. So erstellen Sie beispielsweise einen GKE-Cluster, für den nur die Cloud Trace API aktiviert ist:

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

Lokal und extern ausführen

Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie Anmeldedaten zur Authentifizierung in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Rolle "Cloud Trace-Agent" enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen für die Suche nach den Anmeldedaten Ihrer Anwendung.

Sie haben drei Möglichkeiten, diese Anmeldedaten anzugeben:

  • Führen Sie gcloud auth application-default login aus

  • Platzieren Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem. Im Folgenden sind die Standardpfade für Windows und Linux aufgeführt:

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

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

  • Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrem Dienstkonto fest:

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"

Traces ansehen

Wählen Sie im Navigationsbereich der Google Cloud Console Trace und dann Trace Explorer aus:

Zum Trace Explorer

Fehlerbehebung

Informationen zur Fehlerbehebung bei Cloud Trace finden Sie auf der Seite Fehlerbehebung.