Logabfragen erstellen

Auf dieser Seite wird beschrieben, wie Sie Abfragen im Log-Explorer der Google Cloud Console erstellen, um Logs abzurufen, zu optimieren und zu analysieren.

Vorbereitung

Sie benötigen keinen Arbeitsbereich, um Logging zu verwenden, es sei denn, Sie senden Logs von Amazon Web Services (AWS) an Logging.

Im Log-Explorer werden Logs für ein einzelnes Google Cloud-Projekt angezeigt. Wenn Sie einen Arbeitsbereich verwenden, werden die Logs der überwachten Projekte beim Logging nicht kombiniert. Sie müssen ein bestimmtes Projekt auswählen, um die zugehörigen Logs abzurufen.

Wenn Sie einen Arbeitsbereich und AWS verwenden, wählen Sie das AWS-Verbindungsprojekt aus, um die AWS-Logs abzurufen.

Einstieg

So gehen Sie zum Log-Explorer:

  1. Rufen Sie das Google Cloud-Navigationsmenü auf und wählen Sie Logging > Log-Explorer aus.
    Zum Log-Explorer
  2. Wählen Sie ein Google Cloud-Projekt aus.
  3. Wechseln Sie vom Menü Upgrade von Legacy-Loganzeige zu Log-Explorer.

Sie befinden sich jetzt im Log-Explorer.

Abfragen erstellen

Im Bereich "Query Builder" haben Sie mehrere Möglichkeiten, um Logs abzurufen:

  1. Drop-down-Menüs in Query Builder
  2. Abfragen, die die Sprache des Query Builders verwenden
  3. Die Tabs Zuletzt, Gespeichert und Vorgeschlagen.

query-builder-pane

In den folgenden Abschnitten wird beschrieben, wie Sie Abfragen zum Abrufen von Logs erstellen und ausführen.

Drop-down-Menüs in Query Builder

Mit den Drop-down-Menüs können Sie dem Query Builder Abfrageparameter hinzufügen. Sie können die Drop-down-Menüs verwenden, um Ressourcen, Lognamen, Log-Schweregrad und Zeiträume auszuwählen. Diese Optionen entsprechen den LogEntry-Feldern für alle Logs der Operations-Suite von Google Cloud.

Drop-down-Menüs in Query Builder

  • Ressource: Hier können Sie resource.type angeben. Sie können jeweils nur eine Ressource auswählen, die Sie dem Query Builder hinzufügen möchten. Einträge verwenden den logischen Operator AND.
  • Logname: Hier können Sie logName angeben. Sie können mehrere Lognamen gleichzeitig auswählen und dem Query Builder hinzufügen. Bei der Auswahl mehrerer Einträge wird der logische Operator OR verwendet.
  • Schweregrad: Hier können Sie [severity][severity] angeben. Sie können mehrere Schweregrade gleichzeitig auswählen und dem Query Builder hinzufügen. Bei der Auswahl mehrerer Einträge wird der logische Operator OR verwendet.

Zum Verwenden der Suchparametermenüs, erweitern Sie diese und wählen Sie einen oder mehrere Parameter aus. Klicken Sie anschließend auf Hinzufügen.

Klicken Sie nach dem Erstellen der Abfrage auf Abfrage ausführen, um die gewünschten Logeinträge abzurufen.

Abfragen mit Zeitbeschränkung

Es gibt zwei Möglichkeiten, Logs auf der Basis von Zeit abzufragen:

  1. Abfrage mit einem Ausdruck für einen Zeitstempel
  2. Abfrage mit der Auswahl eines Zeitraums

    Log-Explorer bietet zwei Möglichkeiten zum Filtern nach Zeit

Wenn Sie eine Abfrage mit einem Zeitstempel haben, ist die Zeitraumauswahl deaktiviert und die Abfrage verwendet den Zeitstempelausdruck als Zeitraumbeschränkung. Wenn eine Abfrage keinen Zeitstempelausdruck hat, verwendet die Abfrage die Zeitraumauswahl als Zeitraumbeschränkung.

Abfragen, die die Sprache des Query Builders verwenden

Sie können die Sprache des Query Builders verwenden, um Abfragen im Cloud Logging-Bereich "Query Builder" in der Logging API oder in der Befehlszeile zu erstellen.

Weitere Informationen finden Sie unter Sprache des Query Builders.

Im Folgenden finden Sie einige Vorschläge zur Optimierung Ihrer Abfragen.

Abfragen optimieren

Gehen Sie so vor, um Logeinträge schneller zu finden:

  • Suchen Sie nach indexierten Feldern.
  • Minimieren Sie die Anzahl der zu durchsuchenden Logeinträge.

Indexierte Felder verwenden

Geben Sie exakte Werte für indexierte Felder an, um den Index optimal zu nutzen. Verwenden Sie keine Teilstring-Übereinstimmungen.

Die folgenden LogEntry-Felder sind indexiert:

In den nächsten Abschnitten wird erläutert, wie mit diesen indexierten Feldern die Anzahl der Logeinträge minimiert wird, die abgefragt werden sollen.

Logeinträge schnell finden

Sie können Suchanfragen beschleunigen, indem Sie die Anzahl der Logs oder Logeinträge oder den Zeitraum jeder Suche reduzieren. Optimalerweise reduzieren Sie alle drei.

Beispiel: Den richtigen Lognamen verwenden

Geben Sie das Log mit den relevanten Logeinträgen an. Wichtig ist, dass Sie den tatsächlichen Lognamen kennen. Diesen finden Sie in Ihren Logeinträgen. Beispielsweise zeigt der Log-Explorer, dass im Compute Engine-Abschnitt ein Log namens "activity_log" enthalten ist. Bei genauerer Überprüfung der Einträge des Aktivitätslogs sehen Sie, dass das Log tatsächlich "compute.googleapis.com/activity_log" heißt.

Der folgende Vergleich ist falsch. Es wird keine Übereinstimmung zurückgegeben, da der Logname falsch ist:

    logName = "projects/my-project-id/logs/activity_log"   # WRONG!

Der folgende Vergleich ist richtig. Dabei werden Logeinträge im Aktivitätslog ausgewählt. Wichtig ist, dass der Logname wie folgt URL-codiert ist:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"

Beispiel: Die richtigen Logeinträge auswählen

Wenn Sie wissen, dass die gewünschten Logeinträge aus einer bestimmten VM-Instanz stammen, geben Sie die Instanz an. Prüfen Sie die Richtigkeit der Labelnamen in einem der zu durchsuchenden Logeinträge. Im folgenden Beispiel ist instance_id eines der indexierten Labels:

    logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log"
    resource.type = "gce_instance" AND
    resource.labels.instance_id = "6731710280662790612"

Geben Sie einen Wert für den Ressourcentyp an. Andernfalls wird beim Vergleich von instance_id der Index nicht verwendet.

Beispiel: Den richtigen Zeitraum auswählen

Geben Sie einen Zeitraum für die Suche an. Nützliche Zeitstempel im RFC 3339-Format lassen sich schnell mit dem Gnu/Linux-Befehl date festlegen:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

Verwenden Sie die Werte dieser Zeitstempel in den folgenden Abfragen. Wenn Sie einen für Logging akzeptablen Zeitstempel erstellen möchten, ersetzen Sie das Leerzeichen zwischen Datum und Uhrzeit durch den Buchstaben T.

Durchsuchen Sie z. B. die Einträge der vergangenen drei Stunden:

    timestamp >= "2016-06-27T14:40:00-04:00"

Oder durchsuchen Sie den Zeitraum vor drei bis fünf Stunden:

    timestamp >= "2016-06-27T12:40:00-04:00" AND
    timestamp <= "2016-06-27T14:40:00-04:00"

Ein weiteres Beispiel zur Verwendung von Zeitstempeln finden Sie auf dieser Seite unter Temporäre Feldindexe.

Globale und Teilstring-Suchanfragen minimieren

Kürzen Sie Logabfragen bei der Eingabe nicht ab.

Beispiel: Keine Teilstrings in indexierten Feldern verwenden

Angenommen, Sie suchen nach einem Logeintrag vom Apache2-Webserver. Sie wissen, dass die Apache-Logs apache-access und apache-error heißen. Wie gehen Sie vor?

  • Falsch: Verwenden Sie keine Teilstring-Übereinstimmung, um die Eingabe zu beschleunigen:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • Richtig: Verwenden Sie zum Durchsuchen indexierter Felder exakte Übereinstimmungen:

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

Teilstring-Suchanfragen in indexierten Feldern verlangsamen den Suchvorgang.

Beispiel: Keine globalen Suchanfragen verwenden

Angenommen, Sie suchen nach einem Logeintrag mit dem Text "Hello, Kitty" in der Nutzlast:

  • Falsch: Verwenden Sie keine globale Suchanfrage. Ein Grund ist, dass es sich dabei ausnahmslos um Teilstring-Suchanfragen handelt:

        "Hello, Kitty"   # THIS CAUSES A SLOW SEARCH!
    
  • Richtig: Begrenzen Sie die Suche auch dann auf ein einzelnes Feld, wenn Sie eine Teilstring-Suche durchführen müssen:

        textPayload:"Hello, Kitty"
    
  • Richtig: Führen Sie nach Möglichkeit einen Gleichheitstest durch:

        textPayload = "Hello, Kitty"
    
  • Richtig: Referenzieren Sie einzelne Felder in einer Nutzlast, wenn die Logeinträge über strukturierte Nutzlasten verfügen:

        jsonPayload.my_favorite_cat = "Hello, Kitty"
    
  • Richtig: Schränken Sie die Suche durch Verwendung eines indexierten Felds ein:

        logName = "projects/my-project_id/logs/somelog" AND
        jsonPayload.my_favorite_cat = "Hello, Kitty"
    

In Beispielen suchen

Die angezeigten Logeinträge stimmen mit der Suchanfrage im Suchfeld überein. Wenn das Menü Zu Datum springen einen Wert enthält, wird in der Anzeige zu diesem Zeitpunkt gescrollt. Hier einige Beispiele für Abfragen:

resource.type=gae_app

Hiermit werden dieselben Logeinträge zurückgegeben, die Sie auch auf der einfachen Abfrageoberfläche sehen würden, wenn Sie im Menü mit den Ressourcenlogs die Option GAE-Anwendung (alle Modul-IDs) und im Menü mit den Lognamen Alle Logs auswählen. Eine Liste der Ressourcentypen finden Sie unter Liste beobachteter Ressourcen.

Während der Eingabe werden im Log-Explorer Vorschläge für Felder wie resource.type eingeblendet.

resource.type=gae_app AND logName:request_log

Hiermit werden Logeinträge für App Engine-Apps aus Logs zurückgegeben, deren Name request_log enthält. Beachten Sie Folgendes:

  • Der Operator = steht für genaue Gleichheit. Der Ressourcentyp muss genau mit "gae_app" übereinstimmen. Die Groß-/Kleinschreibung wird nicht beachtet.
  • Der Operator : steht für "has" (enthält). Das Feld logName muss request_log enthalten. Die Groß-/Kleinschreibung wird nicht beachtet. Der tatsächliche Logname ist deutlich länger. Der Operator : kann Suchanfragen verlangsamen.
  • Die beiden Vergleiche werden durch AND verbunden. Sie können auch OR verwenden. Wenn Sie den Operator weglassen, gilt standardmäßig AND.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Hiermit werden Logeinträge mit einem der beiden Ressourcentypen "Compute Engine-VM-Instanz" oder "AWS EC2-VM-Instanz" zurückgegeben. Für die Logeinträge muss mindestens die severity (Wichtigkeitsstufe) ERROR gelten. Das entspricht in der einfachen Abfrageoberfläche der Auswahl von ERROR im Menü für Wichtigkeitsstufen. Sie können auf der einfachen Abfrageoberfläche jeweils nur die Logs eines einzigen Ressourcentyps ansehen.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Hiermit werden alle Audit-Logeinträge zu Administratoraktivitäten im Projekt [PROJECT_ID] zurückgegeben. Alle Audit-Logs eines Projekts verwenden denselben Namen, haben aber unterschiedliche Ressourcentypen. Die Log-ID cloudaudit.googleapis.com/activity muss URL-codiert und im Lognamen enthalten sein. Durch Verwendung eines Gleichheitsoperators im Vergleich beschleunigen Sie die Suche. Weitere Informationen finden Sie unter Audit-Logs verstehen.

unicorn

Hiermit werden Logeinträge zurückgegeben, die in einem der Felder unicorn enthalten. Die Groß-/Kleinschreibung wird nicht beachtet. Ein Suchbegriff, der nicht Teil eines Feldvergleichs ist, bildet eine Abfrage an "alle Felder".

unicorn phoenix

Hiermit werden Logeinträge zurückgegeben, die in einem der Felder unicorn und phoenix enthalten.

textPayload:(unicorn phoenix)

Hiermit werden Logeinträge zurückgegeben, deren Feld textPayload sowohl unicorn als auch phoenix in beliebiger Reihenfolge enthält. Zwischen den beiden Wörtern wird standardmäßig der Operator AND angenommen.

textPayload:"unicorn phoenix"

Hiermit werden Logeinträge zurückgegeben, deren Feld textPayload den String "unicorn phoenix" enthält. Diese Abfrage ist mit der Abfrage in der herkömmlichen Abfrageoberfläche identisch.

NOT textPayload: "unicorn phoenix"

Hiermit werden Logeinträge zurückgegeben, deren Feld textPayload den String "unicorn phoenix" nicht enthält. Diese Art der Abfrage reduziert unerwünschte Logeinträge.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Hiermit werden Logeinträge innerhalb eines 30-Minuten-Zeitraums zurückgegeben.

Gespeicherte Abfragen

Der Bereich "Query Builder" enthält den Tab Gespeichert. Hier können Sie gespeicherte Abfragen abrufen.

Liste gespeicherter Abfragen

Mit gespeicherten Abfragen können Sie Abfrageausdrücke speichern, um Ihre Logs konsistenter und effizienter zu durchsuchen.

So speichern Sie eine Abfrage, die Sie im Bereich "Query Builder" erstellt haben:

  1. Klicken Sie im Bereich "Query Builder" auf Speichern. Das Dialogfeld Abfrage speichern wird geöffnet. Der Abfrageausdruck befindet sich im Feld Abfrage.

  2. Fügen Sie einen Namen für die Abfrage hinzu.

    Namen sind auf 64 Zeichen beschränkt.

  3. Optional: Wenn Sie der Abfrage Zusammenfassungsfelder hinzufügen möchten, aktivieren Sie Zusammenfassungsfelder einbeziehen.

  4. Optional: Fügen Sie eine Beschreibung für Ihre Abfrage hinzu.

    Beschreibungen sind auf 1.000 Zeichen beschränkt. Geben Sie keine vertraulichen Informationen an.

  5. Klicken Sie im Dialogfeld auf Abfrage speichern.

Ihre gespeicherten Abfragen werden im Bereich "Query Builder" auf dem Tab Gespeichert in einer Liste angezeigt.

Klicken Sie zum Ausführen einer gespeicherten Abfrage auf Abfrage ausführen.

Aktuelle Abfragen

Der Bereich "Query Builder" enthält den Tab Aktuell. Wenn Sie eine Abfrage ausführen, wird sie in die Abfrageliste Aktuell aufgenommen, die die letzten 10.000 Abfragen über einen Zeitraum von 30 Tagen enthält.

Der Tab

Um die letzten Abfragen anzusehen, wählen Sie im Query Builder-Fenster den Tab Aktuell aus. Auf dem Tab Aktuell stehen folgende Optionen zur Verfügung:

  • Ausführen. Führt die Abfrage aus.
  • Weitere Optionen . Hiermit können Sie die Abfrageparameter mit den Optionen zum Ausführen der Abfrage oder zum Speichern in der Liste der Gespeicherten Abfragen anzeigen. Sie können die Abfrage auch direkt auswählen, um diese Optionen aufzurufen.

    Klicken Sie zum Ausführen der Abfrage auf Ausführen.

    Klicken Sie zum Speichern der Abfrage auf Speichern unter und füllen Sie folgende Felder aus:

    • Name (erforderlich): Geben Sie einen Namen an.
    • Beschreibung (optional): Geben Sie eine Beschreibung ein, um den Zweck der Abfrage zu identifizieren.
    • Zusammenfassungsfelder einschließen (optional): Aktivieren Sie Zusammenfassende Felder einschließen und geben Sie die Felder an, die angezeigt werden sollen.
    • Zusammenfassungsfelder kürzen (optional): Aktivieren Sie Zusammenfassungsfelder kürzen und wählen Sie die Anzahl der zu kürzenden Zeichen aus, und ob die Kürzung vom Anfang oder Ende ausgehend erfolgen soll.

    Klicken Sie auf Abfrage speichern. Die Abfrage ist jetzt in der Liste "Gespeicherte Abfragen" verfügbar.

Sie können auch Ihre letzten Abfragen filtern. Der Filter nutzt den Text im Ausdruck Ihrer Abfrage.

Vorgeschlagene Abfragen

Logging generiert vorgeschlagene Abfragen anhand seiner Kenntnisse der von Ihnen verwendeten Google Cloud-Produkte. Es schlägt Abfragen vor, die Ihnen helfen können, Probleme zu erkennen, und bietet einen Einblick in den Gesamtzustand Ihrer Systeme. Wird beispielsweise festgestellt, dass Sie Google Kubernetes Engine verwenden, kann Logging eine Abfrage vorschlagen, die alle Fehlerlogs für Ihre Container findet.

So zeigen Sie im Query Builder-Bereich vorgeschlagene Abfragen an und führen sie aus:

  1. Klicken Sie auf den Tab Vorgeschlagen.

    Tab

  2. Prüfen Sie die Beschreibung der vorgeschlagenen Abfrage.

  3. Führen Sie einen der folgenden Schritte aus, um die Details einer vorgeschlagenen Suchanfrage anzuzeigen:

    a. Klicken Sie auf die Zeile.

    b. Klicken Sie auf das Dreipunkt-Menü und wählen Sie Ansehen aus.

  4. Im Query Builder sehen Sie die Abfrage und die Optionen zum Ausführen oder Speichern.

    a. Klicken Sie zum Speichern der Abfrage auf Speichern. Die Abfrage wird in der Liste Gespeichert angezeigt. Dort können Sie die Abfrage später ausführen.

    b. Klicken Sie zum Ausführen der Abfrage auf Run (Ausführen). Die Abfrage wird unter Abfragen-Preview im Query Builder-Fenster angezeigt.

  5. Nachdem Sie die Abfrage überprüft haben, klicken Sie auf Abfrage ausführen. Das Ergebnis der vorgeschlagenen Abfrage wird unter Abfrageergebnisse angezeigt.

Vorgeschlagene Abfragen werden dynamisch basierend auf dem Google Cloud-Projektkontext erstellt. Bei aufeinanderfolgendem Ladevorgängen werden möglicherweise nicht die gleichen Abfragen in derselben Reihenfolge angezeigt. Das ist ganz normal.

Fehlerbehebung

Text ohne Anführungszeichen

Textstrings, die weder Leerzeichen noch bestimmte Sonderzeichen enthalten, können ohne Anführungszeichen eingegeben werden. Das wird als Text ohne Anführungszeichen bezeichnet. Ein Beispiel hierfür ist der oben angegebene Begriff ERROR. Der String "v1.compute.instances.insert" ist aufgrund der enthaltenen Punkte in Anführungszeichen gesetzt. Wenn Sie in einen String Anführungszeichen einbeziehen möchten, stellen Sie den Anführungszeichen einen umgekehrten Schrägstrich ("\") voran.

Syntaxprobleme

Wenn Sie Probleme mit der Query Builder-Sprache haben, prüfen Sie Folgendes:

  • Die Abfragen erfüllen die Syntaxregeln hinsichtlich entsprechender Klammern und Anführungszeichen. Ihre Abfrage darf keine Kommentare enthalten.

  • Die Feldnamen für die Logeinträge sind korrekt geschrieben.

  • Boolesche Operatoren sind in Großbuchstaben angegeben (AND, OR, NOT).

  • Boolesche Ausdrücke, die als globale Einschränkungen oder als rechte Seite in Vergleichen verwendet werden, sollten der Übersichtlichkeit halber in Klammern gesetzt werden. Die beiden Abfragen unten sehen beispielsweise gleich aus, sind aber unterschiedlich:

    insertId = "ABC-1" OR "ABC-2"  # ERROR!?
    insertId = ("ABC-1" OR "ABC-2")
    
  • Text ohne Anführungszeichen darf keine Sonderzeichen enthalten. Fügen Sie im Zweifelsfall doppelte Anführungszeichen hinzu. Der erste Vergleich unten ist beispielsweise aufgrund des eingebetteten Teilstring-Operators (:) unzulässig. Er muss Anführungszeichen enthalten:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • Bei gcloud logging muss die Abfrage in doppelte Anführungszeichen gesetzt werden. Wenn Sie mit dem Befehl gcloud logging doppelte Anführungszeichen als Maskierungszeichen von Sonderzeichen verwenden möchten, setzen Sie den gesamten Filter stattdessen in einfache Anführungszeichen:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
    gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'
    
  • Wenn Sie eine Abfrage schreiben, die einen Zeitstempel enthält, wählen Sie in der Zeitraumauswahl unter dem Feld für die Suchanfrage die Option Keine Beschränkung aus.