In diesem Dokument wird beschrieben, wie Sie eine Go-Anwendung ändern, um Trace- und Messwertdaten mit dem Open-Source-Framework OpenTelemetry zu erfassen, und wie Sie strukturierte JSON-Logs zum Standard-Out 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 zur Instrumentierung finden Sie in den folgenden Dokumenten:
Kontext
Context von OpenTelemetry ist ein Mechanismus zum Übertragen von ausführungsbezogenen Werten über APIs innerhalb eines Prozesses. Kontext ist wichtig, um den aktuellen aktiven Span zu übernehmen, damit er geändert oder als übergeordnetes Element neuer Spans referenziert werden kann, wenn sie erstellt werden. Zusammenfassung:
Kontext bezieht sich auf den Mechanismus zur Weitergabe von Werten auf Ausführungsebene, einschließlich des aktuellen aktiven Spans, über die APIs innerhalb eines Prozesses.
Span-Kontext ist ein unveränderliches Objekt in jedem Span, der die Trace-ID, die Span-ID sowie Flags und Status für den Trace enthält.
Die Weitergabe ist der Mechanismus, der Kontext zwischen Diensten und Prozessen verschiebt.
Die context.Context
der Go-Standardbibliothek überträgt auch Bereichswerte über API-Grenzen. Normalerweise empfangen Handler-Funktionen auf einem Server ein eingehendes Context
und leiten es über die Aufrufkette an alle Clients weiter, die ausgehende Anfragen senden.
Die Standardbibliothek context.Context
von Go wird als Implementierung von OpenTelemetry Context in Go verwendet.
Hinweise
Cloud Logging, Cloud Monitoring, and Cloud Trace APIs aktivieren.
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
- Dem HTTP-Server Instrumentierung hinzufügen
- Trace-Spans mit Logs und Messwerten verknüpfen
- Dem HTTP-Client Instrumentierung hinzufügen
- Strukturierte Logs schreiben
Hauptfunktion konfigurieren
Wenn Sie die Anwendung für das Schreiben strukturierter Logs und das Erfassen von Messwerten und Trace-Daten mit OpenTelemetry konfigurieren möchten, aktualisieren Sie die Funktion main
, um das strukturierte Go-Logging-Paket slog
und OpenTelemetry zu konfigurieren.
Das folgende Codebeispiel zeigt eine main
-Funktion, die die beiden Hilfsfunktionen setupLogging()
und setupOpenTelemetry()
aufruft. Diese Hilfsfunktionen konfigurieren das Logging-Paket und OpenTelemetry.
Um das vollständige Beispiel anzusehen, klicken Sie auf more_vert Mehr und wählen Sie dann Auf GitHub ansehen aus.
Wenn Sie die Logs nach der Konfiguration des Logging-Pakets mit den Trace-Daten verknüpfen möchten, müssen Sie das Go-Context
an den Logger übergeben. Weitere Informationen finden Sie in diesem Dokument im Abschnitt Strukturierte Logs schreiben.
OpenTelemetry konfigurieren
Konfigurieren Sie die globalen Instanzen TracerProvider
und MeterProvider
, um Traces und Messwerte mithilfe des OTLP-Protokolls zu erfassen und zu exportieren.
Das folgende Codebeispiel veranschaulicht die setupOpenTelemetry
-Funktion, die über die main
-Funktion aufgerufen wird:
Im vorherigen Codebeispiel wird das 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 gelöscht und Verbindungen ordnungsgemäß geschlossen werden, gibt die Funktion setupOpenTelemetry
eine Funktion namens shutdown
zurück, die diese Aktionen ausführt.
Strukturiertes Logging konfigurieren
Wenn Sie die Trace-Informationen in die JSON-formatierten Logs einfügen möchten, die in die Standardausgabe geschrieben werden, konfigurieren Sie das strukturierte Go-Logging-Paket slog
.
Das folgende Codebeispiel veranschaulicht die setupLogging
-Funktion, die über die main
-Funktion aufgerufen wird:
Der vorherige Code ruft die Funktion handlerWithSpanContext
auf, die Informationen aus der Instanz Context
extrahiert und als Attribute in ein 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 musstrue
oderfalse
sein.
Weitere Informationen zu diesen Feldern finden Sie in der LogEntry
-Struktur.
Instrumentierung zum HTTP-Server hinzufügen
Verwenden Sie OpenTelemetry, um den Anfragen, die vom HTTP-Server verarbeitet werden, Trace- und Messwertinstrumentierung hinzuzufügen. Im folgenden Beispiel wird der otelhttp
-Handler zur Weitergabe von Kontext sowie für die Trace- und Messwertinstrumentierung verwendet:
Im vorherigen Code verwendet der Handler otelhttp
die globalen Instanzen TracerProvider
, MeterProvider
und TextMapPropagator
. Die Funktion setupOpenTelemetry
konfiguriert diese Instanzen.
Trace-Spans mit Logs und Messwerten verknüpfen
Übergeben Sie die Context
-Instanz an die HTTP-Anfrage und wenn Sie Logs schreiben, um Server- und Client-Spans zu verknüpfen und Messwerte und Logs zu verknüpfen.
Das folgende Beispiel zeigt einen Routing-Handler, der die Go-Instanz Context
extrahiert und an den Listener und die Funktion callSingle
übergibt, die eine ausgehende HTTP-Anfrage sendet:
Im vorherigen Code ruft der Funktionsaufruf r.Context()
das Go-Context
aus der HTTP-Anfrage ab.
Fügen Sie dem HTTP-Client Instrumentierung hinzu
Rufen Sie die Funktion otelhttp.Get
auf, um den Trace-Kontext in ausgehende HTTP-Anfragen einzufügen und Trace- und Messwertinstrumentierung hinzuzufügen.
Im folgenden Beispiel führt die Funktion callSingle
diese Aktion aus:
Im vorherigen Code verwendet der Handler otelhttp
die globalen Instanzen TracerProvider
, MeterProvider
und TextMapPropagator
. Die Funktion setupOpenTelemetry
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-Paket slog
von Go 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 Methode InfoContext
für slog
aufgerufen wird und wie das Feld subRequests
zur 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:
-
Aktivieren Sie Cloud Shell in der Google Cloud Console.
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.
Klonen Sie das Repository:
git clone https://github.com/GoogleCloudPlatform/golang-samples
Gehen Sie zum OpenTelemetry-Verzeichnis:
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, was bedeutet, dass jeder Wert die Gesamtsumme seit Beginn der Wertesammlung 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 Messwerte für diesen Messwert sind kumulativ.
-
Rufen Sie in der Google Cloud Console die Seite leaderboard Metrics Explorer auf.
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:- Wählen Sie im Menü Aktive Ressourcen die Option Prometheus-Ziel aus.
- Wählen Sie im Menü Aktive Messwertkategorien die Option Http aus.
- Wählen Sie im Menü Aktive Messwerte einen Messwert aus.
- 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:
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.
Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.
Suchen Sie ein Log mit der Beschreibung
handle /multi request
.Erweitern Sie den Logeintrag, um die Details des Logs aufzurufen. Das Feld
jsonPayload
enthält einen Eintrag mit dem NamensubRequests
. Dieser Eintrag wurde durch eine Anweisung in der FunktionhandleMulti
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.
Nächste Schritte
- OpenTelemetry
- OTLP-Spezifikation
- Strukturiertes Logging
- Fehlerbehebung für Managed Service for Prometheus
- Fehlerbehebung für Cloud Trace