Cloud Trace für Go einrichten

Sie können Cloud Trace für Go-Anwendungen mithilfe von OpenCensus aktivieren. OpenCensus ist eine Sammlung von Instrumentenbibliotheken zum Erfassen von Trace- und Messwertdaten, die mit mehreren Back-Ends funktionieren. Die neuesten Informationen zu OpenCensus für Go sowie zusätzliche Dokumentation und Beispiele finden Sie unter opencensus-go.

Paket installieren

Rufen Sie das OpenCensus-Trace-Paket ab:

go get go.opencensus.io/trace

Stackdriver-Exporter konfigurieren

Nutzen Sie zum Exportieren der erfassten Trace-Daten einen Stackdriver-Exporter:


import (
	"log"
	"os"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"go.opencensus.io/trace"
)

func main() {
	// Create and register a OpenCensus Stackdriver Trace exporter.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{
		ProjectID: os.Getenv("GOOGLE_CLOUD_PROJECT"),
	})
	if err != nil {
		log.Fatal(err)
	}
	trace.RegisterExporter(exporter)
}

Wenn Sie die Google Cloud-Infrastruktur ausführen, müssen Sie das Feld ProjectID nicht auf Ihre Google Cloud-Projekt-ID festlegen, da die Clientbibliothek für Go diese Daten automatisch von einem Google Cloud-Metadatenserver erfasst.

Wenn Sie nicht die Google Cloud-Infrastruktur verwenden, müssen Sie im Feld ProjectID Ihre Google Cloud-Projekt-ID eingeben. Im Beispielcode wird eine Umgebungsvariable verwendet. Die Anwendung wurde geändert, um diese Variable zu lesen.

Integration mit Cloud Logging konfigurieren

Informationen zum Senden von Cloud Trace-Daten an Cloud Logging finden Sie unter Integration in Cloud Logging.

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

Dafür gibt es drei Möglichkeiten:

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

  • Legen Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem ab. Nachfolgend 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"

Trace-Beispielanwendung für Go


// Sample trace_quickstart traces incoming and outgoing requests.
package main

import (
	"log"
	"net/http"
	"os"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"contrib.go.opencensus.io/exporter/stackdriver/propagation"
	"go.opencensus.io/plugin/ochttp"
	"go.opencensus.io/trace"
)

func main() {
	// Create and register a OpenCensus Stackdriver Trace exporter.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{
		ProjectID: os.Getenv("GOOGLE_CLOUD_PROJECT"),
	})
	if err != nil {
		log.Fatal(err)
	}
	trace.RegisterExporter(exporter)

	// By default, traces will be sampled relatively rarely. To change the
	// sampling frequency for your entire program, call ApplyConfig. Use a
	// ProbabilitySampler to sample a subset of traces, or use AlwaysSample to
	// collect a trace on every run.
	//
	// Be careful about using trace.AlwaysSample in a production application
	// with significant traffic: a new trace will be started and exported for
	// every request.
	trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})

	client := &http.Client{
		Transport: &ochttp.Transport{
			// Use Google Cloud propagation format.
			Propagation: &propagation.HTTPFormat{},
		},
	}

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		req, _ := http.NewRequest("GET", "https://www.google.com", nil)

		// The trace ID from the incoming request will be
		// propagated to the outgoing request.
		req = req.WithContext(r.Context())

		// The outgoing request will be traced with r's trace ID.
		resp, err := client.Do(req)
		if err != nil {
			log.Fatal(err)
		}
		// Because we don't read the resp.Body, need to manually call Close().
		resp.Body.Close()
	})
	http.Handle("/foo", handler)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	log.Printf("Listening on port %s", port)

	// Use an ochttp.Handler in order to instrument OpenCensus for incoming
	// requests.
	httpHandler := &ochttp.Handler{
		// Use the Google Cloud propagation format.
		Propagation: &propagation.HTTPFormat{},
	}
	if err := http.ListenAndServe(":"+port, httpHandler); err != nil {
		log.Fatal(err)
	}
}

Traces ansehen

Nach der Bereitstellung können Sie die Traces in der Console sehen.

Trace-Anzeige öffnen

Problembehebung

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

Hochladen von Spans für den Go OpenCensus-Exporter schlägt fehl

Die folgenden Fehler treten auf, wenn die vom Exporter verwendete Bundler-Bibliothek nicht die Anzahl der Spans verwalten kann, die die Anwendung generiert und hochlädt:

OpenCensus Stackdriver exporter: failed to upload span: buffer full
OpenCensus Stackdriver exporter: failed to upload 183 spans: buffer full

Versuchen Sie Folgendes, um dieses Problem zu beheben:

  • Erhöhen Sie in der Struktur Options, die an den Konstruktor traceExporter übergeben wird, den Wert des Felds TraceSpansBufferMaxBytes. Dieses optionale Feld gibt die maximale Anzahl von Bytes an, die für die Pufferung von Spans verwendet werden. Der Standardwert ist 8 MB.

  • Verringern Sie die Werte für die folgenden Felder im Objekt Options, das an den Konstruktor traceExporter übergeben wird:

    • BundleDelayThreshold: Dieses optionale Feld gibt die maximale Zeit an, die der Exporter warten soll, bevor Trace-Spans hochgeladen werden. Der Standardwert dieses Felds beträgt zwei Sekunden.

    • BundleCountThreshold: Dieses optionale Feld gibt die Anzahl der Spans an, die zwischengespeichert werden können. Der Standardwert dieses Felds ist 50.

  • Exportieren Sie weniger Spans. Konfigurieren Sie zur Reduzierung der Anzahl der zu exportierenden Spans einen globalen Sampler oder übergeben Sie einen Sampler an jeden StartSpan. Beispielcode und weitere Informationen zu diesen Konfigurationen finden Sie unter OpenCensus Sampling.

Ressourcen