Traces und Messwerte mit Go generieren

In diesem Dokument wird beschrieben, wie Sie eine Go-Anwendung ändern, um Traces und mithilfe des Open-Source-Frameworks OpenTelemetry und wie Sie strukturierte JSON-Logs in Standard-out schreiben. Dieses Dokument enthält auch Informationen zu einer Beispiel-App, die Sie installieren und ausführen können. Die App ist so konfiguriert, dass Messwerte, Traces und Logs generiert werden.

Weitere Informationen zur Instrumentierung finden Sie in den folgenden Dokumenten:

Kontext

Context von OpenTelemetry ist ein Mechanismus zur Ausführung von Ausführungsbereichen. innerhalb eines Prozesses in allen APIs. Eine wichtige Verwendung von Kontext besteht darin, aktuell aktiven Span, sodass er geändert oder als übergeordnetes Element neue Spans an, wenn sie erstellt werden. Zusammenfassung:

  • Kontext bezieht sich auf den Mechanismus für die Weitergabe. Werte auf Ausführungsebene, einschließlich des aktuellen aktiven Spans, über APIs hinweg innerhalb eines Prozesses.

  • Span-Kontext ist ein unveränderliches Objekt in jedem Span, enthält die Trace-ID, die Span-ID sowie Flags und Status für den Trace.

  • Die Propagation ist der Mechanismus, der Kontext verschiebt. zwischen Diensten und Prozessen.

Der Bereich context.Context der Go-Standardbibliothek enthält ebenfalls über API-Grenzen hinweg nutzen. Normalerweise empfangen Handler-Funktionen in einem Server eines eingehenden Context und leiten es über die Aufrufkette an eine beliebige Kunden, die ausgehende Anfragen stellen.

Die Standardbibliothek context.Context von Go wird als Implementierung von OpenTelemetry Context in Go.

Hinweise

Cloud Logging, Cloud Monitoring, and Cloud Trace APIs aktivieren.

Aktivieren Sie die 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:

  1. Hauptfunktion konfigurieren
  2. OpenTelemetry konfigurieren
  3. Strukturiertes Logging konfigurieren
  4. Dem HTTP-Server Instrumentierung hinzufügen
  5. Trace-Spans mit Logs und Messwerten verknüpfen
  6. Dem HTTP-Client Instrumentierung hinzufügen
  7. Strukturierte Logs schreiben

Hauptfunktion konfigurieren

Um die Anwendung für das Schreiben strukturierter Logs, das Erfassen von Messwerten und mit OpenTelemetry zu verfolgen, aktualisieren Sie die Funktion main auf Konfigurieren Sie das strukturierte Go-Logging-Paket slog und konfigurieren Sie OpenTelemetry.

Das folgende Codebeispiel zeigt eine main-Funktion, die zwei Hilfsfunktionen setupLogging() und setupOpenTelemetry(). Diese Helfer das Logging-Paket und OpenTelemetry konfigurieren.

Um das vollständige Beispiel anzusehen, klicken Sie auf Mehr und wählen Sie Auf GitHub ansehen

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, verknüpfen Sie die Logs mit dem Trace müssen Sie „Go“-Context an den Protokollierungsmodus übergeben. Weitere Informationen siehe Abschnitt Strukturierte Logs schreiben Dokument.

OpenTelemetry konfigurieren

So erfassen und exportieren Sie Traces und Messwerte mithilfe der OTLP-Protokoll, konfigurieren Sie das globale TracerProvider und MeterProvider Instanzen. Das folgende Codebeispiel veranschaulicht die setupOpenTelemetry-Funktion. Dieser wird über die Funktion main aufgerufen:

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 der globale TextMapPropagator so konfiguriert, dass er den Parameter Format W3C Trace Context zur Weitergabe von Trace Kontext. Diese Konfiguration gewährleistet, dass Spans die richtige hierarchische Beziehung in einem Trace haben.

Um sicherzustellen, dass alle ausstehenden Telemetriedaten gelöscht und Verbindungen geschlossen werden ordnungsgemäß funktioniert, gibt die Funktion setupOpenTelemetry eine Funktion mit dem Namen shutdown, der diese Aktionen ausführt.

Strukturiertes Logging konfigurieren

So fügen Sie die Trace-Informationen in die geschriebenen JSON-formatierten Logs ein: Konfigurieren Sie das strukturierte Go-Logging-Paket slog für die Standardausgabe. Das folgende Codebeispiel veranschaulicht die setupLogging-Funktion. Dieser wird über die Funktion main aufgerufen:

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

Der vorherige Code ruft die Funktion handlerWithSpanContext auf, die extrahiert aus der Instanz Context und fügt diese Informationen als Attribute hinzu einem Protokoll hinzu. 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
}

Instrumentierung zum HTTP-Server hinzufügen

So fügen Sie den Anfragen, die vom HTTP-Server, verwenden Sie OpenTelemetry. Im folgenden Beispiel wird der otelhttp-Handler verwendet. für die Weitergabe von Kontext sowie für die Trace- und Messwertinstrumentierung:

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 das globale TracerProvider-, MeterProvider- und TextMapPropagator-Instanzen. Die Die setupOpenTelemetry-Funktion konfiguriert diese Instanzen.

Trace-Spans mit Logs und Messwerten verknüpfen

Um Server- und Client-Spans zu verknüpfen und Messwerte und Logs zu verknüpfen, übergeben Sie den Rufen Sie die Context-Instanz zur HTTP-Anfrage auf und wenn Sie Logs schreiben. Das folgende Beispiel zeigt einen Routing-Handler, der die Gehen Sie zur Context-Instanz und übergeben Sie diese Instanz an den Protokollierungs- und den callSingle, die eine ausgehende HTTP-Anfrage sendet:

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.

Fügen Sie dem HTTP-Client Instrumentierung hinzu

Um den Trace-Kontext in ausgehende HTTP-Anfragen einzufügen und Trace- und Messwertinstrumentierung die Funktion otelhttp.Get aufrufen. 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()
}

Im vorherigen Code verwendet der otelhttp-Handler das globale TracerProvider-, MeterProvider- und TextMapPropagator-Instanzen. Die Die setupOpenTelemetry-Funktion konfiguriert diese Instanzen.

Strukturierte Logs schreiben

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

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:

  1. Aktivieren Sie Cloud Shell in der Google Cloud Console.

    Cloud Shell aktivieren

    Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.

  2. Klonen Sie das Repository:

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

  3. Gehen Sie zum OpenTelemetry-Verzeichnis:

    cd golang-samples/opentelemetry/instrumentation

  4. 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 Anforderungsinhalts für /multi auf und /single HTTP-Routen. Die Messwerte für diesen Messwert sind kumulativ, Das bedeutet, dass jeder Wert die Summe seit der Sammlung von Werten darstellt begonnen.

  • Prometheus/http_server_response_content_length_total/counter zeichnet auf Länge des Antwortinhalts für die HTTP-Routen /multi und /single Die Messwerte für diesen Messwert sind kumulativ.

So rufen Sie die von der Beispielanwendung generierten Messwerte auf:

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

  2. 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.
  3. 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:

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

  2. Wählen Sie im Streudiagramm einen Trace mit dem URI /multi aus.

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

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

  1. 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 Monitoring ist.

  2. Suchen Sie ein Log mit der Beschreibung handle /multi request.

    Erweitern Sie den Logeintrag, um die Details des Logs aufzurufen. Im jsonPayload enthält, gibt es einen Eintrag mit der Bezeichnung subRequests. Dieser Eintrag wurde durch eine Anweisung in der Funktion handleMulti hinzugefügt.

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

Nächste Schritte