Logs schreiben und aufrufen

Go Java Node.js PHP Python Ruby

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

• Systemprotokoll: Von der Plattform generierte Protokolle mit Informationen zu Ihrer App. Diese Protokolle werden in varlog/system geschrieben.

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

Hinweis: Wenn Sie von der Laufzeit der ersten Generation auf die Laufzeit der zweiten Generation aktualisieren, finden Sie weitere Informationen und Beispiele unter Zu Cloud Logging migrieren.

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
• Strukturierte Logs mit stdout und stderr schreiben

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.

Sie können Logs von Python-Anwendungen mit dem standardmäßigen Python-Logging-Handler in Cloud Logging schreiben. Dies ist auch direkt über die Cloud Logging API-Clientbibliothek für Python möglich. Wenn Sie den standardmäßigen Python-Logging-Handler verwenden, müssen Sie an den Python-Root-Handler einen Cloud Logging-Handler anhängen. Weitere Informationen finden Sie unter Cloud Logging für Python einrichten.

Wichtig: Im Log-Explorer werden Anwendungslogeinträge über 16 Kilobyte nicht angezeigt.

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.

Die folgenden Snippets veranschaulichen das Schreiben solcher strukturierten Logs.

Hinweis: Diese Snippets wurden ursprünglich für Cloud Run geschrieben. Sie sind gleichermaßen auf App Engine anwendbar.

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

In der App Engine-Standardumgebung wird das Schreiben strukturierter Logs in stdout und stderr nicht auf das Kontingent für Logaufnahmeanfragen pro Minute in der Cloud Logging API angerechnet.

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

Standardmäßig werden Logs in Laufzeiten der zweiten Generation nicht korreliert. Diese Laufzeiten erfordern die Verwendung der Cloud-Clientbibliotheken. Diese Bibliotheken unterstützen Verschachtelung nicht und erfordern, dass Sie Ihre Logs korrelieren.

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 vom Python logging-Modul geschriebenen Anwendungslogs wie logging.info() und logging.error() hinzu. 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

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:

• 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:

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.

   

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:

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 Instanzskalierungsprotokollen

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.

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.