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.
<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 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.
logbrew projects --json.
Potem utwórz osobny klucz serwerowy: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 Kolejne wywołania
app.py. Dodaj inicjalizator po
utworzeniu aplikacji Flask. Handler logowania jest opcjonalny. Dzięki niemu
logi aplikacji należą do aktywnego śladu i spanu żądania.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 Dostarczanie działa w workerze w tle i nie blokuje odpowiedzi.
app w poleceniu.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 jedenLogBrewLoggingHandler 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:
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
Status4xx 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:
500. Znajdź nowy problem i metrykę żądania:
local capture check.
Połącz pracę wychodzącą z żądaniem
SDK dla Pythona ma helpery dlarequests, 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ścitraceparent, 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.
