Przejdź do głównej treści
LogBrew to platforma obserwowalności dla programistów i agentów kodujących. Ma hojny darmowy plan i nie wymaga karty. Ten przewodnik opisuje logowanie w Pythonie ze standardowym modułem logging, 5 poziomów logowania w Pythonie, obsługę błędów w Pythonie i najczęstsze typy błędów Pythona. Ostatnie sekcje wysyłają te same logi i awarie do LogBrew przez logbrew-sdk 0.1.29. Każdy przykład uruchomiono w Pythonie 3.13, a każdy blok wyniku pokazuje prawdziwy wynik. W aplikacji Flask użyj zamiast tego przewodnika Logowanie w aplikacji Flask. Dodaje on ślady żądań do tej samej konfiguracji logowania.

Napisz pierwszy log w Pythonie

Zapisz ten plik jako app.py. Wywołaj logging.basicConfig() jeden raz, w punkcie wejścia programu. W każdym module pobierz nazwany logger.
Uruchom python3 app.py. Wynik trafia na standardowe wyjście błędów.
Rekord debug się nie pojawia, bo poziom to INFO. logger.exception() loguje na poziomie ERROR i dodaje traceback. Wywołuj tę metodę tylko w bloku except. Przekazuj wartości jako argumenty, jak w "payment retry %d of %d", 2, 3. Python buduje komunikat dopiero wtedy, gdy handler przyjmie rekord. Szablon komunikatu jest taki sam przy każdej ponownej próbie, więc łatwo go wyszukać.

Poziomy logowania w Pythonie

Logger wysyła rekord tylko wtedy, gdy poziom rekordu jest równy poziomowi loggera lub od niego wyższy. Handler może ustawić drugi, wyższy poziom. Główny logger (root logger) startuje z poziomem WARNING. Nowy logger ma poziom NOTSET (0) i używa poziomu swojego rodzica. Na produkcji ustaw INFO, a DEBUG włączaj tylko w środowisku deweloperskim lub na czas krótkiej diagnozy.
Pierwszy wiersz pokazuje rekordy debug jednego modułu. Drugi wiersz wycisza szum z biblioteki.

Loggery, handlery i formattery

  • Logger przyjmuje wywołanie. Użyj logging.getLogger(__name__), aby nazwa loggera odpowiadała ścieżce modułu.
  • Handler wysyła rekordy do miejsca docelowego, na przykład do konsoli, pliku lub LogBrew.
  • Formatter zamienia rekord na tekst.
Biblioteka nie może konfigurować logowania. Dodaje tylko logging.NullHandler() do własnego loggera. Aplikacja konfiguruje handlery i poziomy jeden raz. Przy dużej konfiguracji użyj logging.config.dictConfig().

Obsługa błędów w Pythonie

Przechwytuj najbardziej konkretny wyjątek, który umiesz obsłużyć. Użyj else dla kodu, który działa tylko po sukcesie, a finally dla kodu, który działa zawsze. Użyj raise ... from error, aby zachować pierwotną przyczynę. Zapisz ten plik jako orders.py.
Wynik pokazuje oba wyjątki z łańcucha wyjątków.
Stosuj te zasady przy każdym wyjątku.
  • Loguj wyjątek raz, w miejscu, w którym go obsługujesz. Nie loguj go i nie zgłaszaj ponownie w każdej warstwie, bo każda warstwa doda zduplikowany rekord.
  • Nie pisz except Exception: pass. Jeśli ignorujesz błąd, zaloguj go razem z powodem na poziomie WARNING lub wyższym.
  • Przechwytuj Exception, a nie BaseException. BaseException przechwytuje też KeyboardInterrupt i SystemExit, które celowo zatrzymują program.
  • Twórz własne klasy wyjątków dla błędów, które musi obsłużyć kod wywołujący, tak jak robi to OrderError.

Zgłoś kilka błędów naraz

Python 3.11 i nowszy może zgłosić ExceptionGroup. Użyj go, gdy jedna walidacja znajdzie więcej niż jeden błąd. Każdy typ obsłuż przez except*.

Najczęstsze typy błędów w Pythonie

Wszystkie wbudowane błędy, które program może obsłużyć, dziedziczą po Exception. Ta tabela pokazuje najczęstsze błędy Pythona i to, co sprawdzić najpierw przy każdym z nich. KeyboardInterrupt i SystemExit dziedziczą po BaseException, a nie po Exception. Nie są to błędy w twoim kodzie.

Wysyłaj logi Pythona do LogBrew

LogBrewLoggingHandler to standardowy handler logowania. Wysyła do LogBrew każdy rekord, który przyjmie. Handler konsoli się nie zmienia.
1

Utwórz klucz projektu

Zaloguj się w CLI. Utwórz projekt i zapisz jego klucz wysyłania w pliku, który może czytać tylko właściciel.
CLI nie wyświetla klucza. Na produkcji używaj menedżera sekretów swojej platformy.
2

Zainstaluj SDK

Aktywuj środowisko wirtualne aplikacji. Potem zainstaluj pakiet. Wymaga on Pythona 3.10 lub nowszego.
3

Ustaw klucz i tożsamość wdrożenia

Klient dodaje usługę, środowisko i wydanie do każdego zdarzenia.
4

Dodaj handler

Zapisz ten plik jako worker.py. Wywołaj logging.basicConfig(), zanim utworzysz klienta. Klient dodaje handler do głównego loggera, a basicConfig() nic nie robi, gdy główny logger ma już handler.
HttpTransport() wysyła zdarzenia w tle, 1 sekundę po pierwszym zdarzeniu albo po zebraniu 50 zdarzeń. client.shutdown() wysyła pozostałe zdarzenia i zamyka klienta.
5

Uruchom program

Wynik w konsoli się nie zmienia. LogBrew dostaje 1 zdarzenie logu na każdy rekord. Oto pierwsze zdarzenie bez wspólnego kontekstu środowiska uruchomieniowego.
Proste wartości z extra={...} trafiają do metadanych. Drugie zdarzenie ma exceptionName KeyError i exceptionMessage 'seats'. Aby wysłać pełny tekst tracebacku, utwórz handler z include_exception_text=True.
6

Odczytaj logi

Pasujący wynik odczytu pokazuje, że LogBrew zapisał logi. Aby czytać logi z CI lub z agenta kodującego, użyj klucza odczytu projektu. Szczegóły znajdziesz w przewodniku Sprawdź konfigurację.

Wybierz rekordy, które trafiają do LogBrew

Nadaj handlerowi własny poziom, aby wysyłać mniej rekordów. Konsola nadal dostaje INFO i wyższe poziomy.
Poziomy Pythona zmieniają się w poziomy LogBrew. Pierwotna nazwa i liczba poziomu zostają w metadanych.

Zgłaszaj awarie Pythona jako problemy

install_process_error_capture(client) zgłasza nieprzechwycone wyjątki w skryptach, workerach, kodzie startowym i wątkach. Każda awaria staje się 1 problemem z typem wyjątku, komunikatem, ramkami stosu i przyczynami z łańcucha wyjątków. Python nadal wypisuje traceback i kończy działanie tak jak wcześniej. Zapisz ten plik jako startup.py i uruchom go.
LogBrew dostaje problem z tytułem FileNotFoundError, poziomem critical i mechanizmem python.excepthook. Jego ramki zawierają nazwę pliku, wiersz i funkcję, ale nie pełną ścieżkę. Awaria w wątku ma poziom error. Zanim Python zakończy działanie, SDK czeka na dostarczenie zdarzeń najwyżej 2 sekundy.
Problem zawiera komunikat wyjątku. Nie umieszczaj poświadczeń ani danych osobowych w komunikatach wyjątków i logów. Szczegóły znajdziesz w przewodniku Kontrola rejestrowanych danych.

Rozwiązywanie problemów

Dla aplikacji webowych zobacz przewodnik Logowanie w aplikacji Flask. Format logów pomoże ci wybrać przewodnik Logowanie strukturalne. Inne środowiska uruchomieniowe opisuje przewodnik Integracja SDK.