Diese Seite wurde von der Cloud Translation API übersetzt.

Traces und Messwerte mit Go generieren

In diesem Dokument wird beschrieben, wie Sie eine Go-Anwendung ändern, um Trace- und Messwertdaten mit dem Open-Source-Framework OpenTelemetry zu erfassen und strukturierte JSON-Logs in das Standard-Out-Format zu schreiben. Dieses Dokument enthält auch Informationen zu einer Beispielanwendung, die Sie installieren und ausführen können. Die Anwendung ist so konfiguriert, dass Messwerte, Traces und Logs generiert werden.

Weitere Informationen zu Instrumentierung finden Sie in den folgenden Dokumenten:

Kontext

Der Kontext von OpenTelemetry ist ein Mechanismus, mit dem Werte auf Ausführungsebene über APIs innerhalb eines Prozesses übertragen werden. Eine wichtige Verwendung des Kontexts besteht darin, die aktuelle aktive Span zu übergeben, damit sie geändert oder beim Erstellen als übergeordnetes Element für neue Spans referenziert werden kann. Zusammenfassung:

Der Kontext bezieht sich auf den Mechanismus, mit dem Werte auf Ausführungsebene, einschließlich der aktuellen aktiven Spanne, über APIs innerhalb eines Prozesses weitergegeben werden.
Der Span-Kontext ist ein unveränderliches Objekt für jeden Span, das die Trace-ID, die Span-ID sowie Flags und den Status für den Trace enthält.
Die Weitergabe ist der Mechanismus, mit dem der Kontext zwischen Diensten und Prozessen übertragen wird.

Die context.Context der Go-Standardbibliothek überträgt auch Werte mit Bereich über API-Grenzen hinweg. Normalerweise empfangen Handlerfunktionen auf einem Server eine eingehende Context und leiten sie über die Aufrufabfolge an alle Clients weiter, die ausgehende Anfragen stellen.

Die Go-Standardbibliothek context.Context wird als Implementierung des OpenTelemetry-Kontexts in Go verwendet.

Hinweise

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Anwendung für die Erfassung von Traces, Messwerten und Logs instrumentieren

Führen Sie die folgenden Schritte aus, um Ihre Anwendung so zu instrumentieren, dass Trace- und Messwertdaten erfasst und strukturiertes JSON in die Standardausgabe geschrieben wird, wie in den folgenden Abschnitten dieses Dokuments beschrieben:

Hauptfunktion konfigurieren
OpenTelemetry konfigurieren
Strukturiertes Logging konfigurieren
HTTP-Server instrumentieren
Link-Trace-Spannen mit Logs und Messwerten
HTTP-Client Instrumentation hinzufügen
Strukturierte Logs schreiben

Hauptfunktion konfigurieren

Wenn Sie die Anwendung so konfigurieren möchten, dass strukturierte Logs geschrieben und Messwerte und Trace-Daten mit OpenTelemetry erfasst werden, aktualisieren Sie die Funktion main, um das Go-Paket für strukturiertes Logging, slog, und OpenTelemetry zu konfigurieren.

Das folgende Codebeispiel zeigt eine main-Funktion, die zwei Hilfsfunktionen aufruft: setupLogging() und setupOpenTelemetry(). Mit diesen Hilfsfunktionen werden das Logging-Paket und OpenTelemetry konfiguriert.

Wenn Sie sich das vollständige Beispiel ansehen möchten, klicken Sie auf Mehr und wählen Sie dann Auf GitHub ansehen aus.

func main() {
	ctx := context.Background()

	// Setup logging
	setupLogging()

	// Setup metrics, tracing, and context propagation
	shutdown, err := setupOpenTelemetry(ctx)
	if err != nil {
		slog.ErrorContext(ctx, "error setting up OpenTelemetry", slog.Any("error", err))
		os.Exit(1)
	}

	// Run the http server, and shutdown and flush telemetry after it exits.
	slog.InfoContext(ctx, "server starting...")
	if err = errors.Join(runServer(), shutdown(ctx)); err != nil {
		slog.ErrorContext(ctx, "server exited with error", slog.Any("error", err))
		os.Exit(1)
	}
}

Nachdem Sie das Logging-Paket konfiguriert haben, müssen Sie die Go-Context an den Logging-Client übergeben, um Ihre Protokolle mit Ihren Trace-Daten zu verknüpfen. Weitere Informationen finden Sie im Abschnitt Strukturierte Protokolle schreiben dieses Dokuments.

OpenTelemetry konfigurieren

Wenn Sie Traces und Messwerte mit dem OTLP-Protokoll erfassen und exportieren möchten, konfigurieren Sie die globalen Instanzen TracerProvider und MeterProvider. Das folgende Codebeispiel zeigt die Funktion setupOpenTelemetry, die von der Funktion main aufgerufen wird:

func setupOpenTelemetry(ctx context.Context) (shutdown func(context.Context) error, err error) {
	var shutdownFuncs []func(context.Context) error

	// shutdown combines shutdown functions from multiple OpenTelemetry
	// components into a single function.
	shutdown = func(ctx context.Context) error {
		var err error
		for _, fn := range shutdownFuncs {
			err = errors.Join(err, fn(ctx))
		}
		shutdownFuncs = nil
		return err
	}

	// Configure Context Propagation to use the default W3C traceparent format
	otel.SetTextMapPropagator(autoprop.NewTextMapPropagator())

	// Configure Trace Export to send spans as OTLP
	texporter, err := autoexport.NewSpanExporter(ctx)
	if err != nil {
		err = errors.Join(err, shutdown(ctx))
		return
	}
	tp := trace.NewTracerProvider(trace.WithBatcher(texporter))
	shutdownFuncs = append(shutdownFuncs, tp.Shutdown)
	otel.SetTracerProvider(tp)

	// Configure Metric Export to send metrics as OTLP
	mreader, err := autoexport.NewMetricReader(ctx)
	if err != nil {
		err = errors.Join(err, shutdown(ctx))
		return
	}
	mp := metric.NewMeterProvider(
		metric.WithReader(mreader),
	)
	shutdownFuncs = append(shutdownFuncs, mp.Shutdown)
	otel.SetMeterProvider(mp)

	return shutdown, nil
}

Im vorherigen Codebeispiel wird die globale TextMapPropagator so konfiguriert, dass das Format W3C Trace Context zur Weitergabe von Trace-Kontext verwendet wird. Diese Konfiguration gewährleistet, dass Spans die richtige hierarchische Beziehung in einem Trace haben.

Damit alle ausstehenden Telemetriedaten geleert und Verbindungen ordnungsgemäß geschlossen werden, gibt die setupOpenTelemetry-Funktion eine Funktion namens shutdown zurück, die diese Aktionen ausführt.

Strukturiertes Logging konfigurieren

Wenn Sie die Trace-Informationen in die JSON-formatierten Logs aufnehmen möchten, die in die Standardausgabe geschrieben werden, konfigurieren Sie das Go-Paket für strukturiertes Logging, slog. Das folgende Codebeispiel zeigt die Funktion setupLogging, die von der Funktion main aufgerufen wird:

func setupLogging() {
	// Use json as our base logging format.
	jsonHandler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: replacer})
	// Add span context attributes when Context is passed to logging calls.
	instrumentedHandler := handlerWithSpanContext(jsonHandler)
	// Set this handler as the global slog handler.
	slog.SetDefault(slog.New(instrumentedHandler))
}

Im vorherigen Code wird die Funktion handlerWithSpanContext aufgerufen, die Informationen aus der Context-Instanz extrahiert und diese Informationen als Attribute einem Log hinzufügt. Mit diesen Attributen können Sie dann ein Log mit einem Trace korrelieren:

logging.googleapis.com/trace: Der Ressourcenname des Trace, das mit dem Logeintrag verknüpft ist.
logging.googleapis.com/spanId: Die Span-ID mit dem Trace, das dem Logeintrag zugeordnet ist.
logging.googleapis.com/trace_sampled: Der Wert dieses Felds muss true oder false sein.

Weitere Informationen zu diesen Feldern finden Sie in der LogEntry-Struktur.

func handlerWithSpanContext(handler slog.Handler) *spanContextLogHandler {
	return &spanContextLogHandler{Handler: handler}
}

// spanContextLogHandler is an slog.Handler which adds attributes from the
// span context.
type spanContextLogHandler struct {
	slog.Handler
}

// Handle overrides slog.Handler's Handle method. This adds attributes from the
// span context to the slog.Record.
func (t *spanContextLogHandler) Handle(ctx context.Context, record slog.Record) error {
	// Get the SpanContext from the golang Context.
	if s := trace.SpanContextFromContext(ctx); s.IsValid() {
		// Add trace context attributes following Cloud Logging structured log format described
		// in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
		record.AddAttrs(
			slog.Any("logging.googleapis.com/trace", s.TraceID()),
		)
		record.AddAttrs(
			slog.Any("logging.googleapis.com/spanId", s.SpanID()),
		)
		record.AddAttrs(
			slog.Bool("logging.googleapis.com/trace_sampled", s.TraceFlags().IsSampled()),
		)
	}
	return t.Handler.Handle(ctx, record)
}

func replacer(groups []string, a slog.Attr) slog.Attr {
	// Rename attribute keys to match Cloud Logging structured log format
	switch a.Key {
	case slog.LevelKey:
		a.Key = "severity"
		// Map slog.Level string values to Cloud Logging LogSeverity
		// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
		if level := a.Value.Any().(slog.Level); level == slog.LevelWarn {
			a.Value = slog.StringValue("WARNING")
		}
	case slog.TimeKey:
		a.Key = "timestamp"
	case slog.MessageKey:
		a.Key = "message"
	}
	return a
}

HTTP-Server instrumentieren

Verwenden Sie OpenTelemetry, um den vom HTTP-Server verarbeiteten Anfragen Trace- und Messwertinstrumentierung hinzuzufügen. Im folgenden Beispiel wird der otelhttp-Handler zum Übertragen des Kontexts und für die Trace- und Messwertinstrumentierung verwendet:

func runServer() error {
	handleHTTP("/single", handleSingle)
	handleHTTP("/multi", handleMulti)

	return http.ListenAndServe(":8080", nil)
}

// handleHTTP handles the http HandlerFunc on the specified route, and uses
// otelhttp for context propagation, trace instrumentation, and metric
// instrumentation.
func handleHTTP(route string, handleFn http.HandlerFunc) {
	instrumentedHandler := otelhttp.NewHandler(otelhttp.WithRouteTag(route, handleFn), route)

	http.Handle(route, instrumentedHandler)
}

Im vorherigen Code verwendet der otelhttp-Handler die globalen Instanzen TracerProvider, MeterProvider und TextMapPropagator. Diese Instanzen werden mit der Funktion setupOpenTelemetry konfiguriert.

Trace-Spans mit Logs und Messwerten verknüpfen

Wenn Sie Server- und Client-Spannen verknüpfen und Messwerte und Protokolle zuordnen möchten, übergeben Sie die Go Context-Instanz an die HTTP-Anfrage und beim Schreiben von Protokollen. Das folgende Beispiel zeigt einen Routen-Handler, der die Go-Context-Instanz extrahiert und an den Logging-Dienst und die callSingle-Funktion weitergibt, die eine ausgehende HTTP-Anfrage stellt:

func handleMulti(w http.ResponseWriter, r *http.Request) {
	subRequests := 3 + rand.Intn(4)
	// Write a structured log with the request context, which allows the log to
	// be linked with the trace for this request.
	slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))

	err := computeSubrequests(r, subRequests)
	if err != nil {
		http.Error(w, err.Error(), http.StatusBadGateway)
		return
	}

	fmt.Fprintln(w, "ok")
}

Im vorherigen Code ruft der Funktionsaufruf r.Context() das Go-Context aus der HTTP-Anfrage ab.

Dem HTTP-Client Instrumentierung hinzufügen

Rufen Sie die Funktion otelhttp.Get auf, um den Trace-Kontext in ausgehende HTTP-Anfragen einzuschleusen und Trace- und Messwertinstrumentierung hinzuzufügen. Im folgenden Beispiel führt die Funktion callSingle diese Aktion aus:

func callSingle(ctx context.Context) error {
	// otelhttp.Get makes an http GET request, just like net/http.Get.
	// In addition, it records a span, records metrics, and propagates context.
	res, err := otelhttp.Get(ctx, "http://localhost:8080/single")
	if err != nil {
		return err
	}

	return res.Body.Close()
}

Strukturierte Logs schreiben

Verwenden Sie das Go-Paket für strukturierte Logging, slog, um strukturierte Logs zu schreiben, die mit einem Trace verknüpft sind, und übergeben Sie die Go-Instanz Context an den Logger. Die Go Context-Instanz ist erforderlich, wenn Sie ein Protokoll mit einem Span verknüpfen möchten. Die folgende Anweisung zeigt beispielsweise, wie die Methode InfoContext für slog aufgerufen wird und wie das Feld subRequests der JSON-Instanz hinzugefügt wird:

slog.InfoContext(r.Context(), "handle /multi request", slog.Int("subRequests", subRequests))

Beispielanwendung ausführen, die für die Erfassung von Telemetriedaten konfiguriert ist

Die Beispielanwendung verwendet anbieterneutrale Formate, einschließlich JSON für Logs und OTLP für Messwerte und Traces. In diesem Beispiel wird die OpenTelemetry-Collector verwendet, die mit Google-Exportern konfiguriert wurde, um die Telemetrie an Google Cloud weiterzuleiten. Der Lastgenerator in der Anwendung gibt Anfragen an die Routen der Anwendung aus.

Anwendung herunterladen und bereitstellen

So führen Sie das Beispiel aus:

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Klonen Sie das Repository:

git clone https://github.com/GoogleCloudPlatform/golang-samples

Rufen Sie das OpenTelemetry-Verzeichnis auf:

cd golang-samples/opentelemetry/instrumentation

Erstellen Sie das Beispiel und führen Sie es aus:

docker compose up --abort-on-container-exit

Wenn Sie Cloud Shell nicht ausführen, führen Sie die Anwendung mit der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS aus, die auf eine Datei mit Anmeldedaten verweist. Standardanmeldedaten für Anwendungen stellt eine Datei mit Anmeldedaten unter $HOME/.config/gcloud/application_default_credentials.json bereit.

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Messwerte ansehen

Die OpenTelemetry-Instrumentierung in der Beispielanwendung generiert Prometheus-Messwerte, die Sie mit dem Metrics Explorer aufrufen können:

Prometheus/http_server_duration/histogram zeichnet die Dauer von Serveranfragen auf und speichert die Ergebnisse in einem Histogramm.
Prometheus/http_server_request_content_length_total/counter zeichnet die Länge des Anfrageinhalts für die HTTP-Routen /multi und /single auf. Die Messungen für diesen Messwert sind kumulativ. Das bedeutet, dass jeder Wert die Summe seit Beginn der Werterfassung darstellt.
Prometheus/http_server_response_content_length_total/counter zeichnet die Länge des Antwortinhalts für die HTTP-Routen /multi und /single auf. Die Messungen für diesen Messwert sind kumulativ.

So rufen Sie die von der Beispielanwendung generierten Messwerte auf:

Rufen Sie in der Google Cloud Console die Seite Metrics Explorer auf.
Zum Metrics Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.
Maximieren Sie im Element Messwert das Menü Messwert auswählen, geben Sie http_server in die Filterleiste ein und wählen Sie dann über die Untermenüs einen bestimmten Ressourcentyp und Messwert aus:
1. Wählen Sie im Menü Aktive Ressourcen die Option Prometheus-Ziel aus.
2. Wählen Sie im Menü Aktive Messwertkategorien die Option Http aus.
3. Wählen Sie im Menü Aktive Messwerte einen Messwert aus.
4. Klicken Sie auf Anwenden.
Konfigurieren Sie, wie die Daten angezeigt werden.
Wenn die Messungen für einen Messwert kumulativ sind, normalisiert Metrics Explorer die gemessenen Daten automatisch nach dem Ausrichtungszeitraum. Dadurch wird im Diagramm eine Rate angezeigt. Weitere Informationen finden Sie unter Arten, Typen und Umwandlungen.

Wenn ganzzahlige oder doppelte Werte gemessen werden, z. B. mit den beiden counter-Messwerten, summiert der Metrics Explorer automatisch alle Zeitachsen. Wenn Sie die Daten für die HTTP-Routen /multi und /single aufrufen möchten, legen Sie im ersten Menü des Eintrags Aggregation die Option Keine fest.

Weitere Informationen zum Konfigurieren eines Diagramms finden Sie unter Messwerte bei Verwendung von Metrics Explorer auswählen.

Traces ansehen

So rufen Sie Ihre Trace-Daten auf:

Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:
Zum Trace Explorer

Sie können diese Seite auch über die Suchleiste finden.
Wählen Sie im Streudiagramm einen Trace mit dem URI /multi aus.
Wählen Sie im Gantt-Diagramm im Bereich Trace-Details den Span mit der Bezeichnung /multi aus.

Ein Steuerfeld mit Informationen zur HTTP-Anfrage wird geöffnet. Zu diesen Details gehören die Methode, der Statuscode, die Anzahl der Byte und der User-Agent des Aufrufers.
Wählen Sie den Tab Logs und Ereignisse aus, um die mit diesem Trace verknüpften Logs aufzurufen.

Auf dem Tab werden einzelne Logs angezeigt. Maximieren Sie den Logeintrag, um die Details anzusehen. Sie können auch auf Logs ansehen klicken und das Log mit dem Log-Explorer aufrufen.

Weitere Informationen zur Verwendung von Cloud Trace-Explorer finden Sie unter Traces suchen und untersuchen.

Logs ansehen

Im Log-Explorer können Sie Ihre Logs prüfen und sich auch die zugehörigen Traces ansehen, sofern vorhanden.

Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.
Zum Log-Explorer

Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.
Suchen Sie ein Log mit der Beschreibung handle /multi request.

Erweitern Sie den Logeintrag, um die Details des Logs aufzurufen. Im Feld jsonPayload befindet sich ein Eintrag mit der Bezeichnung subRequests. Dieser Eintrag wurde durch eine Anweisung in der handleMulti-Funktion hinzugefügt.
Klicken Sie auf Traces für einen Logeintrag mit der Nachricht "handle /multi request" und wählen Sie dann Trace-Details anzeigen aus.

Der Bereich Trace-Details wird geöffnet und zeigt den ausgewählten Trace an.

Weitere Informationen zur Verwendung des Log-Explorers finden Sie unter Logs mit dem Log-Explorer ansehen.