Skip to main content
Używaj logbrew-flask w wersji 0.1.6 lub nowszej. Pakiet rejestruje spany żądań i nieobsłużone wyjątki. Opcjonalny handler logowania łączy logi Pythona ze śladem żądania. Metryki czasu trwania żądań też są opcjonalne. Pakiet wymaga Pythona 3.10 lub nowszego i Flaska 3.1 lub nowszego.
W aplikacji używaj serwerowego klucza wysyłania przypisanego do projektu. Nie używaj poświadczenia konta, które autoryzuje CLI.
Zastąp <project_id>, <trace_id> i <issue_id> identyfikatorami z LogBrew. Do żądań testowych użyj projektu deweloperskiego. Przykłady poleceń powłoki są napisane dla Basha.

Wyślij pierwsze żądanie

1

Utwórz lub wybierz klucz projektu

Zaloguj się w CLI. Potem użyj nowego lub istniejącego projektu. Nie uruchamiaj obu przykładów. Dla nowego projektu zapisz jego klucz wysyłania w nowym pliku, który może czytać tylko właściciel:
Dla istniejącego projektu pobierz jego ID z logbrew projects --json. Potem utwórz osobny klucz serwerowy:
CLI zapisuje klucz wysyłania z uprawnieniami tylko dla właściciela. Nie wypisuje klucza ani ścieżki jego pliku. W środowisku produkcyjnym zamiast tego pliku lokalnego użyj menedżera sekretów swojej platformy wdrożeniowej.Jeśli wynik żądania utworzenia jest niepewny, uruchom ponownie dokładnie to samo polecenie.
2

Zainstaluj wydaną integrację

Utwórz lub aktywuj środowisko wirtualne aplikacji, a potem zainstaluj pakiet frameworka. Pakiet instaluje też zgodną zależność, czyli podstawowe SDK.
3

Skonfiguruj tożsamość wdrożenia

Wczytaj klucz projektu lokalnie, nie wypisując go. Ustaw stałą usługę, środowisko i wydanie, aby każdy sygnał miał przydatny kontekst wdrożenia.
init_logbrew() sprawdza najpierw jawne argumenty, potem konfigurację aplikacji Flask, a na końcu te zmienne środowiskowe. Jeśli nazwa usługi nie jest skonfigurowana, używa nazwy importu aplikacji Flask.
4

Zainicjuj Flask tylko raz

W nowej aplikacji zapisz przykład jako app.py. Dodaj inicjalizator po utworzeniu aplikacji Flask. Handler logowania jest opcjonalny. Dzięki niemu logi aplikacji należą do aktywnego śladu i spanu żądania.
Kolejne wywołania init_logbrew(app) zwracają to samo rozszerzenie Flask. Nie instalują zduplikowanych hooków żądań ani wyjątków. Inicjalizator nie dodaje handlerów logowania. Dodaj handler jeden raz do loggera, którego właścicielem jest aplikacja.
5

Wykonaj jedno żądanie

Uruchom aplikację i wywołaj trasę z innego terminala. Jeśli twoja aplikacja używa innej nazwy modułu, zastąp app w poleceniu.
Dostarczanie działa w workerze w tle i nie blokuje odpowiedzi.
6

Sprawdź dowody w LogBrew

Odczytaj dokładny zakres projektu i wdrożenia. Szukaj śladu żądania health i skorelowanego logu z handlera logowania z przykładu.
Skopiuj zwrócone ID śladu do polecenia analizy o ograniczonym zakresie:
Zgodny odczyt potwierdza, że LogBrew zapisał sygnał. Lokalna odpowiedź 200 dowodzi tylko tego, że Flask obsłużył żądanie.

Wybierz potrzebne sygnały

Inicjalizator ma domyślnie włączone ślady żądań i nieobsłużone wyjątki. Metryki żądań i przekazywanie logów Pythona to osobne opcje. Zacznij od wartości domyślnych. Dodaj metryki żądań, gdy potrzebujesz widoku opóźnień. Handler logowania dodaj tylko do loggerów, które pomagają w analizie. Domyślnie inicjalizator ma własny transport HTTP. Umieszcza każde zdarzenie w kolejce, a worker w tle zaczyna dostarczanie, gdy tylko w kolejce pojawi się jedno zdarzenie. Dostarczanie nie blokuje odpowiedzi. Błędy transportu nie psują odpowiedzi Flask. flush_on_response=True wysyła zamiast tego zdarzenia z kolejki na ścieżce odpowiedzi. Z tą opcją raise_flush_errors=True zgłasza błędy dostarczania jako wyjątki. Używaj obu opcji tylko do kontrolowanej diagnostyki.

Kontroluj treść logów

Dodaj jeden LogBrewLoggingHandler do loggera, do którego należą potrzebne komunikaty. Handler nie zastępuje handlerów konsoli ani plików w aplikacji. Nie modyfikuje frameworka Flask ani modułu logowania Pythona. Dodanie tego samego handlera dwa razy duplikuje logi. Jeśli aplikacja używa też głównego loggera (root logger), sprawdź propagację, zanim dołączysz drugi handler. Log wewnątrz żądania dziedziczy aktywny ślad i span. Log poza żądaniem nie ma śladu żądania. Handler wysyła sformatowany komunikat, nazwę loggera i poziom LogBrew. Wysyła też nazwę pliku źródłowego, moduł, funkcję, wiersz oraz nazwy wątku i procesu, ale nie pełną ścieżkę źródła. Proste wartości z extra={...} stają się metadanymi. Sprawdź te wartości, zanim zaczniesz logować w żądaniach od użytkowników. Rekordy Pythona z poziomem DEBUG trafiają do LogBrew jako info. WARNING staje się warning, a CRITICAL – critical. Oryginalna nazwa i numer poziomu Pythona pozostają w metadanych. Aby wysyłać mniej rekordów, nadaj handlerowi własny poziom, na przykład LogBrewLoggingHandler(logbrew.client, level=logging.WARNING). Konsola i LogBrew mogą otrzymać ten sam rekord. Na przykład skonfiguruj konsolę, zanim utworzysz aplikację Flask:
Konsola dostaje sformatowany tekst. LogBrew zachowuje komunikat, poziom, logger i metadane jako osobne pola. Rekord logu z exc_info zawiera typ i komunikat wyjątku. Pełny tekst wyjątku jest wysyłany tylko wtedy, gdy handler ma include_exception_text=True. To coś innego niż automatyczna rejestracja wyjątków, która nigdy nie wysyła komunikatu wyjątku. Nie umieszczaj poświadczeń, danych osobowych ani treści żądań w komunikatach logów lub wyjątków.

Co rejestruje integracja

Nazwy spanów zawierają metodę HTTP i dopasowany szablon trasy. Na przykład /orders/100 i /orders/200 mają wspólną nazwę GET /orders/<int:order_id>. Niedopasowane żądanie dostaje stałą etykietę <unmatched>. Brakujący lub nieprawidłowy traceparent rozpoczyna nowy ślad. Metadane spanu zawierają metodę, szablon trasy, endpoint, kod statusu i czas trwania. Nie zawierają konkretnej ścieżki ani ciągu zapytania. W wersji 0.1.6 i nowszych span żądania obejmuje całą obsługę żądania przez Flask. Hooki before-request, handlery błędów i teardown należą do śladu żądania. Odpowiedź strumieniowa kończy swój span, gdy treść się skończy lub zostanie zamknięta.

Przetestuj rejestrację wyjątków

Status 4xx lub 5xx pojawia się w spanie żądania. Sam status nie dowodzi, że wystąpił wyjątek. Zanim zdiagnozujesz błąd, odczytaj zarówno ślady, jak i problemy. LogBrew nie zastępuje handlerów błędów Flask i nie zmienia statusu odpowiedzi. W projekcie deweloperskim dodaj tymczasową trasę. Wywołaj ją raz. Usuń ją przed wdrożeniem:
Żądanie zwraca status 500. Znajdź nowy problem i metrykę żądania:
Sprawdź usługę, środowisko, wydanie, typ wyjątku i ślad żądania w problemie. Problem nie może zawierać tekstu local capture check.

Połącz pracę wychodzącą z żądaniem

SDK dla Pythona ma helpery dla requests, urllib, httpx, aiohttp, bazy danych, pamięci podręcznej i kolejek, które aplikacja wywołuje sama. Każdy helper tworzy span podrzędny aktywnego śladu żądania. SDK nie modyfikuje tych bibliotek globalnie. Przykłady pokazuje pakiet logbrew-flask. Nadaj każdemu helperowi stałą nazwę operacji i szablon trasy lub zapytania. Nie umieszczaj w tych nazwach ID rekordów, wartości klientów, wartości parametrów SQL ani treści wiadomości. Spany podrzędne dodawaj tylko tam, gdzie zależność ma znaczenie dla żądania. Span dla każdego małego wywołania utrudnia czytanie śladu. Helpery wychodzących żądań HTTP dodają jeden nagłówek W3C traceparent. Nie rejestrują pełnych adresów URL, ciągów zapytań, treści, plików cookie ani dowolnych nagłówków. Helpery bazy danych, pamięci podręcznej i kolejek nie rejestrują wartości parametrów, wyników, wartości z pamięci podręcznej ani treści wiadomości z kolejki.

Prywatność i cykl życia procesu

Automatyczna rejestracja w aplikacji Flask pomija konkretne ścieżki żądań, ciągi zapytań, treści żądań i odpowiedzi, pliki cookie, dowolne nagłówki, surowe wartości traceparent, baggage i tracestate. Automatyczna rejestracja wyjątków nigdy nie odczytuje ani nie wysyła str(error). Używa stałego podsumowania Unhandled exception i oznacza każdy komunikat w łańcuchu wyjątków jako zamaskowany. Ramki zawierają nazwę pliku bez ścieżki i ograniczoną identyfikację kodu. Nie zawierają surowego tekstu traceback, kodu źródłowego, zmiennych lokalnych ani ścieżek bezwzględnych. Twórz aplikację i klienta LogBrew w każdym procesie workera. Domyślne ładowanie aplikacji osobno w każdym workerze Gunicorna działa. Nie używaj opcji --preload Gunicorna z klientem utworzonym w procesie nadrzędnym. W uWSGI ładuj aplikację osobno w każdym workerze, na przykład przez --lazy-apps. Klient Pythona odrzuca ponowne użycie po rozwidleniu procesu (fork). Wywołaj logbrew.client.shutdown() z hooka zamykania workera w menedżerze procesów. Metoda wysyła pozostałe zdarzenia z kolejki i zamyka klienta. Nie wywołuj jej po każdym żądaniu. Po zamknięciu klient odrzuca nowe zdarzenia z tego workera. Odpowiedź może się zakończyć, zanim worker wyśle ostatnie zdarzenia z kolejki. Podczas wdrożenia lub skalowania w dół kontrolowane zamknięcie daje tym zdarzeniom ostatnią próbę dostarczenia.

Rozwiąż problemy z konfiguracją

Błędy dostępu do konta, kluczy i odczytu opisuje strona Rozwiązywanie problemów. Inne środowiska uruchomieniowe opisuje strona Integracja SDK.