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

Im Folgenden finden Sie eine Anleitung zur Instrumentierung Ihrer Go-Anwendungen in Compute Engine und in Google Kubernetes Engine.

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)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().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 und foo ist der Name des Spans. Die Tracer-Instanz sollte nach der Komponente benannt werden, die verfolgt wird, da Sie mehrere Tracer-Instanzen haben können.

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

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().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 und foo ist der Name des Spans. Die Tracer-Instanz ist nach der Komponente benannt, die verfolgt werden soll, damit sie einfacher identifiziert werden kann. Sie haben möglicherweise mehrere Tracer-Instanzen.

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 fügen Sie dem Quellcode Folgendes hinzu:

ctx := context.Background()
// Create custom span.
tracer := global.TraceProvider().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 und foo ist der Name des Spans. Die Tracer-Instanz ist nach der Komponente benannt, die verfolgt werden soll, damit sie einfacher identifiziert werden kann. Sie haben möglicherweise mehrere Tracer-Instanzen.

Ihre 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.

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, muss der Zugriffsbereich der Cloud Trace API aktiviert sein. 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 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, um diese Daten zu senden und die Leistung bei der Berichterstellung von Trace-Daten zu reduzieren. Fügen Sie transport=AsyncTransport beim Initialisieren von StackdriverExporter ein, um Hintergrundberichte von Trace-Daten zu konfigurieren.

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.