Logeinträge mit der gcloud CLI schreiben und abfragen

Logeinträge mit der gcloud CLI schreiben und abfragen

Mit der Google Cloud CLI können Sie Logeinträge in Cloud Logging über die Befehlszeile schreiben und abfragen. So können Sie die Logaufnahme testen und Logdaten prüfen, ohne Anwendungscode schreiben zu müssen. In dieser Kurzanleitung schreiben und listen Sie strukturierte und unstrukturierte Logeinträge mit der gcloud CLI auf, listen Logeinträge mit der Cloud Logging API auf und rufen Logs mit dem Log-Explorer auf und fragen sie ab.

Hinweis

Sie benötigen ein Google Cloud -Projekt mit aktivierter Abrechnung, um diese Kurzanleitung abzuschließen. Wenn Sie kein Google Cloud -Projekt haben oder die Abrechnung für Ihr Google Cloud -Projekt nicht aktiviert ist, gehen Sie so vor:

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach 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.

Installieren Sie die Google Cloud CLI.

Hinweis: Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die aktuelle Version haben, indem Sie gcloud components update ausführen.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Google Cloud -Projekt erstellen oder auswählen.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Project Creator“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• Erstellen Sie ein Projekt in Google Cloud :

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Projekt Google Cloud aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Wenn Sie für diese Anleitung ein vorhandenes Projekt verwenden, prüfen Sie, ob Sie die erforderlichen Berechtigungen haben. Wenn Sie ein neues Projekt erstellt haben, haben Sie bereits die erforderlichen Berechtigungen.

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud -Projekt aktiviert ist.

Installieren Sie die Google Cloud CLI.

Hinweis: Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die aktuelle Version haben, indem Sie gcloud components update ausführen.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Google Cloud -Projekt erstellen oder auswählen.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Project Creator“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• Erstellen Sie ein Projekt in Google Cloud :

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Projekt Google Cloud aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Wenn Sie für diese Anleitung ein vorhandenes Projekt verwenden, prüfen Sie, ob Sie die erforderlichen Berechtigungen haben. Wenn Sie ein neues Projekt erstellt haben, haben Sie bereits die erforderlichen Berechtigungen.

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud -Projekt aktiviert ist.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Logging-Administrator (roles/logging.admin) für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen, Auflisten und Löschen von Logeinträgen benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Die Rollen „Log-Autor“ (roles/logging.logWriter) und „Log-Betrachter“ (roles/logging.viewer) enthalten die Berechtigungen zum Erstellen und Auflisten von Logeinträgen. Wenn Sie Logeinträge löschen möchten, weisen Sie die Rolle „Logging-Administrator“ (roles/logging.admin) zu. Diese enthält die Berechtigungen zum Erstellen, Auflisten und Löschen von Logeinträgen. Beachten Sie, dass die Rolle „Logging-Administrator“ (roles/logging.admin) auch Berechtigungen zum Ausführen aller Aktionen in Logging gewährt.

Logeinträge mit der gcloud CLI schreiben

Logging unterstützt Logeinträge mit strukturierten und unstrukturierten Daten. Strukturierte Daten bestehen aus einer JSON-Datenstruktur, z. B. {"weather": "partly cloudy"}. Unstrukturierte Daten sind Strings, wie zum Beispiel "A simple entry".

In den nächsten Schritten verwenden Sie die gcloud CLI, um einen Logeintrag mit unstrukturierten Daten und einen Logeintrag mit strukturierten Daten zu schreiben. Die gcloud CLI bietet eine Befehlszeile für die Cloud Logging API.

1. Führen Sie den Befehl gcloud logging write aus, um einen Logeintrag mit unstrukturierten Daten in das Log my-test-log zu 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 der gcloud CLI auflisten

Sie können Logeinträge aus Logging abrufen und mit der gcloud CLI anzeigen lassen. Führen Sie beispielsweise den folgenden Befehl aus, um die Logeinträge mit dem Ressourcentyp global abzurufen und anzuzeigen:

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'

Informationen zum Lesen von Logs finden Sie in der Referenzdokumentation zu gcloud logging read.

Logeinträge mit APIs Explorer auflisten

Informationen zum Ausführen von Logging API-Methoden ohne Code finden Sie unter APIs Explorer verwenden. So rufen Sie eine Liste von Logeinträgen aus Logging ab:

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 das Feld Anfragetext des APIs Explorer 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 abfragen

Wenn Sie Logeinträge in der Google Cloud Console aufrufen möchten, können Sie den Log-Explorer verwenden. In den meisten Google Cloud -Projekten wird eine große Anzahl von Logs gespeichert. Sie können bestimmte Logeinträge auswählen, indem Sie 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 das Segment und die Seite Log-Explorer auf:

   Zum Log-Explorer

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

   Prüfen Sie, ob Ihr Google Cloud -Projekt in der Google Cloud-Navigationsleiste ausgewählt ist. Wählen Sie bei Bedarf Ihr Google Cloud -Projekt aus der Drop-down-Liste Google Cloud 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 dann 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.

   Hinweis: Wenn message ein Schlüssel für einen strukturierten Logeintrag ist, verwendet Stackdriver Logging diesen als Zusammenfassung des Logeintrags, wenn der Eintrag nicht maximiert ist.

Informationen zum Datenformat von Logeinträgen finden Sie unter LogEntry-Typ.

Logeinträge im Log-Explorer abfragen

Sie können Logeinträge mit dem Abfrageeditor und bei strukturierten Logs nach Schlüssel und Wert abfragen. So rufen Sie beispielsweise alle Logeinträge auf, die den Text simple enthalten:

1. Rufen Sie in der Google Cloud Console das Segment und die Seite Log-Explorer auf:

   Zum Log-Explorer

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis mit der Zwischenüberschrift Logging aus.

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

3. Geben Sie im Abfrageeditor den String simple in Anführungszeichen ein. In der Loganzeige wird nur der Logeintrag A simple entry. angezeigt.

4. Nachdem Sie sich das Log angesehen haben, entfernen Sie den hinzugefügten Abfragestring und klicken Sie auf Abfrage ausführen. Beide Log-Einträge werden wieder in der Anzeige dargestellt.

So rufen Sie alle Logeinträge mit strukturierten Daten auf, die den Schlüssel weather haben, wobei das Feld value den Wert partly enthält:

1. Der Abfrageeditor enthält die Zeile resource.type="global". Geben Sie den folgenden Befehl ein:

   jsonPayload.weather:partly
   

2. Klicken Sie auf Abfrage ausführen. Das Ergebnis ist der einzelne Logeintrag My second entry:

Der Log-Explorer bietet auch gespeicherte, vorgeschlagene und aktuelle Abfragen. Weitere Informationen zu Abfragen finden Sie unter Abfragen im Log-Explorer erstellen.

Beispielabfragen finden Sie unter Beispielabfragen mit dem Log-Explorer.

Fehlerbehebung

• Tippfehler und unbekannte Feldnamen führen dazu, dass die gcloud CLI-Befehle mit der Meldung Ungültiges Argument abgeschlossen werden. 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 hat, werden die gcloud CLI-Befehle mit der Meldung Berechtigung verweigert abgeschlossen. Wenn eine Compute Engine-VM-Instanz beispielsweise mit den Standard-API-Einstellungen konfiguriert ist, wird der Befehl list mit einem Fehler „Berechtigung verweigert“ beendet:

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

  So beheben Sie dieses Problem: Ändern Sie die Berechtigungen Ihrer Compute Engine-VM-Instanz, um Cloud Logging die Leseberechtigung zu erteilen:

  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 Meldung nextPageToken angezeigt wird, bedeutet dies, dass der APIs Explorer nicht genügend 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 beispielsweise global fälschlicherweise als gloobal schreiben, lautet die Meldung Unsupported resource type: gloobal.
  • Antwortcode 404: Die Projekt-ID ist ungültig. Überprüfen Sie die Schreibweise der Projekt-ID.
  • Möglicherweise werden Sie aufgefordert, sich in IhremGoogle Cloud -Projekt anzumelden und APIs Explorer Zugriff auf Ihr Konto zu gewähren.

Bereinigen

Löschen Sie das Projekt von Google Cloud zusammen mit den Ressourcen, damit Ihrem Konto von Google Cloud die auf dieser Seite verwendeten Ressourcen nicht 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 zum Log-Explorer finden Sie unter Log-Explorer verwenden.

• Informationen zum Erfassen von Logeinträgen von Ihren VM-Instanzen in Logging finden Sie unter Google Cloud Observability-Agents.