Logi błędów w Drupal – gdzie ich szukać i jak je czytać

Logi błędów w Drupal potrafią być najlepszym przyjacielem programisty… albo jego największym koszmarem. To od nich zależy, jak szybko znajdziesz przyczynę białego ekranu śmierci, niedziałającej wtyczki czy niespodziewanego spadku wydajności. Zrozumienie, gdzie szukać komunikatów o błędach i jak je interpretować, pozwala skrócić czas debugowania z godzin do minut. Poniżej znajdziesz praktyczny przewodnik po najważniejszych miejscach z logami i sposobach ich czytania w Drupal 7, 8, 9 i 10.

Podstawowe typy logów w Drupal

Różnica między logami PHP, serwera i Drupal

Drupal korzysta z kilku warstw mechanizmów raportowania błędów. Na samym dole znajdują się logi samego PHP – to one przechowują informacje o fatal errorach, ostrzeżeniach i notice’ach generowanych przez kod. Druga warstwa to logi serwera WWW, najczęściej Apache lub Nginx, które przechowują zarówno błędy PHP, jak i problemy z konfiguracją serwera, przekierowaniami czy dostępem do plików. Trzecia, najwyższa warstwa to logi Drupal, zapisywane domyślnie w bazie danych (Watchdog) lub w plikach, jeśli włączysz odpowiednie moduły. Dopiero łączna analiza tych źródeł daje pełny obraz problemu.

Rozumienie, z której warstwy pochodzi dany komunikat, pomaga zdecydować, od czego zacząć debugowanie. Biały ekran i brak jakichkolwiek zapisów w logach Drupala często oznaczają krytyczny błąd PHP, który w ogóle nie pozwolił na uruchomienie systemu CMS. Z kolei informacja o nieudanym logowaniu użytkownika niemal zawsze znajduje się w logach Drupala, ponieważ jest to zdarzenie obsługiwane na poziomie aplikacji, a nie samego języka PHP czy serwera.

Poziomy błędów: notice, warning, error, critical

Logi Drupala i PHP korzystają z różnych poziomów istotności wpisów. Typowe poziomy to: notice, warning, error, critical, alert, emergency. Mniej istotne komunikaty, takie jak notice, informują o potencjalnie problematycznym, ale wciąż działającym fragmencie kodu – przykładowo o użyciu niezainicjalizowanej zmiennej. Wpis typu warning sygnalizuje już poważniejszy kłopot, ale system zwykle nadal funkcjonuje. Natomiast error lub critical oznaczają, że funkcja, proces lub cała strona mogły przestać działać zgodnie z oczekiwaniami.

W Drupalu spotkasz się również z logowaniem zdarzeń informacyjnych, takich jak sukces logowania czy wyczyszczenie cache. Pomimo że nie są to błędy, potrafią pomóc w odtworzeniu chronologii zdarzeń, które doprowadziły do usterki. Analizując logi, warto filtrować je po poziomie istotności, koncentrując się najpierw na error i critical, a dopiero później na warning oraz notice.

Dlaczego brak logów też jest informacją

Czasami najtrudniejsze do zdiagnozowania problemy to te, które nie zostawiają żadnego śladu w logach Drupala. Gdy panel administracyjny przestaje odpowiadać, a raporty zdarzeń są puste, może to oznaczać, że kod zatrzymuje się, zanim system zdąży zapisać komunikat. Taka sytuacja często wskazuje na błąd PHP, przekroczenie limitu pamięci lub problem na poziomie serwera.

W takich przypadkach kluczowe staje się sięgnięcie po logi serwera i PHP oraz tymczasowe włączenie wyświetlania błędów bezpośrednio w przeglądarce (na środowisku deweloperskim). Brak wpisu w raportach Drupala nie powinien być interpretowany jako brak problemu, ale jako sygnał, że trzeba zmienić poziom, na którym analizujesz zdarzenie.

Gdzie znaleźć logi błędów w panelu administracyjnym

Raporty zdarzeń (dblog) w Drupal 7, 8, 9, 10

Najbardziej oczywistym miejscem do przeglądania logów jest wbudowany moduł dblog, w interfejsie nazywany Raporty zdarzeń. W Drupal 8, 9 i 10 znajdziesz go zwykle pod ścieżką /admin/reports/dblog, a w Drupal 7 pod podobną lokalizacją. Moduł ten zapisuje wpisy w bazie danych, w tabeli watchdog, prezentując je w formie czytelnej listy z możliwością filtrowania po typie, użytkowniku, poziomie błędu oraz przedziale czasowym.

Dzięki raportom zdarzeń możesz łatwo wykryć powtarzające się błędy, takie jak brakujący plik, błędna konfiguracja modułu czy problemy z uprawnieniami. To narzędzie sprawdza się szczególnie dobrze na środowiskach, gdzie nie masz bezpośredniego dostępu do serwera, ale możesz zalogować się do panelu administracyjnego Drupala. W praktyce wielu administratorów rozpoczyna analizę właśnie od dblog, a dopiero później sięga po logi systemowe.

Konfiguracja poziomu rejestrowania błędów w interfejsie

Drupal pozwala ustawić, jak szczegółowo mają być rejestrowane błędy. W Drupal 7 znajdziesz te ustawienia w sekcji Konfiguracja → Rozwój → Logowanie i błędy. Możesz tam wskazać, czy błędy mają być wyświetlane w przeglądarce, logowane w bazie lub w obu miejscach, oraz określić poziom szczegółowości. W nowszych wersjach Drupala (8+) część konfiguracji przeniosła się do plików konfiguracyjnych, ale nadal istnieją ustawienia związane z logowaniem, dostępne z poziomu interfejsu.

Zbyt szczegółowe logowanie na środowisku produkcyjnym może skutkować znacznym rozrostem bazy danych oraz spadkiem wydajności, dlatego dobrym kompromisem jest rejestrowanie głównie błędów typu error, critical oraz ważnych warning. Na środowiskach deweloperskich warto natomiast włączyć bardziej szczegółowe logowanie, aby wychwycić nawet drobne problemy, zanim trafią na serwer produkcyjny.

Przeglądanie szczegółów pojedynczego wpisu

Każdy wpis w logach Drupala można rozwinąć, przechodząc do szczegółów. Znajdziesz tam m.in. pełną treść komunikatu, typ zdarzenia, poziom istotności, identyfikator użytkownika oraz ścieżkę URL, dla której wystąpił błąd. Bardzo przydatnym elementem jest również ślad stosu (backtrace), jeśli został wygenerowany. Pozwala on odtworzyć łańcuch wywołań funkcji, który doprowadził do błędu.

Analizując pojedynczy wpis, zwracaj uwagę na powtarzające się elementy: ten sam moduł, ta sama ścieżka, ten sam typ błędu. Często jeden błąd generuje dziesiątki podobnych wpisów w logu – zidentyfikowanie ich wspólnego mianownika znacznie skraca proces debugowania. Zdarza się również, że jedna niegroźna z pozoru notice prowadzi po pewnym czasie do poważniejszego problemu, dlatego warto nie ignorować pozornie drobnych ostrzeżeń.

Logi na poziomie serwera: Apache, Nginx, PHP

Typowe lokalizacje plików logów

Jeśli masz dostęp do serwera, najwięcej informacji znajdziesz w logach serwera WWW oraz PHP. W systemach opartych na Linuxie logi Apache często znajdują się w katalogu /var/log/apache2/ (Ubuntu, Debian) lub /var/log/httpd/ (CentOS, Fedora). W przypadku Nginx typowym miejscem jest /var/log/nginx/. Plik error.log zawiera informacje o błędach, podczas gdy access.log przechowuje listę wszystkich żądań wraz z kodami odpowiedzi HTTP.

Logi PHP mogą być połączone z logami serwera lub zapisywane w osobnym pliku, definiowanym w konfiguracji php.ini w dyrektywie error_log. Lokalizacja ta bywa różna w zależności od hostingu, dlatego warto zapoznać się z dokumentacją dostawcy lub poprosić o informację dział wsparcia. Bez dostępu do tych plików nie zdiagnozujesz wielu krytycznych błędów, które zatrzymują działanie Drupala jeszcze przed inicjalizacją systemu.

Typowe wpisy błędów PHP i jak je czytać

W logach PHP znajdziesz komunikaty zawierające datę, typ błędu, plik, numer linii oraz treść problemu. Przykładowy wpis może wyglądać tak: PHP Fatal error: Call to undefined function w pliku includes/bootstrap.inc on line 1234. Słowo Fatal oznacza, że skrypt został zatrzymany i dalsze wykonywanie kodu nie było możliwe. Błędy tego typu zazwyczaj generują biały ekran lub częściowo załadowaną stronę.

Kluczowe elementy to typ błędu (Fatal, Warning, Notice), miejsce (plik i linia) oraz treść komunikatu. Wiedząc, który moduł lub motyw odpowiada za dany plik, możesz szybko zawęzić obszar poszukiwań. Jeśli plik należy do rdzenia Drupala, problem często wynika z niekompatybilnego modułu lub błędnej aktualizacji. Jeśli plik pochodzi z katalogu sites/all/modules lub modules/custom, prawdopodobnie błąd leży w kodzie dodatku.

Błędy serwera: 500, 502, 503 i inne

Nie wszystkie problemy z Drupala mają swoje źródło w PHP. Kody HTTP 500, 502, 503 czy 504 to błędy po stronie serwera, które mogą wynikać z przeciążenia, błędnej konfiguracji PHP-FPM, problemów z reverse proxy lub przekroczonych limitów zasobów. Logi serwera często zawierają dodatkowe informacje, np. o przekroczeniu maksymalnego czasu wykonania skryptu czy limitu pamięci.

W przypadku błędów 500 warto zawsze zajrzeć do error.log serwera i logów PHP w tym samym przedziale czasowym. Błąd 502 Bad Gateway lub 504 Gateway Timeout często wskazuje na problem z komunikacją między Nginx a PHP-FPM, a nie bezpośrednio z samym Drupala. Mimo to skutkiem dla użytkownika jest niedostępność strony, dlatego analiza logów obu warstw staje się obowiązkowa.

Zaawansowane narzędzia logowania w Drupal

Monolog i integracja z syslog

W nowszych wersjach Drupala (8, 9, 10) popularnym rozwiązaniem jest użycie Monolog. To rozbudowana biblioteka logowania w PHP, pozwalająca wysyłać logi do wielu kanałów: plików, syslog, zewnętrznych usług, a nawet komunikatorów. Dzięki modułowi integrującemu Drupala z Monologiem możesz skonfigurować osobne pliki logów dla różnych poziomów błędów lub typów wiadomości, co ułatwia analizę problemów na dużych instalacjach.

Alternatywą lub uzupełnieniem jest syslog – systemowy demon logujący w systemach Unix. Przekierowanie logów Drupala do syslog pozwala na łatwą integrację z zewnętrznymi narzędziami do analizy, takimi jak ELK Stack, Graylog czy Splunk. Rozwiązanie to jest szczególnie przydatne w środowiskach z wieloma serwerami aplikacyjnymi, gdzie lokalne przechowywanie logów w bazie danych byłoby mało wydajne i trudne do utrzymania.

Dblog a wydajność i dobre praktyki

Standardowy moduł dblog jest wygodny, ale na intensywnie używanych serwisach może stać się wąskim gardłem. Każdy zapis do tabeli watchdog to dodatkowa operacja na bazie danych, która przy tysiącach żądań na minutę zaczyna mieć zauważalny wpływ na wydajność. Z tego powodu na dużych produkcjach często ogranicza się poziom logowania lub wyłącza dblog na rzecz syslog czy Monologa.

Dobrą praktyką jest regularne czyszczenie starych wpisów logów z bazy danych, czy to ręcznie, czy przy pomocy cron. Wiele konfiguracji Drupala pozwala ustawić maksymalną liczbę dni przechowywania wpisów. Zbyt duża tabela watchdog nie tylko zajmuje miejsce, ale również spowalnia zapytania, co może wpływać na ogólną szybkość działania panelu administracyjnego.

Tworzenie własnych wpisów logów w kodzie

Programując własne moduły lub motywy, warto świadomie korzystać z API logowania. W Drupal 7 użyjesz funkcji watchdog(), natomiast w Drupal 8+ korzystasz z kontenera usług i interfejsu loggera. Dzięki temu możesz dodawać do logów własne komunikaty, np. o nieudanym połączeniu z zewnętrznym API, nietypowym zachowaniu użytkownika czy błędach importu danych.

Własne wpisy logów powinny zawierać jasny komunikat, poziom istotności oraz ewentualne dane kontekstowe, takie jak identyfikator użytkownika, ID węzła czy adres zewnętrznego serwisu. Dzięki temu w momencie awarii nie musisz zgadywać, w którym fragmencie procesu coś poszło nie tak – wystarczy filtr w raportach zdarzeń po typie zdarzenia czy module. Świadome logowanie to jeden z najskuteczniejszych sposobów na ułatwienie sobie życia przy późniejszym debugowaniu.

Integracja z zewnętrznymi systemami monitoringu

Coraz częściej logi z Drupala trafiają nie tylko do lokalnej bazy danych czy systemowych plików, ale też do wyspecjalizowanych narzędzi monitorujących. Usługi takie jak Sentry, Datadog, New Relic czy Elastic umożliwiają agregację logów z wielu serwerów, wyszukiwanie pełnotekstowe, tworzenie wykresów, a nawet automatyczne powiadomienia przy przekroczeniu określonych progów błędów.

Integrując Drupala z takim systemem, zyskujesz możliwość szybkiego wykrywania regresji po wdrożeniu nowej wersji kodu, obserwowania trendów (np. rosnącej liczby warning dotyczących pamięci) oraz reagowania, zanim użytkownicy zgłoszą problem. Dla większych projektów jest to często jedyny praktyczny sposób, by zachować kontrolę nad chaosem, jaki potrafi generować rozproszony system logów na wielu maszynach.