Logeinträge mit einem Python-Skript schreiben und abfragen

Mit der Cloud Logging-Clientbibliothek für Python können Sie Logeinträge programmatisch schreiben, abfragen und verwalten, um Ihre Anwendungen zu überwachen und Fehler zu beheben. In dieser Kurzanleitung verwenden Sie ein Python-Skript, um Logeinträge zu schreiben, anzusehen und zu löschen. Außerdem konfigurieren Sie eine Senke, um Logs an einen Cloud Storage-Bucket weiterzuleiten. Zusätzlich zu Cloud Storage-Buckets können Sie mit Logging Logeinträge an BigQuery-Datasets, Pub/Sub, Logging-Buckets und andere Google Cloud -Projekte weiterleiten.

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:
  1. 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.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  7. Verify that billing is enabled for your Google Cloud project.

In dieser Kurzanleitung werden Cloud Logging und Cloud Storage verwendet. Die Verwendung dieser Ressourcen kann Kosten für Sie verursachen. Löschen Sie die erstellten Ressourcen, nachdem Sie diese Kurzanleitung abgeschlossen haben, um fortlaufende Kosten zu vermeiden. Weitere Informationen finden Sie auf dieser Seite unter Bereinigen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen, Auflisten und Löschen von Logeinträgen und Cloud Storage-Buckets 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.

Erste Schritte

Sie können die Cloud Shell-Umgebung oder eine generische Linux-Umgebung für diese Kurzanleitung verwenden. Python ist in Cloud Shell vorinstalliert.

Cloud Shell

  1. Öffnen Sie die Cloud Shell und prüfen Sie die Konfiguration Ihres Google Cloud -Projekts:

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

      Die Cloud Shell wird in einem Fenster geöffnet und zeigt eine Willkommensnachricht an.

    2. In der Begrüßungsnachricht wird die konfigurierte Projekt-ID von Google Cloud angezeigt. Wenn dies nicht das Projekt von Google Cloud ist, das Sie verwenden möchten, führen Sie den folgenden Befehl aus, nachdem Sie PROJECT_ID durch die ID Ihres Projekts ersetzt haben:

      gcloud config set project PROJECT_ID

Linux

  1. Prüfen Sie, ob Python installiert und konfiguriert ist. Informationen zur Vorbereitung Ihres Rechners für die Python-Entwicklung finden Sie unter Python-Entwicklungsumgebung einrichten.

  2. Installieren Sie die Cloud Logging-Clientbibliothek:

    pip install --upgrade google-cloud-logging

  3. Richten Sie die IAM-Berechtigungen (Identity and Access Management) für Ihr Google Cloud -Projekt ein. In den folgenden Schritten erstellen Sie ein Dienstkonto für IhrGoogle Cloud -Projekt und generieren dann eine Datei, die Sie auf Ihre Linux-Workstation herunterladen.

    1. Rufen Sie in der Google Cloud Console die Seite Dienstkonten auf:

      Rufen Sie Dienstkonten auf.

      Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift IAM & Admin lautet.

    2. Wählen Sie Ihr Google Cloud -Projekt für die Kurzanleitung aus und klicken Sie dann auf Dienstkonto erstellen:

      • Geben Sie einen Kontonamen ein.
      • Geben Sie eine Kontobeschreibung ein.
      • Klicken Sie auf Erstellen und fortfahren.

    3. Klicken Sie auf das Feld Rolle auswählen und wählen Sie Logging-Administrator aus.

    4. Klicken Sie auf Fertig, um das Erstellen des Dienstkontos abzuschließen.

    5. Erstellen Sie eine Schlüsseldatei und laden Sie sie auf Ihre Workstation herunter:

      • Klicken Sie für Ihr Dienstkonto auf Weitere Optionen und wählen Sie Schlüssel verwalten aus.
      • Klicken Sie im Bereich Schlüssel auf Schlüssel hinzufügen.
      • Klicken Sie auf Neuen Schlüssel erstellen.

      • Wählen Sie als Schlüsseltyp JSON aus und klicken Sie dann auf Erstellen. Nach einem Moment wird in einem Fenster eine Meldung wie die folgende angezeigt:

        Privater Schlüssel auf Ihrem Computer gespeichert.

  4. Geben Sie auf Ihrer Linux-Workstation die Authentifizierungsdaten für Ihre Anwendung an, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrer Schlüsseldatei festlegen. Beispiel:

     export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/FILE_NAME.json"

    Diese Umgebungsvariable gilt nur für Ihre aktuelle Shell-Sitzung. Wenn Sie eine neue Sitzung öffnen, müssen Sie die Variable noch einmal festlegen.

Quellcode klonen

So konfigurieren Sie Cloud Shell für diese Kurzanleitung:

  1. Klonen Sie das GitHub-Projekt python-logging:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Das Verzeichnis samples/snippets enthält die beiden in dieser Kurzanleitung verwendeten Skripts:

    • Mit snippets.py können Sie Einträge in einem Log verwalten.
    • Mit export.py können Sie Logexporte verwalten.

  2. Wechseln Sie in das Verzeichnis snippets:

    cd logging/samples/snippets

Logeinträge schreiben

Das snippets.py-Skript verwendet die Python-Clientbibliotheken, um Logeinträge in das Logging zu schreiben. Wenn die Option write in der Befehlszeile angegeben ist, schreibt das Skript die folgenden Logeinträge:

  • Einen Eintrag mit unstrukturierten Daten und ohne angegebene Wichtigkeitsstufe
  • Einen Eintrag mit unstrukturierten Daten und der Wichtigkeitsstufe ERROR
  • Einen Eintrag mit strukturierten JSON-Daten und ohne angegebene Wichtigkeitsstufe

Zum Schreiben neuer Logeinträge in das Log my-log führen Sie das snippets.py-Skript mit der Option write aus:

python snippets.py my-log write

Logeinträge aufrufen

Führen Sie das snippets.py-Skript mit der Option list aus, um die Logeinträge in der Cloud Shell zu sehen:

python snippets.py my-log list

Der Befehl wird mit folgendem Ergebnis abgeschlossen:

Listing entries for logger my-log:
* 2025-11-13T16:05:35.548471+00:00: Hello, world!
* 2025-11-13T16:05:35.647190+00:00: Goodbye, world!
* 2025-11-13T16:05:35.726315+00:00: {u'favorite_color': u'Blue', u'quest': u'Find the Holy Grail', u'name': u'King Arthur'}

Wenn das Ergebnis keine Einträge enthält, wiederholen Sie den Befehl. Es dauert einige Momente, bis Stackdriver Logging Logeinträge empfängt und verarbeitet.

Sie können die von Ihnen geschriebenen Logeinträge auch mit dem Log-Explorer aufrufen. Weitere Informationen finden Sie unter Logs mit dem Log-Explorer aufrufen.

Logeinträge löschen

Wenn Sie alle Logeinträge im Log my-log löschen möchten, führen Sie das snippets.py-Skript mit der Option delete aus:

python snippets.py my-log delete

Der Befehl wird mit folgendem Ergebnis abgeschlossen:

Deleted all logging entries for my-log.

Logs weiterleiten

In diesem Abschnitt tun Sie Folgendes:

  • Einen Cloud Storage-Bucket als Zielort für Ihre Daten erstellen
  • Eine Datensenke erstellen, die neue Logeinträge zum Ziel kopiert
  • Die Berechtigungen Ihres Cloud Storage-Buckets aktualisieren
  • Logeinträge in Logging schreiben
  • Optional den Inhalt Ihres Cloud Storage-Buckets überprüfen

Zielort erstellen

Das Exportziel für diese Kurzanleitung ist ein Cloud Storage-Bucket. So erstellen Sie einen Cloud Storage-Bucket:

  1. Rufen Sie in der Google Cloud Console die Seite Buckets auf:

    Rufen Sie Buckets auf.

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Cloud Storage ist.

  2. Klicken Sie auf Bucket erstellen.
  3. Geben Sie einen Namen für den Bucket ein. In dieser Kurzanleitung wird der Name myloggingproject-1 verwendet.
  4. Wählen Sie als Standorttyp die Option Region aus, um einen Bucket-Standort mit der geringsten Latenz auszuwählen.
  5. Wählen Sie für Standardklasse festlegen die Option Standard aus.
  6. Wählen Sie für Zugriffssteuerung die Option Detailliert aus.
  7. Wählen Sie unter Schutztools die Option Keine aus und klicken Sie auf Erstellen.

Senke erstellen

Eine Senke ist eine Regel, die bestimmt, ob Stackdriver Logging einen neu eingetroffenen Logeintrag an einen Zielort weiterleitet. Eine Senke hat drei Attribute:

  • Name
  • Ziel
  • Filter

Weitere Informationen zu Senken finden Sie unter Informationen zu Logsenken.

Wenn ein neu eingetroffener Logeintrag die Abfragebedingungen erfüllt, wird dieser Logeintrag an den Zielort weitergeleitet.

Das Skript export.py verwendet die Python-Clientbibliotheken zum Erstellen, Auflisten, Ändern und Löschen von Senken. Führen Sie den folgenden Befehl aus, um die Senke mysink zu erstellen, die alle Logeinträge mit einem Schweregrad von mindestens INFO an den Cloud Storage-Bucket myloggingproject-1 sendet:

python export.py create mysink myloggingproject-1 "severity>=INFO"

Das Skript gibt Folgendes zurück:

Created sink mysink

Führen Sie das Skript export.py mit der Option list aus, um sich die Senken anzeigen zu lassen:

python export.py list

Das Skript gibt Folgendes zurück:

mysink: severity>=INFO -> storage.googleapis.com/myloggingproject-1

Zielberechtigungen aktualisieren

Die Berechtigungen des Ziels, in diesem Fall Ihres Cloud Storage-Buckets, ändern sich beim Erstellen einer Senke mit dem Skript export.py nicht. Sie müssen die Berechtigungseinstellungen Ihres Cloud Storage-Bucket ändern, um Schreibberechtigungen für Ihre Senke zu gewähren. Informationen zu Dienstkonten, Zugriffsbereichen und Identity and Access Management-Rollen finden Sie unter Dienstkonten.

So aktualisieren Sie die Berechtigungen für Ihren Cloud Storage-Bucket:

  1. Ermitteln Sie die Identität des Autors für die Senke:

    1. Rufen Sie in der Google Cloud Console die Seite Logs Router auf.

      Zu Logs Router

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

      Eine Zusammenfassungstabelle Ihrer Senken wird angezeigt.

    2. Suchen Sie Ihre Senke in der Tabelle, wählen Sie Menü und dann Senkendetails ansehen aus.

    3. Kopieren Sie die Identität des Autors in die Zwischenablage.

  2. Rufen Sie in der Google Cloud Console die Seite Buckets auf:

    Rufen Sie Buckets auf.

    Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Cloud Storage ist.

  3. Klicken Sie zum Öffnen der Detailansicht auf den Namen Ihres Buckets.

  4. Wählen Sie Berechtigungen aus und klicken Sie auf Zugriff gewähren.

  5. Fügen Sie die Identität des Autors in das Feld Neue Hauptkonten ein. Entfernen Sie das Präfix serviceAccount: aus der Adresse der Writer-Identität.

  6. Legen Sie die Rolle auf Storage Admin fest und klicken Sie dann auf Speichern.

Weitere Informationen finden Sie unter Zielberechtigungen festlegen.

Senke validieren

So prüfen Sie, ob Ihre Senke und Ihr Ziel ordnungsgemäß konfiguriert sind:

  1. Schreiben Sie neue Logeinträge in das Log my-log:

    python snippets.py my-log write

  2. Sehen Sie sich den Inhalt Ihres Cloud Storage-Buckets an:

    1. Rufen Sie in der Google Cloud Console die Seite Buckets auf:

      Rufen Sie Buckets auf.

      Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Cloud Storage ist.

    2. Klicken Sie zum Öffnen der Detailansicht auf den Namen Ihres Buckets. In der Detailansicht werden die Ordner aufgelistet, die Daten enthalten. Wenn sich in Ihrem Bucket keine Daten befinden, wird die folgende Meldung angezeigt:

      There are no live objects in this bucket.

      Wie unter Verspätet eingehende Logeinträge beschrieben, kann es zwei oder drei Stunden dauern, bis die ersten Einträge am Ziel angezeigt werden oder bis Sie über einen Konfigurationsfehler benachrichtigt werden.

      Nachdem Ihr Bucket Daten erhalten hat, zeigt die Detailansicht ein Ergebnis wie das folgende an:

      Detailansicht des Bucket-Inhalts.

    3. Die Daten in jedem Bucket sind in einer Reihe von Ordnern organisiert. Diese sind folgendermaßen benannt: der Ordner auf der obersten Ebene nach dem Lognamen und die Ordner auf den untergeordneten Ebenen anschließend nacheinander nach Jahr, Monat und Tag. Wenn Sie die von Ihrer Senke exportierten Daten sehen möchten, klicken Sie auf den Ordnernamen my-log und dann durch die Unterordner für Jahr, Monat und Tag, bis Sie eine Datei mit der Endung json finden:

      Unterordneransicht des Bucket-Inhalts.

    4. Die JSON-Datei enthält die Logeinträge, die in Ihren Cloud Storage-Bucket exportiert wurden. Klicken Sie auf den Namen der JSON-Datei, um den Inhalt anzuzeigen. Er sieht etwa so aus:

       {"insertId":"yf1cshfoivz48",
 "logName":"projects/loggingproject-222616/logs/my-log",
 "receiveTimestamp":"2018-11-15T23:06:14.738729911Z",
 "resource":{"labels":{"project_id":"loggingproject-222616"},"type":"global"},
 "severity":"ERROR",
 "textPayload":"Goodbye, world!",
 "timestamp":"2018-11-15T23:06:14.738729911Z"}

      Da die Wichtigkeitsstufe ERROR die Wichtigkeitsstufe INFO übersteigt, wird der Log-Eintrag mit dem String "Goodbye, world!" an den Zielort der Senke exportiert. Die anderen geschriebenen Logeinträge wurden nicht an das Ziel exportiert, da ihre Wichtigkeitsstufe auf den Standardwert gesetzt war und die Standard-Wichtigkeitsstufe niedriger als INFO ist.

Fehlerbehebung

Es gibt mehrere Gründe, warum ein Cloud Storage-Bucket möglicherweise leer ist:

  • Der Bucket hat keine Daten empfangen. Es kann zwei bis drei Stunden dauern, bis die ersten Einträge am Ziel vorhanden sind oder Sie über einen Konfigurationsfehler informiert werden. Weitere Informationen finden Sie unter Spät eingehende Logeinträge.

  • Ein Konfigurationsfehler ist aufgetreten. In diesem Fall erhalten Sie eine E-Mail-Nachricht mit einer Betreffzeile ähnlich der folgenden:

     [ACTION REQUIRED] Logging export config error in myloggingproject.

    Der Inhalt des E-Mail-Texts beschreibt das Konfigurationsproblem. Wenn Sie beispielsweise Ihre Zielberechtigungen nicht aktualisieren, wird in der E-Mail der folgende Fehlercode aufgeführt:

     bucket_permission_denied

    Informationen zum Beheben dieses Problems finden Sie auf dieser Seite unter Zielberechtigungen aktualisieren.

  • Nach dem Erstellen der Senke wurden keine Logeinträge geschrieben. Die Senke wird nur auf neue Logeinträge angewendet. Wenn Sie diese Situation korrigieren möchten, schreiben Sie neue Logeinträge:

     python snippets.py my-log write

Bereinigen

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

  1. (Optional) Löschen Sie die Logeinträge, die Sie erstellt haben. Wenn Sie Ihre Logeinträge nicht löschen, verfallen sie und werden entfernt. Siehe Kontingente und Limits.

    Führen Sie den folgenden Befehl aus, um alle Logeinträge im Log my-log zu löschen:

     python snippets.py my-log delete

  2. Löschen Sie Ihr Projekt von Google Cloud oder Ihre Kurzanleitungsressourcen.

    • Wenn Sie Ihr Google Cloud Projekt löschen möchten, klicken Sie in derGoogle Cloud Console im Bereich Projektinformationen auf Zu den Projekteinstellungen und dann auf Beenden.

    • So löschen Sie Ihre Schnellstartressourcen:

      1. Löschen Sie Ihre Senke mit dem folgenden Befehl:

        python export.py delete mysink

      2. Löschen Sie den Cloud Storage-Bucket. Rufen Sie die Google Cloud Console auf und klicken Sie auf Storage > Buckets. Setzen Sie ein Häkchen in das Kästchen neben dem Bucket-Namen und klicken Sie dann auf Löschen.

Nächste Schritte