Go und OpenTelemetry

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für Go-Anwendungen mithilfe von OpenTelemetry erfassen möchten. OpenTelemetry besteht aus einer Reihe von Instrumentierungsbibliotheken zum Erfassen von Trace- und Messwertdaten. Diese Bibliotheken funktionieren mit mehreren Back-Ends. So erfassen Sie Traces mit OpenTelemetry und Go, wie auf dieser Seite beschrieben:

  • Installieren Sie die OpenTelemetry-Pakete.
  • Anwendung so konfigurieren, dass Spans nach Cloud Trace exportiert werden
  • Konfigurieren Sie Ihre Plattform.

Versionshinweise:

Aktuelle Details zu OpenTelemetry for Go sowie weitere Dokumentationen und Beispiele finden Sie unter OpenTelemetry.

Hinweis

Prüfen Sie, ob die Cloud Trace API für Ihr Google Cloud-Projekt aktiviert ist:

  1. Klicken Sie auf die folgende Schaltfläche oder wählen Sie in der Google Cloud Console APIs & Dienste und dann Cloud Trace API aus.

    Zur Trace API

  2. Wenn auf der Seite Cloud Trace API die Schaltfläche Aktivieren angezeigt wird, klicken Sie darauf. Wenn diese Schaltfläche nicht angezeigt wird, ist die Cloud Trace API für das ausgewählte Projekt aktiviert.

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 von OpenTelemetry für Go.

Compute Engine

Installieren Sie das OpenTelemetry-Paket:

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

Importieren Sie OpenTelemetry- und Cloud Trace-Exportpakete:

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Erstellen Sie den Exporter und den Trace-Anbieter:

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

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

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

In der Beispielanwendung wird die Funktion WithBatcher aufgerufen, um den Trace-Anbieter so zu konfigurieren, dass Spans mithilfe eines Hintergrundprozesses an Cloud Monitoring gesendet werden. Das Beispiel ist auch so konfiguriert, dass die Shutdown-Funktion des Exporters beim Beenden der Anwendung aufgerufen wird. Bei Ausführung von Shutdown 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. Im Beispiel lautet der Name example.com/trace. Wir empfehlen, diese Instanzen nach der Komponente zu benennen, da sie mehrere Instanzen ermöglicht.

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 -u go.opentelemetry.io/otel

Importieren Sie OpenTelemetry- und Cloud Trace-Exportpakete:

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Erstellen Sie den Exporter und den Trace-Anbieter:

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

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

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

In der Beispielanwendung wird die Funktion WithBatcher aufgerufen, um den Trace-Anbieter so zu konfigurieren, dass Spans mithilfe eines Hintergrundprozesses an Cloud Monitoring gesendet werden. Das Beispiel ist auch so konfiguriert, dass die Shutdown-Funktion des Exporters beim Beenden der Anwendung aufgerufen wird. Bei Ausführung von Shutdown 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. Im Beispiel lautet der Name example.com/trace. Wir empfehlen, diese Instanzen nach der Komponente zu benennen, da sie mehrere Instanzen ermöglicht.

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)

Dabei 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:

  • Flexible App Engine-Umgebung
  • App Engine-Standardumgebung

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, müssen Sie dafür sorgen, dass der Zugriffsbereiche der Cloud Trace API aktiviert ist:

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

  • Geben Sie für gcloud-Nutzer Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Zugriffsbereich trace.append der Cloud Trace API hinzu. 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 geben diese Anmeldedaten an, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen:

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

Nach der Bereitstellung können Sie die Traces im Trace Viewer der Cloud Console anzeigen.

Trace-Anzeige öffnen

Fehlerbehebung

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