Kurzanleitung für Logging-Tools

Diese Kurzanleitung bietet eine Einführung in einige Funktionen von Cloud Logging. Sie erfahren, wie Sie:

  • Logeinträge mit dem gcloud-Befehlszeilentool schreiben
  • Logeinträge mit dem gcloud-Befehlszeilentool auflisten
  • Logeinträge über die Logging API auflisten
  • Logeinträge mit der Loganzeige ansehen und abfragen

Hinweise

Sie benötigen ein Google Cloud-Projekt mit aktivierter Abrechnungsfunktion, um diese Kurzanleitung durchzuarbeiten. Wenn Sie kein Google Cloud-Projekt haben oder die Abrechnung für Ihr Projekt nicht aktiviert ist, gehen Sie so vor:
  1. Melden Sie sich bei Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.

  2. Wählen Sie in der Cloud Console auf der Seite für die Projektauswahl ein Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für Ihr Projekt aktiviert ist.

Einstieg

Das Cloud SDK bietet die Befehlsgruppe gcloud logging, die eine Befehlszeile für die Cloud Logging API bereitstellt.

Für die Ausführung der in dieser Kurzanleitung genannten Befehle über das gcloud-Befehlszeilentool können Sie die Cloud Shell-Umgebung oder eine VM-Instanz von Compute Engine verwenden.

Cloud Shell

  1. Das Cloud SDK ist in der Cloud Shell-Umgebung vorinstalliert. Sie müssen keine andere Software installieren oder konfigurieren.

  2. Öffnen Sie Cloud Shell und prüfen Sie die Projektkonfiguration:

    1. Klicken Sie in der Cloud Console auf Cloud Shell aktivieren:

      Cloud Shell aktivieren

      Cloud Shell wird in einem Fenster geöffnet und eine Begrüßungsnachricht wird angezeigt:

      Willkommen bei Cloud Shell

    2. Die Begrüßungsnachricht gibt die konfigurierte Projekt-ID wieder. Handelt es sich nicht um das gewünschte Projekt, führen Sie den folgenden Befehl aus und ersetzen Sie dabei [PROJECT_ID] durch Ihre Projekt-ID:

       gcloud config set project [PROJECT_ID]
      

VM-Instanz

  1. Erstellen Sie eine Compute Engine-VM-Instanz:

    1. Wählen Sie in der Cloud Console Compute Engine > VM instances (VM-Instanzen) aus. Wählen Sie Create (Erstellen) aus. Wenn Sie die folgende Meldung sehen, warten Sie, bis Compute Engine bereit ist, bevor Sie fortfahren:

      Compute wird vorbereitet

    2. Wählen Sie unter Identity and API access (Identität und API-Zugriff) die Option Set access for each API (Zugriff für jede API festlegen) aus. Scrollen Sie durch die Einträge, bis Sie die Cloud Logging API finden. Ändern Sie den Zugriff von Write only (Nur Schreiben) zu Full (Vollständiger Zugriff):

      Compute wird vorbereitet

    3. Behalten Sie für alle anderen Einstellungen den Standardwert bei und klicken Sie auf Create (Erstellen): Nach kurzer Zeit steht Ihnen die VM-Instanz zur Verfügung.

  2. Gehen Sie zu SSH > Im Browserfenster öffnen, um eine Verbindung zur VM-Instanz-Shell herzustellen. Nach kurzer Zeit öffnet sich in einem Fenster eine Debian GNU/Linux-Shell und eine Begrüßungsnachricht wird angezeigt.

  3. Das Cloud SDK ist in der VM-Instanz vorinstalliert. Mit dem folgenden Befehl können Sie prüfen, ob Ihr Cloud SDK für das Compute Engine-Projekt konfiguriert ist:

     gcloud config list
    
  4. Wenn es sich bei dem aufgelisteten Projekt nicht um das gewünschte Projekt handelt, führen Sie den folgenden Befehl aus und ersetzen Sie dabei [PROJECT_ID] durch Ihre Projekt-ID:

     gcloud config set project [PROJECT_ID]
    

Logeinträge mit dem gcloud-Tool schreiben

Logging unterstützt Logeinträge mit strukturierten und unstrukturierten Daten. Strukturierte Daten haben eine JSON-Datenstruktur, zum Beispiel {"weather": "partly cloudy"}. Unstrukturierte Daten sind Strings, wie zum Beispiel "A simple entry". In den nächsten Schritten wird beschrieben, wie Sie mit dem gcloud-Tool einen Logeintrag mit unstrukturierten bzw. strukturierten Daten schreiben können:

  1. Logeintrag mit unstrukturierten Daten in das Log my-test-log schreiben:

    gcloud logging write my-test-log "A simple entry."
    

    Nach Verarbeitung des Befehls wird die folgende Meldung angezeigt: Created log entry.

  2. Logeintrag mit strukturierten Daten in my-test-log schreiben:

    gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
    

    Zum Schreiben eines Logeintrags mit strukturierten Daten müssen Sie --payload-type=json angeben. Wenn Sie dieses Feld weglassen, interpretiert Logging die Nutzlast als unstrukturierten Text.

Wenn das Log my-test-log nicht vorhanden ist, wird es von Logging erstellt, sobald der Logeintrag empfangen wird.

Logeinträge mit dem gcloud-Tool auflisten

Sie können Logeinträge aus Logging abrufen und mithilfe des gcloud-Tools anzeigen lassen. Führen Sie beispielsweise den folgenden Befehl aus, um die Logeinträge mit dem Ressourcentyp global abzurufen und anzeigen zu lassen:

gcloud logging read "resource.type=global"

Das Ergebnis des Befehls sollte in etwa so aussehen:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

Log-Einträge mit dem API Explorer auflisten

Sie können mit dem API Explorer Logging API-Methoden ausführen, ohne Code schreiben zu müssen. So rufen Sie eine Liste von Log-Einträgen aus Stackdriver Logging auf:

  1. Rufen Sie die API-Referenzseite für die API-Methode entries.list auf:

    Weiter zur API-Seite "entries.list"

  2. Das API Explorer-Widget wird angezeigt. Es hat den Header API testen. Kopieren Sie den folgenden Text und fügen Sie ihn in den Anfragetext ein. Ersetzen Sie die [PROJECT_ID], bevor Sie auf Ausführen klicken.

      "resourceNames": [
        "projects/[PROJECT_ID]"
      ],
      "filter": "resource.type=global",
      "orderBy": "timestamp desc"
    

    Unten finden Sie ein Beispiel für einen vollständigen Request body (Anfragetext) mit diesen Einstellungen:

    API testen

  3. Klicken Sie auf Execute (Ausführen). Die Methode gibt in etwa folgende Antwort zurück:

    {
      "entries": [
        {
          "textPayload": "A simple entry",
          "insertId": "vd4m1if7h7u1a",
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:19.718100792Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
        },
        {
          "insertId": "jpj9zjf73t1mn",
          "jsonPayload": {
            "message": "My second entry",
            "weather": "partly cloudy"
          },
          "resource": {
            "type": "global",
            "labels": {
              "project_id": "myloggingproject"
            }
          },
          "timestamp": "2018-11-01T18:39:31.114507977Z",
          "logName": "projects/myloggingproject/logs/my-test-log",
          "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
        }
      ]
    }
    

Logs in der Loganzeige ansehen

Die Loganzeige ist ein Tool zum Ansehen, Abfragen und Herunterladen von Logeinträgen. So rufen Sie Logs in der Loganzeige auf:

  1. Öffnen Sie in der Google Cloud Console die Loganzeige:

    Loganzeige aufrufen

    Sie sehen die Seite "Loganzeige":

    Loganzeige

    Wählen Sie in der Google Cloud-Navigationsleiste Ihr Projekt aus. Verwenden Sie die Drop-down-Liste für die Projekte, um gegebenenfalls Ihr Projekt auszuwählen.

  2. Wählen Sie in der Drop-down-Liste für den Ressourcentyp die Option Global aus, um sich die Logeinträge anzeigen zu lassen, die Sie geschrieben haben:

    Loganzeige

    Wenn die Menüoption Global oder Ihre Logeinträge nicht angezeigt werden, warten Sie einige Minuten und aktualisieren Sie dann die Seite. Der Empfang von Logeinträgen durch Logging kann einige Minuten dauern.

  3. Klicken Sie zum Maximieren eines Logeintrags auf den Rechtspfeil .

    Loganzeige

    Die Daten des ersten Logeintrags werden in textPayload gespeichert. Der zweite Logeintrag enthält strukturierte Daten, die in jsonPayload gespeichert sind. Die strukturierte Nutzlast enthält die Schlüssel message und weather.

Weitere Informationen zu Datenformaten für Logeinträge finden Sie unter Typ LogEntry.

Logeinträge in der Loganzeige abfragen

Sie können Log-Einträge anhand eines Textfeldes abfragen. Strukturierte Logs lassen sich anhand des Schlüssels oder des Werts abfragen. So können Sie beispielsweise alle Logeinträge anzeigen lassen, die den Text simple enthalten:

  1. Geben Sie in das Suchfeld den String simple ein. In der Loganzeige wird nur der Logeintrag A simple entry. angezeigt.

  2. Nachdem Sie das Log aufgerufen haben, entfernen Sie den hinzugefügten Abfragestring und klicken auf Aktualisieren (). Nun werden beide Logeinträge angezeigt.

So können Sie alle Logeinträge mit strukturierten Daten aufrufen, die den Schlüssel weather haben, wobei das Feld value partly enthält:

  1. Wechseln Sie in den erweiterten Abfragemodus, indem Sie im Suchfeld auf das Drop-down-Menü klicken und In erweiterten Filter umwandeln auswählen.
  2. Das Suchfeld enthält die Zeile resource.type="global". Geben Sie unter dieser Zeile folgende Zeile ein:

    jsonPayload.weather:partly
    
  3. Klicken Sie auf Submit filter (Filter senden). Das Ergebnis ist der einzelne Logeintrag My second entry:

    Erweiterte Abfrage von Logeinträgen

Weitere Informationen zu Abfragen finden Sie unter Erweiterte Logabfragen.

Fehlerbehebung

  • Schreibfehler und unbekannte Feldnamen führen dazu, dass Befehle vom gcloud-Tool Fehlermeldungen über ein Ungültiges Argument zurückgeben. Wenn Sie beispielsweise den Punkt in resource.type vergessen, führt dies zu folgendem Fehler:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • Wenn Cloud Logging nicht die erforderlichen Zugriffsberechtigungen erteilt wurden, werden Befehle vom gcloud-Tool mit der Meldung Berechtigung verweigert zurückgegeben. Beispiel: Wenn eine Compute Engine-VM-Instanz mit den Standard-API-Einstellungen konfiguriert ist, wird der Befehl list mit einem Fehler wegen verweigerter Berechtigung abgeschlossen:

     ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
    

    Ändern Sie zur Behebung dieses Fehlers die VM-Instanzberechtigungen in Compute Engine und erteilen Sie Cloud Logging Leseberechtigung. Gehen Sie dazu so vor:

    1. Gehen Sie zur Seite VM-Instanzdetails Ihrer VM-Instanz. Klicken Sie auf Beenden. Es kann ein bis zwei Minuten dauern, bis der Vorgang abgeschlossen ist.
    2. Klicken Sie auf Bearbeiten, um die Konfiguration zu ändern.
    3. Suchen Sie nach dem Header Zugriffsbereiche für Cloud API und klicken Sie auf Details, um sich die Einstellungen für jede API anzeigen zu lassen. Ändern Sie den Eintrag für die Cloud Logging API zu Vollständiger Zugriff. Klicken Sie dann auf Speichern.
    4. Klicken Sie auf Starten, um die VM-Instanz neu zu starten. Nach wenigen Augenblicken ist die VM einsatzbereit.
  • Wenn der API Explorer Ihren Befehl nicht ausführen kann oder eine zusätzliche Autorisierung erforderlich ist, wird eine Meldung oder ein Fehlercode angezeigt:

    • Antwortcode 200 und keine Einträge: Wenn die Nachricht nextPageToken angezeigt wird, bedeutet dies, dass API Explorer nicht ausreichend Zeit hatte, die Suche abzuschließen. Fügen Sie der Anfrage einen pageToken hinzu, stellen Sie diesen auf denselben Wert ein wie der des nextPageToken des Schlüssels und führen Sie dann den Befehl noch einmal aus.
    • Antwortcode 400: Der Abfragewert ist ungültig. Wenn Sie zum Beispiel gloobal statt global schreiben, wird die Meldung Unsupported resource type: gloobal zurückgegeben.
    • Antwortcode 404: Die Projekt-ID ist ungültig. Überprüfen Sie die Schreibweise der Projekt-ID.
    • Sie werden möglicherweise aufgefordert, sich bei Ihrem Google-Konto anzumelden und API Explorer den Zugriff auf Ihr Konto zu gewähren.

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud-Konto die in dieser Kurzanleitung verwendeten Ressourcen in Rechnung gestellt werden:

  1. (Optional) Führen Sie den folgenden gcloud-Befehl aus, um die erstellten Logeinträge zu löschen:

    gcloud logging logs delete my-test-log
    

    Wenn Sie Ihre Logeinträge nicht löschen, laufen sie ab und werden entfernt. Informationen zur Aufbewahrung finden Sie unter Kontingente und Limits.

Nächste Schritte

  • Ausführliche Informationen zur Befehlszeilenschnittstelle von Logging finden Sie auf den Referenzseiten für die Befehlsgruppe gcloud logging.
  • Dokumentation zur Logging API finden Sie unter Cloud Logging API.
  • Weitere Informationen zur Loganzeige finden Sie unter Loganzeige.
  • Informationen zum Erfassen von Logeinträgen aus VM-Instanzen in Logging finden Sie unter Informationen zum Logging-Agent.