In diesem Dokument wird beschrieben, wie Sie eine Java-Anwendung so ändern, dass Trace- und Messwertdaten mithilfe des Open-Source-Frameworks OpenTelemetry erfasst werden, und wie Sie strukturierte JSON-Logs zum Standard-Out schreiben. Dieses Dokument enthält auch Informationen zu einer Java Spring Boot-Beispielanwendung, die Sie installieren und ausführen können. Die Anwendung ist so konfiguriert, dass Messwerte, Traces und Logs generiert werden. Die Schritte sind immer die gleichen, unabhängig davon, ob Sie das Spring Boot Framework verwenden oder nicht.
Weitere Informationen zur Instrumentierung finden Sie in den folgenden Dokumenten:
Manuelle und automatische Instrumentierung
Die in diesem Dokument beschriebene Instrumentierung verwendet die automatische Instrumentierung von OpenTelemetry, um Telemetriedaten an Ihr Google Cloud-Projekt zu senden. Bei Java bezieht sich automatische Instrumentierung auf das dynamische Einschleusen von Bytecode in Bibliotheken und Frameworks zur Erfassung von Telemetriedaten. Die automatische Instrumentierung kann Telemetrie für Elemente wie eingehende und ausgehende HTTP-Aufrufe erfassen. Weitere Informationen finden Sie unter Automatische Instrumentierung für Java.
OpenTelemetry bietet außerdem eine API, mit der Sie Ihrem eigenen Code benutzerdefinierte Instrumentierung hinzufügen können. Bei OpenTelemetry wird dies als manuelle Instrumentierung bezeichnet. In diesem Dokument wird die manuelle Instrumentierung nicht beschrieben. Beispiele und Informationen zu diesem Thema finden Sie unter Manuelle Instrumentierung.
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:
- Anwendung für die Verwendung des OpenTelemetry-Java-Agent konfigurieren
- OpenTelemetry konfigurieren
- Strukturiertes Logging konfigurieren
- Strukturierte Logs schreiben
Anwendung für die Verwendung des OpenTelemetry-Java-Agent konfigurieren
Wenn Sie die Anwendung für das Schreiben strukturierter Logs und das Erfassen von Messwerten und Trace-Daten mithilfe von OpenTelemetry konfigurieren möchten, aktualisieren Sie den Aufruf Ihrer Anwendung, um den OpenTelemetry-Java-Agent zu verwenden. Diese Methode zur Instrumentierung Ihrer Anwendung wird als automatische Instrumentierung bezeichnet, da der Anwendungscode nicht geändert werden muss.
Das folgende Codebeispiel zeigt ein Dockerfile, das die JAR-Datei des OpenTelemetry-Java-Agent herunterlädt und den Befehlszeilenaufruf aktualisiert, um das Flag -javaagent
zu übergeben.
Um das vollständige Beispiel anzusehen, klicken Sie auf more_vert Mehr und wählen Sie dann Auf GitHub ansehen aus.
Alternativ können Sie das Flag -javaagent
auch in der Umgebungsvariablen JAVA_TOOL_OPTIONS
festlegen:
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"
OpenTelemetry konfigurieren
In der Standardkonfiguration für den OpenTelemetry-Java-Agent werden Traces und Messwerte mithilfe des OTLP-Protokolls exportiert. Außerdem wird OpenTelemetry 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.
Weitere Informationen und Konfigurationsoptionen finden Sie unter Automatische Instrumentierung von OpenTelemetry Java.
Strukturiertes Logging konfigurieren
Wenn Sie die Trace-Informationen in die JSON-formatierten Logs aufnehmen möchten, die in die Standardausgabe geschrieben werden, konfigurieren Sie Ihre Anwendung so, dass strukturierte Logs im JSON-Format ausgegeben werden. Wir empfehlen die Verwendung von Log4j2 als Logging-Implementierung.
Das folgende Codebeispiel zeigt eine log4j2.xml
-Datei, die so konfiguriert ist, dass strukturierte JSON-Logs mithilfe des JSON-Vorlagenlayouts ausgegeben werden:
Die vorherige Konfiguration extrahiert Informationen zum aktiven Span aus dem zugeordneten Diagnosekontext von SLF4J und fügt diese Informationen als Attribute dem Log 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 musstrue
oderfalse
sein.
Weitere Informationen zu diesen Feldern finden Sie in der LogEntry
-Struktur.
Strukturierte Logs schreiben
Wenn Sie strukturierte Logs schreiben möchten, die mit einem Trace verknüpft sind, verwenden Sie die SLF4J Logging API. Die folgende Anweisung zeigt beispielsweise, wie die Methode Logger.info()
aufgerufen wird:
logger.info("handle /multi request with subRequests={}", subRequests);
Der OpenTelemetry-Java-Agent füllt automatisch den zugeordneten Diagnosekontext des SLF4J mit dem Span-Kontext des aktuellen aktiven Spans im OpenTelemetry-Kontext. Der zugeordnete Diagnosekontext wird dann in die JSON-Logs eingefügt, wie unter Strukturiertes Logging konfigurieren beschrieben.
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 sowie das Spring Boot Framework. In diesem Beispiel wird die mit Google-Exportern konfigurierte OpenTelemetry-Collector
verwendet, um die Telemetrie an Google Cloud weiterzuleiten. Die Anwendung hat zwei Endpunkte:
Der
/multi
-Endpunkt wird von derhandleMulti
-Funktion verarbeitet. Der Lastgenerator in der Anwendung gibt Anfragen an den Endpunkt/multi
aus. Wenn dieser Endpunkt eine Anfrage empfängt, sendet er zwischen drei und sieben Anfragen an den Endpunkt/single
auf dem lokalen Server.Der
/single
-Endpunkt wird von derhandleSingle
-Funktion verarbeitet. Wenn dieser Endpunkt eine Anfrage empfängt, wechselt er für eine kurze Verzögerung in den Ruhemodus und antwortet dann mit einem String.
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/opentelemetry-operations-java
Gehen Sie zum Beispielverzeichnis:
cd opentelemetry-operations-java/examples/instrumentation-quickstart
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_milliseconds/histogram
zeichnet die Dauer von Serveranfragen auf und speichert die Ergebnisse in einem Histogramm.Prometheus/http_client_duration_milliseconds/histogram
zeichnet die Dauer von Clientanfragen auf und speichert die Ergebnisse in einem Histogramm.
-
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 Übernehmen.
- 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.
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