Zu Cloud Logging migrieren

Das Logging in Laufzeiten der zweiten Generation unterscheidet sich von den Laufzeiten der ersten Generation. Eine der größten Änderungen beim Upgrade auf neuere Laufzeiten ist, dass das vorintegrierte Logging mit App Engine in Laufzeiten der zweiten Generation nicht unterstützt wird und Logs nicht automatisch korreliert werden. Wenn Sie zu Laufzeiten der zweiten Generation migrieren, müssen Sie die Cloud Logging-Clientbibliothek verwenden.

In diesem Leitfaden wird beschrieben, wie Sie Ihre Anwendung für die Verwendung von Cloud Logging aktualisieren und fast dieselben Filter- und Logkorrelationsfunktionen wie bei der Logging-Integration in App Engine erreichen.

Cloud Logging ist ein Echtzeit-Log-Verwaltungssystem mit Unterstützung für Speicherung, Suche, Analyse und Monitoring. Cloud Logging erfasst automatisch Logs aus Google Cloud-Ressourcen. Sie können auch Logs von Ihren Anwendungen, lokalen Ressourcen und Ressourcen von anderen Cloud-Anbietern erfassen.

Wichtige Unterschiede

In der folgenden Tabelle werden die Unterschiede beim Logging zwischen Laufzeiten der ersten und zweiten Generation behandelt:

	Laufzeiten der ersten Generation	Laufzeiten der zweiten Generation
Anfrage- und Anwendungslogs (auch Anwendungslogs genannt)	App Engine bettet alle Anwendungslogs in das Anfragelog ein. Beim Logging in Laufzeiten der ersten Generation wird das Feld `protoPayload.line.logMessage` des Anfragelogs verwendet, um Anwendungslogs einzubetten.	App Engine bettet keine Anwendungslogs in das zugehörige Anfragelog ein. App Engine lässt das `protoPayload.line`-Attribut im Anfragelog weg. Anwendungslogs werden entsprechend Ihrer Logging-Methode weitergeleitet: `stdout` und `stderr`: Leitet Logs wie `print()` an `logs/stdout` oder `logs/stderr` weiter. Python-Logging-Modul nach der Einrichtung des Cloud Logging-Clients: Leitet alle Logs weiter, die vom Python-Root-Logging-Modul geschrieben wurden, z. B. `logging.info()` und `logging.error()` in `logs/python`. Wenn die Cloud Logging-Clientbibliothek für Python nicht für eine Korrelation eingerichtet ist, wird das Python-Root-Logging-Modul standardmäßig an `logs/stderr` weitergeleitet.
Logs im Log-Explorer ansehen	Laufzeiten der ersten Generation enthalten nur den Logtyp `appengine.googleapis.com/request_log`. Wenn Sie ein Anfragelog maximieren, sehen Sie die darunter verschachtelten Anwendungslogs.	Laufzeiten der zweiten Generation enthalten Logs aus mehreren Logtypen, z. B. Anfragelogs`appengine.googleapis.com/request_log` ,`stdout` ,`stderr` ,`logs/python` und abhängig davon, wie Ihre Anwendung Logs ausgibt. Google-interne Logs sind auch in `/var/log/google_init.log` verfügbar. Da Anwendungslogs nicht automatisch mit Anfragelogs korreliert werden, sind zusätzliche Schritte erforderlich, um die verschachtelte Ansicht der Anfrage- und Anwendungslogs im Log-Explorer anzuzeigen. Weitere Informationen finden Sie unter Anfragelogs mit Anwendungslogs korrelieren und Korrelierte Logs im Log-Explorer ansehen.
Cloud Trace-Einbindung	Automatische Integration in Cloud Trace für die Erfassung von Latenzdaten.	Sie müssen Ihre Anwendung manuell in Cloud Trace einbinden, um Latenzdaten von App Engine zu erfassen. Weitere Informationen finden Sie unter Für Cloud Trace instrumentieren.
Korrelation auf Fehlerebene	Zeichnet den Fehler, der in den App Engine-Anfragelogs ausgegeben wird, mit dem Schweregrad ERROR auf. Error Reporting korreliert diese Details im Error Reporting-Dashboard automatisch.	Standardmäßig integriert App Engine Error Reporting nicht in die Laufzeiten der zweiten Generation. Informationen zum Einrichten der Logging-Integration mit Error Reporting finden Sie unter Anwendungen mithilfe von Clientbibliotheken instrumentieren .
Schweregrad	Logs Explorer weist Anfragelogs ein Wichtigkeitsstufe zu und diese spiegelt die höchste Wichtigkeit jedes app log Eintrags wider, der mit dem Anfragelogeintrag korreliert ist. Zum Beispiel, wenn eine Anfrage darin resultiert, dass Ihre app einen Warnlogeintrag ausgibt, zeigt der Logs Explorer ein Warnsymbol neben dem Anfragelogeintrag an. Wenn Sie den Anfrageeintrag erweitern, sehen Sie den Warnlogeintrag verschachtelt innerhalb des Anfrageeintrags.	Standardmäßig haben alle Anfragelogs den Schweregrad `DEFAULT` oder `INFO`. Selbst wenn Ihre Anfragelogs mit Anwendungslogs korreliert sind und der Log-Explorer so konfiguriert ist, dass korrelierte Logs aufgerufen werden, spiegeln die Anfragelogs nicht den Schweregrad der zugehörigen Anwendungslogs wider.
Logservice API	Die Logservice API ist Teil des SDK für gebündelte Dienste.	Die Logservice API wurde aus dem gebündelten Dienst-SDK entfernt. Weitere Informationen finden Sie in der Liste der verfügbaren APIs.

Vorbereitung der Migration

Aktivieren Sie die Cloud Logging API in dem Projekt, das Ihre App enthält.

API aktivieren
Stellen Sie sicher, dass Ihre App zum Schreiben von Logs berechtigt ist.

Standardmäßig ist das Standarddienstkonto Ihrer App berechtigt, Logs zu schreiben.

Wenn Ihre App ein anderes Dienstkonto verwendet oder Sie die Berechtigungen für das Standarddienstkonto geändert haben, vergewissern Sie sich, dass das von Ihnen verwendete Konto zum Schreiben von Logs berechtigt ist logging.logEntries.create.
Machen Sie sich mit den verschiedenen Logtypen in App Engine vertraut.

Übersicht über den Migrationsprozess

So migrieren Sie Ihre Anwendung für die Verwendung von Cloud Logging:

Cloud-Clientbibliotheken für Cloud Logging installieren
Logs mit Cloud Logging schreiben
Anfragelogs mit Anwendungslogs korrelieren
Logs ansehen
App testen

Cloud-Clientbibliotheken für Cloud Logging installieren

Zum Installieren und Aktualisieren Ihrer Konfigurationsdateien fügen Sie die Cloud-Clientbibliotheken für Cloud Logging der Liste der Abhängigkeiten in der Datei requirements.txt hinzu. Beispiel:

google-cloud-logging

Logs mit dem Python-Standard-Logging-Modul schreiben

In jeder Datei, die Logeinträge schreibt:

Importieren Sie die Cloud Logging-Clientbibliothek.
Instanziieren Sie den Cloud Logging-Client.
Führen Sie die Methode setup_logging() des Cloud Logging-Clients aus, die ihren Standard-Listener als Logging-Handler für den Python-Root-Logger anhängt.

Beispiel:

# Imports the Cloud Logging client library
import google.cloud.logging

# Instantiates a client
client = google.cloud.logging.Client()

# Retrieves a Cloud Logging handler based on the environment
# you're running in and integrates the handler with the
# Python logging module. By default this captures all logs
# at INFO level and higher
client.setup_logging()

Nachdem der Handler angehängt wurde, werden alle Logs auf INFO-Ebene oder höher, die in Ihrer Anwendung ausgegeben werden, standardmäßig an Logging gesendet:

# Imports Python standard library logging
import logging

# The data to log
text = "Hello, world!"

# Emits the data using the standard logging module
logging.warning(text)

Anfragelogs mit Anwendungslogs korrelieren

Einige Features, die in der Laufzeit der ersten Generation verfügbar sind, z. B. die automatische Korrelation von Anfragelogs mit Anwendungslogs, sind in den Laufzeiten der zweiten Generation nicht verfügbar.

Anwendungen, die Laufzeiten der zweiten Generation verwenden, können ein ähnliches verschachteltes Logging-Verhalten wie Laufzeiten der ersten Generation erreichen. Dazu haben Sie zwei Möglichkeiten:

Cloud Logging-Client in Ihrer Anwendung einrichten und Logs korrelieren
trace-ID mit stdout und stderr verwenden.

Das Logging-Verhalten in Laufzeiten der ersten und zweiten Generation unterscheidet sich in folgender Weise:

In Laufzeiten der ersten Generation bettet App Engine alle Anwendungslogs ein, die während der Verarbeitung einer Anfrage im Feld protoPayload.line.logMessage des Anfragelogs ausgegeben werden. Diese Logs sind im Log-Explorer über appengine.googleapis.com/request_log sichtbar.

Die folgende Abbildung zeigt korrelierte Anfrage- und Anwendungslogs in den Laufzeiten der ersten Generation:
In Laufzeiten der zweiten Generation lässt App Engine das Attribut protoPayload.line im Anfragelog weg. Die Inhalte der Anwendungslogs sind in den JSON-Anfragelogs im Log-Explorer nicht vorhanden. Jedes Anwendungslog wird separat nach seinem Lognamen im Log-Explorer angezeigt.

Die folgende Abbildung zeigt separate Anfrage- und Anwendungslogs in den Laufzeiten der zweiten Generation:

In den folgenden Abschnitten wird beschrieben, wie Sie entweder den Cloud Logging-Client oder das strukturierte Logging mit stdout und stderr zum Korrelieren von Logs verwenden.

Python-Logging-Modul verwenden

Richten Sie die Cloud Logging-Clientbibliothek ein, um eine Anfragekorrelation zu den vom Python-Logging-Modul protokollierten Anwendungslogs hinzuzufügen.

Wenn Sie die client.setup_logging()-Methode beim Start der Anwendung ausführen, fügt diese Methode das trace-Feld und die HTTP-Anfragedetails in Anwendungslogs wie logging.info() undlogging.error() die vom Python logging Modul geschrieben wurden. Diese Logs werden an logs/python weitergeleitet.

App Engine fügt außerdem das Feld trace dem zugehörigen Anfragelog hinzu, sodass Sie korrelierte Logeinträge im Log-Explorer ansehen können.

`stdout` und `stderr` verwenden

Wenn Sie stdout und stderr zum Schreiben von Logeinträgen verwenden, werden diese Einträge im Log-Explorer angezeigt. Um jedoch das Filtern und die Korrelation mit Anfragelogs zu ermöglichen, müssen Sie die Einträge als JSON-Objekt formatieren und bestimmte Metadaten angeben. Weitere Informationen zu diesem Ansatz finden Sie unter Strukturierte Logs in stdout und stderr schreiben. Bei diesem Ansatz wird die Trace-ID der Anfrage so den Anwendungslogs hinzugefügt:

Extrahieren der Trace-ID aus dem X-Cloud-Trace-Context-Anfrageheader.
Schreiben der ID in ein Feld mit dem Namen logging.googleapis.com/trace in Ihrem strukturierten Logeintrag. Weitere Informationen zum Header X-Cloud-Trace-Context finden Sie unter Tracing einer Anfrage erzwingen.

Logs ansehen

Sie können Anwendungs- und Anfragelogs auf verschiedene Arten aufrufen:

Verwenden Sie den Log-Explorer von Cloud Logging in der Google Cloud Console.
Logs über die Google Cloud CLI mit gcloud aufrufen
Logs programmatisch mit verschiedenen Methoden lesen.

Log-Explorer verwenden

Sie können Ihre Anwendungs- und Anfragelogs mit dem Log-Explorer aufrufen:

Rufen Sie in der Google Cloud Console den Log-Explorer auf:

Zum Log-Explorer
Wählen Sie oben auf der Seite ein vorhandenes Google Cloud-Projekt aus.
Wählen Sie unter Ressourcentyp die Option GAE-Anwendung aus.

Der Log-Explorer lässt sich nach App Engine-Dienst und -Version sowie nach anderen Kriterien filtern. Sie können in den Logs auch nach bestimmten Einträgen suchen. Weitere Informationen finden Sie unter Log-Explorer verwenden.

Wenn Sie einfache Texteinträge an die Standardausgabe senden, können Sie die Anwendungseinträge in der Loganzeige nicht nach dem Schweregrad filtern. Außerdem lässt sich in diesem Fall nicht feststellen, welche Anwendungslogs bestimmten Anfragen entsprechen. Sie können auch andere Filtertypen im Log-Explorer verwenden, z. B. Text und Zeitstempel.

Korrelierte Logeinträge im Log-Explorer abfragen

Wenn Sie im Log-Explorer die untergeordneten Logeinträge ansehen möchten, die mit einem übergeordneten Logeintrag korrelieren, erweitern Sie den Logeintrag.

So können Sie beispielsweise Ihren App Engine-Anfragelogeintrag und die Anwendungslogeinträge aufrufen:

Wählen Sie im Navigationsbereich der Google Cloud Console Logging und anschließend Log-Explorer aus:

Zum Log-Explorer
Wählen Sie unter Ressourcentyp die Option GAE-Anwendung aus.
Wählen Sie unter Logname die Option request_log aus, um Anfragelogs aufzurufen und zu korrelieren. Wenn Sie nach Anfragelogs korrelieren möchten, klicken Sie alternativ auf Korrelieren nach und wählen Sie request_log aus.
Klicken Sie im Bereich Abfrageergebnisse auf Maximieren, um einen Logeintrag zu maximieren. Beim Maximieren werden in jedem Anfragelog die zugehörigen Anwendungslogs angezeigt.

Nachdem Sie einen Filter für die Logs erstellt haben, zeigt jedes Anfragelog die entsprechenden Anwendungslogs als untergeordnete Logs an. Dies wird durch die Korrelation des Felds trace in Anwendungslogs mit einem bestimmten Anfragelog erreicht, sofern die Anwendung die Bibliothek google-cloud-logging verwendet.

Die folgende Abbildung zeigt Anwendungslogs, die nach dem Feld trace gruppiert sind:

Die Einträge des Anwendungslogs sind im Anfragelogeintrag verschachtelt.

Google Cloud CLI verwenden

Über die Befehlszeile können Sie App Engine-Logs mit diesem Befehl aufrufen:

gcloud app logs tail

Weitere Informationen finden Sie unter gcloud app logs tail.

Logs programmatisch lesen

Wenn Sie die Logs programmatisch lesen möchten, können Sie eine der folgenden Methoden verwenden:

Verwenden Sie eine Logsenke für Pub/Sub und ein Skript zum Abrufen aus Pub/Sub.
Rufen Sie die Cloud Logging API über die Clientbibliothek für Ihre Programmiersprache auf.
Rufen Sie die REST-Endpunkte der Cloud Logging API direkt auf.

Informationen zu Instanzskalierungs-Logs

Wenn neue Instanzen für Ihre App gestartet werden, enthält Cloud Logging Logeinträge unter dem Lognamen varlog/system, die Aufschluss darüber geben, warum die jeweilige Instanz erstellt wurde. Der Logeintrag hat folgendes Format:

Starting new instance. Reason: REASON - DESCRIPTION

In der folgenden Tabelle finden Sie eine Aufschlüsselung der Instanzbeschreibungen:

Grund	Beschreibung
`CUSTOMER_MIN_INSTANCE`	Vom Kunden konfigurierte Mindestkonfiguration für die App.
`SCHEDULED`	Die Instanz wurde aufgrund konfigurierter Skalierungsfaktoren (z.B. CPU-Auslastung, Anfragedurchsatz usw.) und ihrer Ziele gestartet.
`OVERFLOW`	Instanz gestartet, da für den aktuellen Traffic keine Kapazität vorhanden war.

App testen

Die Migration ist erfolgreich, wenn Sie Ihre Anwendung fehlerfrei bereitstellen können. So prüfen Sie, ob Cloud Logging funktioniert:

Rufen Sie den Log-Explorer auf und maximieren Sie einen Anfragelogeintrag.

Zum Log-Explorer
Achten Sie darauf, dass die Anwendungslogs, die bei der Verarbeitung einer Anfrage von Ihrer Anwendung generiert werden, im Anfragelog verschachtelt sind.
Wenn alle Endpunkte Ihrer Anwendung wie erwartet funktionieren, verwenden Sie die Trafficaufteilung, um den Traffic für die aktualisierte Anwendung langsam zu erhöhen. Überwachen Sie die Anwendung genau in Bezug auf Probleme, bevor Sie zusätzlichen Traffic an die aktualisierte Anwendung weiterleiten.