Logs schreiben und aufrufen

Auf dieser Seite werden die Logs erläutert, die für App Engine-Anwendungen verfügbar sind. Außerdem wird gezeigt, wie Logeinträge geschrieben, in Verbindung gesetzt und aufgerufen werden.

App Engine erfasst zwei Arten von Logs:

  • Anfragelog: Logs der Anfragen, die an die Anwendung gesendet wurden. Standardmäßig gibt App Engine automatisch für jede HTTP-Anfrage, die eine Anwendung empfängt, einen Logeintrag aus.

  • Anwendungslog: Logeinträge, die von einer App Engine-Anwendung basierend auf den von Ihnen in ein unterstütztes Framework oder eine Datei geschriebenen Logeinträgen ausgegeben werden.

App Engine sendet automatisch sowohl die Anfrage- als auch die Anwendungslogs an den Cloud Logging-Agent.

Anwendungslogs schreiben

App Engine gibt automatisch Logs für Anfragen aus, die an Ihre Anwendung gesendet werden, sodass Sie keine Anfragelogs schreiben müssen. In diesem Abschnitt wird beschrieben, wie Anwendungslogs geschrieben werden.

Wenn Sie Anwendungslogs aus Ihrer App Engine-Anwendung heraus schreiben, werden die Logs von Cloud Logging automatisch erfasst, sofern die Logs mit den folgenden Methoden geschrieben werden:

In Cloud Logging einbinden

Sie können Ihre App Engine-Anwendung in Cloud Logging einbinden. Auf diese Weise können Sie alle Features von Cloud Logging verwenden. Es sind nur wenige Zeilen mit Google-spezifischem Code erforderlich.

Strukturierte Logs in stdout und stderr schreiben

Standardmäßig verwendet App Engine die Cloud Logging-Clientbibliothek zum Senden von Logs. Diese Methode unterstützt jedoch kein strukturiertes Logging. Strukturierte Logs können nur mit stdout/stderr geschrieben werden. Außerdem können Sie Textstrings an stdout und stderr senden. Standardmäßig ist die Lognutzlast ein Textstring, der im textPayload-Feld des Logeintrags gespeichert wird. Die Strings werden im Log-Explorer, der Befehlszeile und der Cloud Logging API als Nachrichten angezeigt und sind mit dem App Engine-Dienst sowie mit der Version verknüpft, mit der sie ausgegeben wurden.

Sie können diese Strings im Log-Explorer nach Schweregrad filtern, um die Logs optimal zu nutzen. Zum Filtern dieser Strings müssen Sie diese als strukturierte Daten formatieren. Dazu schreiben Sie Logs in Form einer einzelnen, serialisierten JSON-Zeile. App Engine erfasst und parst diese serialisierte JSON-Zeile und fügt sie im jsonPayload-Feld des Logeintrags anstelle von textPayload ein.

stdout- und stderr-Logs werden aus der flexiblen Umgebung über den in den VM-Instanzen ausgeführten Legacy-Logging-Agent an Cloud Logging gesendet. Der Logging-Agent wird mit begrenzten Ressourcen ausgeführt und die geschriebenen Logs werden rotiert, nachdem ein Limit von 10 MB überschritten wurde. Wenn die Rate, mit der Logs in stdout und stderr geschrieben werden, größer ist als die Rate, mit der Logs vom Logging-Agent gelesen werden, können die Logs rotiert werden, bevor die Logs an Cloud Logging gesendet werden: Wenn Sie keine Protokolle verlieren möchten, verwenden Sie Cloud Logging.

Spezielle JSON-Felder in Nachrichten

Wenn Sie ein strukturiertes Log als JSON-Wörterbuch erstellen, werden bestimmte Felder aus jsonPayload entfernt und in das entsprechende Feld im erstellten LogEntry geschrieben, wie in der Dokumentation für spezielle Felder erläutert.

Wenn Ihre JSON-Datei beispielsweise das Attribut severity enthält, wird es aus jsonPayload entfernt und stattdessen als severity des Logeintrags angezeigt. Das Attribut message wird als Hauptanzeigentext des Logeintrags verwendet, sofern vorhanden.

Anfragelogs mit Anwendungslogs korrelieren

Nachdem Sie die Einträge als JSON-Objekt formatiert und bestimmte Metadaten bereitgestellt haben, können Sie die Filterung und die Korrelation mit Anfragelogs aktivieren. Sie benötigen die Trace-ID der Anfrage, um die Einträge der Anfragelogs mit den Einträgen der Anwendungslogs zu korrelieren. Folgen Sie den Anleitungen, um Lognachrichten zu korrelieren:

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

Informationen zum Aufrufen korrelierter Logs finden Sie unter Korrelierte Logeinträge im Log-Explorer ansehen.

Logs ansehen

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

Log-Explorer verwenden

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

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

    Zum Log-Explorer

  2. Wählen Sie oben auf der Seite ein vorhandenes Google Cloud-Projekt aus.

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

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

    Zum Log-Explorer

  2. Wählen Sie unter Ressourcentyp die Option GAE-Anwendung aus.

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

    Logs korrelieren

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

Preise, Kontingente und Aufbewahrungsrichtlinie für Logs

Informationen zu Preisen, die sowohl für Anfrage- als auch für Anwendungslogs gelten, finden Sie unter Preise für Cloud Logging.

Informationen zur Aufbewahrungsrichtlinie für Logs und zur maximalen Größe von Logeinträgen erhalten Sie unter Kontingente und Limits. Zur längerfristigen Speicherung Ihrer Logs können Sie diese nach Cloud Storage exportieren. Außerdem besteht die Möglichkeit, Logs zur weiteren Verarbeitung nach BigQuery und Pub/Sub zu exportieren.

Nutzung von Logressourcen verwalten

Sie können den Umfang der Logging-Aktivität von Ihren Anwendungslogs aus steuern. Dazu schreiben Sie die gewünschte Anzahl an Einträgen über den Code Ihrer Anwendung. Anfragelogs werden automatisch erstellt. Zur Verwaltung der Anzahl der Anfragelogeinträge, die mit Ihrer Anwendung verknüpft sind, verwenden Sie das Feature Logausschluss von Cloud Logging.

Bekannte Probleme

Im Folgenden sind einige Logging-Probleme in Laufzeiten der zweiten Generation aufgeführt:

  • Manchmal sind Anwendungslogeinträge nicht mit dem Anfragelog verknüpft. Dies ist dann der Fall, wenn die Anwendung zum ersten Mal eine Anfrage erhält und immer dann, wenn App Engine Statusmeldungen in das Anwendungslog schreibt. Weitere Informationen finden Sie unter https://issuetracker.google.com/issues/138365527.

  • Wenn Sie Logs von der Logsenke nach Cloud Storage weiterleiten, enthält das Cloud Storage-Ziel nur Anfragelogs. App Engine schreibt Anwendungslogs in verschiedene Ordner.

  • BigQuery kann aufgrund des Felds @type in den Anfragelogs keine Logs aufnehmen. Dies stört die automatische Schemaerkennung, da BigQuery @type nicht in Feldnamen zulässt. Zur Behebung dieses Problems müssen Sie das Schema manuell definieren und das Feld @type aus den Anfragelogs entfernen.

  • Wenn Sie die Logging REST APIs verwenden, schreibt ein Hintergrundthread Logs in Cloud Logging. Wenn der Hauptthread nicht aktiv ist, erhält die Instanz keine CPU-Zeit, wodurch der Hintergrundthread beendet wird. Die Logverarbeitungszeit ist verzögert. Irgendwann wird die Instanz entfernt und alle nicht gesendeten Logs gehen verloren. Verwenden Sie eine der folgenden Optionen, um Logverluste zu vermeiden:

    • Konfigurieren Sie das Cloud Logging SDK für die Verwendung von gRPC. Mit gRPC werden die Logs sofort an Cloud Logging gesendet. Dadurch können jedoch die erforderlichen CPU-Limits erhöht werden.
    • Lognachrichten mit stdout/stderr an Cloud Logging senden Diese Pipeline befindet sich außerhalb der App Engine-Instanz und wird nicht gedrosselt.

Nächste Schritte

  • Unter Latenz überwachen und melden erfahren Sie, wie Sie mit Cloud Logging Logs zum Debugging von Fehlern aufrufen und wie Sie Cloud Trace zum Verständnis der Anwendungslatenz nutzen.