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 dem Log-Explorer aufrufen und abfragen

Hinweis

Sie benötigen ein Google Cloud-Projekt mit aktivierter Abrechnungsfunktion, um diese Kurzanleitung durchzuarbeiten. Wenn Sie kein Cloud-Projekt haben oder die Abrechnung für Ihr Projekt nicht aktiviert ist, gehen Sie so vor:
  1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
  2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

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

  4. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

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

Erste Schritte

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. Das Cloud SDK ist in der Cloud Shell-Umgebung vorinstalliert.

Cloud Shell

Prüfen Sie, ob das Cloud SDK für die Verwendung des richtigen Cloud-Projekts konfiguriert ist:

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

    Screenshot der Cloud Shell-Schaltfläche in der Cloud Console

    Cloud Shell wird in einem Fenster geöffnet und zeigt eine Willkommensnachricht an. Die Willkommensnachricht gibt die konfigurierte Projekt-ID wieder:

    Screenshot von Cloud Shell mit einer Willkommensnachricht

  2. Wenn Sie ein anderes Cloud-Projekt als in der Begrüßungsnachricht verwenden möchten, führen Sie den folgenden Befehl aus und ersetzen Sie dabei PROJECT_ID durch Ihre Projekt-ID:

        gcloud config set project PROJECT_ID
    

    Informationen zum Abrufen der Projekt-ID finden Sie unter Projekte erstellen und verwalten.

VM-Instanz

So erstellen Sie eine Compute Engine-VM-Instanz in der Cloud Console:

  1. Wählen Sie in der Cloud Console die Option Compute Engine und dann VM-Instanzen aus.
  2. Wählen Sie Instanz erstellen aus.

  3. Wählen Sie unter Identität und API-Zugriff für Zugriffsbereiche die Option Zugriff für jede API festlegen aus.

  4. Scrollen Sie durch die APIs, bis Sie die Stackdriver Logging API finden. Stellen Sie den Zugriff auf Vollzugriff ein.

  5. Behalten Sie für alle anderen Einstellungen den Standardwert bei und klicken Sie auf Create (Erstellen): Die VM-Instanz ist einsatzbereit.

  6. Klicken Sie auf SSH, um eine Verbindung zur VM-Instanz-Shell herzustellen. Nach kurzer Zeit wird eine Debian GNU/Linux-Shell in einem Fenster geöffnet und eine Begrüßungsnachricht wird angezeigt.

  7. Prüfen Sie mit dem folgenden Befehl, ob das Cloud SDK, das vorinstalliert ist, für Ihr Compute Engine-Projekt konfiguriert ist:

    gcloud config list
    
  8. Wenn das aufgelistete Cloud-Projekt nicht das ist, das Sie verwenden möchten, führen Sie den folgenden Befehl aus und ersetzen Sie PROJECT_ID durch Ihre Projekt-ID:

       gcloud config set project PROJECT_ID
    

    Informationen zum Abrufen der Projekt-ID finden Sie unter Projekte erstellen und verwalten.

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. Schreiben Sie einen Logeintrag mit strukturierten Daten in das Log my-test-log:

    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 unstrukturierte Daten.

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 mit dem gcloud-Tool aufrufen. 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'

Logeinträge mit APIs Explorer auflisten

Verwenden Sie APIs Explorer, um Methoden der Logging API auszuführen, ohne Code zu schreiben. So lesen Sie eine Liste der Logeinträge aus Logging:

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

    Weiter zur API-Seite "entries.list"

  2. Konfigurieren Sie den API-Befehl und führen Sie ihn aus:

    1. Ersetzen Sie PROJECT_ID im folgenden Text:

        "resourceNames": [
          "projects/PROJECT_ID"
        ],
        "filter": "resource.type=global",
        "orderBy": "timestamp desc"
      
    2. Kopieren Sie den aktualisierten Text aus dem vorherigen Schritt und fügen Sie ihn in APIs Explorer in das Feld Anfragetext ein.

    3. Klicken Sie auf 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"
        }
      ]
    }
    

Logeinträge im Log-Explorer ansehen

Zum Aufrufen von Logeinträgen können Sie den Log-Explorer verwenden. Da in den meisten Cloud-Projekten eine große Anzahl von Logs gespeichert wird, können Sie bestimmte Logeinträge aufrufen, indem Sie Filter hinzufügen oder eine Abfrage schreiben.

So rufen Sie die Logeinträge auf, die Sie mit dem Log-Explorer geschrieben haben:

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

    Zum Log-Explorer

    Achten Sie darauf, dass Ihr Cloud-Projekt in der Google Cloud-Navigationsleiste ausgewählt ist. Wählen Sie bei Bedarf das Cloud-Projekt in der Drop-down-Liste aus.

  2. Wählen Sie im Menü Ressource die Option Global aus.

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

  3. Klicken Sie auf das Menü , um die Details eines Logeintrags aufzurufen.

    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.

Informationen zu den Datenformaten von Logeinträgen finden Sie unter LogEntry.

Logeinträge im Log-Explorer 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. Rufen Sie in der Google Cloud Console den Log-Explorer auf:

    Zum Log-Explorer

  2. Wählen Sie im Menü Ressource die Option Global aus.

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

  4. 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 den folgenden Befehl ein:

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

Außerdem enthält der Log-Explorer gespeicherte, vorgeschlagene und kürzlich durchgeführte Abfragen. Weitere Informationen zu Abfragen finden Sie unter Abfragen im Log-Explorer erstellen.

Beispielabfragen finden Sie unter Beispielabfragen mit dem Log-Explorer.

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 APIs 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 APIs 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 APIs Explorer Zugriff auf Ihr Konto zu gewähren.

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud-Konto die in dieser Anleitung 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, verfallen sie und werden entfernt. Informationen zur Aufbewahrung finden Sie unter Kontingente und Limits.

Nächste Schritte