Zum Hauptinhalt springen
LogBrew ist eine Observability-Plattform für Entwickler und Coding-Agenten, mit großzügigem Gratis-Kontingent und ohne Karte. Dieser Leitfaden behandelt Python-Logging mit dem Standardmodul logging, die 5 Python-Log-Levels, die Fehlerbehandlung in Python und die häufigen Python-Fehlertypen. Die letzten Abschnitte senden dieselben Logs und Abstürze mit logbrew-sdk 0.1.29 an LogBrew. Jedes Beispiel lief unter Python 3.13. Jeder Ausgabeblock zeigt die echte Ausgabe. Für eine Flask-App verwenden Sie stattdessen Flask-Logging. Diese Anleitung ergänzt dieselbe Logging-Konfiguration um Anfrage-Traces.

Erstes Python-Log schreiben

Speichern Sie diese Datei als app.py. Rufen Sie logging.basicConfig() einmal am Einstiegspunkt des Programms auf. Holen Sie sich in jedem Modul einen benannten Logger.
Führen Sie python3 app.py aus. Die Ausgabe landet in der Standardfehlerausgabe.
Der Eintrag mit debug erscheint nicht, weil das Level INFO ist. logger.exception() schreibt mit ERROR und hängt den Traceback an. Rufen Sie die Methode nur in einem except-Block auf. Übergeben Sie Werte als Argumente, wie in "payment retry %d of %d", 2, 3. Python baut die Nachricht erst, wenn ein Handler den Eintrag annimmt. Die Nachrichtenvorlage bleibt bei jeder Wiederholung gleich. So können Sie danach suchen.

Python-Log-Levels

Ein Logger gibt einen Eintrag nur weiter, wenn dessen Level gleich oder höher als das Level des Loggers ist. Ein Handler kann ein zweites, höheres Level setzen. Der Root-Logger startet mit WARNING. Ein neuer Logger hat das Level NOTSET (0) und übernimmt das Level seines übergeordneten Loggers. Setzen Sie in der Produktion INFO und DEBUG nur in der Entwicklung oder für eine kurze Diagnose.
Die erste Zeile zeigt Debug-Einträge für ein Modul. Die zweite Zeile entfernt das Rauschen einer Bibliothek.

Logger, Handler und Formatter

  • Ein Logger nimmt den Aufruf an. Verwenden Sie logging.getLogger(__name__), damit der Name des Loggers dem Modulpfad folgt.
  • Ein Handler sendet Einträge an ein Ziel, zum Beispiel an die Konsole, an eine Datei oder an LogBrew.
  • Ein Formatter macht aus einem Eintrag Text.
Eine Bibliothek darf das Logging nicht konfigurieren. Sie fügt ihrem eigenen Logger nur einen logging.NullHandler() hinzu. Die Anwendung konfiguriert Handler und Levels einmal. Für eine große Konfiguration verwenden Sie logging.config.dictConfig().

Fehlerbehandlung in Python

Fangen Sie die spezifischste Ausnahme ab, die Sie behandeln können. Verwenden Sie else für Code, der nur bei Erfolg läuft. Verwenden Sie finally für Code, der immer läuft. Mit raise ... from error behalten Sie die ursprüngliche Ursache. Speichern Sie diese Datei als orders.py.
Die Ausgabe zeigt beide Ausnahmen der Ausnahmekette.
Befolgen Sie diese Regeln für jede Ausnahme.
  • Loggen Sie eine Ausnahme einmal, dort, wo Sie sie behandeln. Loggen und werfen Sie sie nicht in jeder Schicht erneut, denn jede Schicht fügt einen doppelten Eintrag hinzu.
  • Schreiben Sie nicht except Exception: pass. Wenn Sie einen Fehler ignorieren, loggen Sie ihn mit WARNING oder höher und nennen Sie den Grund.
  • Fangen Sie Exception ab, nicht BaseException. BaseException fängt auch KeyboardInterrupt und SystemExit ab. Diese beiden beenden das Programm absichtlich.
  • Definieren Sie eigene Ausnahmeklassen für Fehler, die Aufrufer behandeln müssen, so wie OrderError.

Mehrere Fehler melden

Python 3.11 und neuer kann eine ExceptionGroup auslösen. Verwenden Sie sie, wenn eine Prüfung mehr als ein Problem findet. Behandeln Sie jeden Typ mit except*.

Häufige Python-Fehlertypen

Alle eingebauten Fehler, die ein Programm behandeln kann, erben von Exception. Diese Tabelle listet die häufigsten Python-Fehler und die erste Prüfung für jeden Fehler. KeyboardInterrupt und SystemExit erben von BaseException, nicht von Exception. Sie sind keine Fehler in Ihrem Code.

Python-Logs an LogBrew senden

LogBrewLoggingHandler ist ein normaler Logging-Handler. Er sendet jeden Eintrag, den er annimmt, an LogBrew. Der Konsolen-Handler bleibt unverändert.
1

Projektschlüssel erstellen

Melden Sie sich mit der CLI an. Erstellen Sie ein Projekt und speichern Sie seinen Ingest-Schlüssel in einer Datei, die nur der Eigentümer lesen kann.
Die CLI gibt den Schlüssel nicht aus. Verwenden Sie in der Produktion den Secret Manager Ihrer Plattform.
2

SDK installieren

Aktivieren Sie die virtuelle Umgebung der Anwendung. Installieren Sie dann das Paket. Es erfordert Python 3.10 oder neuer.
3

Schlüssel und Bereitstellungsidentität setzen

Der Client fügt jedem Ereignis Dienst, Umgebung und Release hinzu.
4

Handler hinzufügen

Speichern Sie diese Datei als worker.py. Rufen Sie logging.basicConfig() auf, bevor Sie den Client erstellen. Der Client fügt dem Root-Logger einen Handler hinzu. basicConfig() tut nichts, wenn der Root-Logger schon einen Handler hat.
HttpTransport() sendet Ereignisse im Hintergrund, 1 Sekunde nach dem ersten Ereignis oder bei 50 Ereignissen. client.shutdown() sendet die restlichen Ereignisse und schließt den Client.
5

Programm ausführen

Die Konsolenausgabe ändert sich nicht. LogBrew erhält 1 Log-Ereignis pro Eintrag. Das ist das erste Ereignis, ohne den gemeinsamen Laufzeitkontext.
Primitive Werte aus extra={...} werden zu Metadaten. Das zweite Ereignis hat exceptionName KeyError und exceptionMessage 'seats'. Um den vollständigen Traceback-Text zu senden, erstellen Sie den Handler mit include_exception_text=True.
6

Logs zurücklesen

Ein passendes Ergebnis zeigt, dass LogBrew die Logs gespeichert hat. Für Lesezugriffe aus CI oder von einem Coding-Agenten verwenden Sie einen Projekt-Leseschlüssel. Siehe Einrichtung prüfen.

Auswählen, welche Einträge an LogBrew gehen

Geben Sie dem Handler ein eigenes Level, um weniger Einträge zu senden. Die Konsole erhält weiterhin INFO und höher.
Python-Levels werden zu LogBrew-Levels. Der ursprüngliche Name und die Zahl des Levels bleiben in den Metadaten.

Python-Abstürze als Issues melden

install_process_error_capture(client) meldet nicht abgefangene Ausnahmen in Skripten, Workern, Startcode und Threads. Jeder Absturz wird zu 1 Issue mit Ausnahmetyp, Meldung, Stackframes und verketteten Ursachen. Python gibt den Traceback weiterhin aus und beendet sich wie bisher. Speichern Sie diese Datei als startup.py und führen Sie sie aus.
LogBrew erhält ein Issue mit dem Titel FileNotFoundError, dem Level critical und dem Mechanismus python.excepthook. Seine Stackframes enthalten Dateiname, Zeile und Funktion, aber nicht den vollständigen Pfad. Ein Absturz in einem Thread hat das Level error. Bevor Python sich beendet, wartet das SDK höchstens 2 Sekunden auf die Zustellung.
Das Issue enthält die Ausnahmemeldung. Schreiben Sie keine Zugangsdaten und keine personenbezogenen Daten in Ausnahme- oder Log-Meldungen. Siehe Erfasste Daten steuern.

Probleme beheben

Für Web-Apps siehe Flask-Logging. Zur Wahl eines Log-Formats siehe Structured Logging. Für andere Laufzeiten siehe SDK-Integration.