OpenTelemetry mit Go verwenden

Sie können Cloud Trace for Go-Anwendungen mit OpenTelemetry aktivieren. OpenTelemetry bietet eine Reihe von Instrumentierungsbibliotheken zum Erfassen von Trace- und Messwertdaten, die mit mehreren Back-Ends funktionieren. Aktuelle Informationen zu OpenTelemetrie für Go sowie zusätzliche Dokumentation und Beispiele finden Sie unter https://opentelemetry.io/.

Installation und Konfiguration

Zum Erfassen von Traces gehen Sie so vor:

  • Installieren Sie die OpenTelemetry-Clientbibliotheken.
  • Importieren Sie die OpenTelemetry-Trace-Pakete.
  • Konfigurieren Sie OpenTelemetry so, dass Spans nach Cloud Trace exportiert werden.
  • Aktivieren Sie den Zugriffsbereich der Cloud Trace API.

Client installieren, initialisieren und verwenden

In der folgenden Anleitung erfahren Sie, wie Sie Ihre Go-Anwendungen in Compute Engine und Google Kubernetes Engine automatisieren.

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/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Erstellen Sie den Exporter und den Trace-Anbieter:

func main() {
	// Create exporter.
	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
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	// Create custom span.
	tracer := global.TraceProvider().Tracer("example.com/trace")
	tracer.WithSpan(context.Background(), "foo",
		func(_ context.Context) error {
			// Do some work.
			return nil
		})
}

Hier bezieht sich example.com/trace auf den Namen der Tracer-Instanz und foo auf den Namen des Spans. Die Tracer-Instanz sollte nach der zu verfolgenden Komponente benannt werden, da Sie mehrere Tracer-Instanzen haben können.

GKE

Fügen Sie Ihrem 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/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Erstellen Sie den Exporter und den Trace-Anbieter:

func main() {
	// Create exporter.
	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
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	// Create custom span.
	tracer := global.TraceProvider().Tracer("example.com/trace")
	tracer.WithSpan(context.Background(), "foo",
		func(_ context.Context) error {
			// Do some work.
			return nil
		})
}

Hier bezieht sich example.com/trace auf den Namen der Tracer-Instanz und foo auf den Namen des Spans. Die Tracer-Instanz wird nach der zu verfolgenden Komponente benannt, um sie identifizierbar zu machen. Sie haben möglicherweise mehrere Tracer-Instanzen.

So erstellen Sie einen benutzerdefinierten Span

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

Fügen Sie dem Quellcode Folgendes hinzu, um einen benutzerdefinierten Span zu erstellen:

// Create custom span.
tracer := global.TraceProvider().Tracer("example.com/trace")
tracer.WithSpan(context.Background(), "foo",
	func(_ context.Context) error {
		// Do some work.
		return nil
	})

Hier bezieht sich example.com/trace auf den Namen der Tracer-Instanz und foo auf den Namen des Spans. Die Tracer-Instanz wird nach der zu verfolgenden Komponente benannt, um sie identifizierbar zu machen. Sie haben möglicherweise mehrere Tracer-Instanzen.

Ihre Plattform konfigurieren

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

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie der Clientbibliothek keine Anmeldedaten in Form eines Dienstkontos bereitstellen. Sie müssen jedoch gewährleisten, dass auf Ihrer Google Cloud Platform der Zugriffsbereich der Cloud Trace API aktiviert ist.

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

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, müssen Sie gewährleisten, dass der Zugriffsbereich der Cloud Trace API aktiviert ist. Geben Sie für gcloud-Nutzer Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Cloud Trace API-Zugriffsbereich trace.append 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 Authentifizierungsdaten in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Cloud Trace-Agent-Rolle enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen, um die Anmeldedaten Ihrer Anwendung zu finden. 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"

Leistungsoptimierung

Verwenden Sie einen Hintergrundprozess zum Senden dieser Daten, um die Auswirkung auf die Leistung von Trace-Daten zu reduzieren. Um die Hintergrundberichte von Trace-Daten zu konfigurieren, schließen Sie transport=AsyncTransport bei der Initialisierung von StackdriverExporter ein.

Traces ansehen

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

Trace-Anzeige öffnen

Fehlerbehebung

Informationen zur Behebung von Problemen mit Cloud Trace finden Sie auf der Seite zur Fehlerbehebung.