Jak czytać logi błędów PrestaShop jak programista

Dlaczego logi błędów PrestaShop mają znaczenie

Każdy sklep PrestaShop generuje błędy. Niektóre to nieszkodliwe powiadomienia, które nigdy nie wpływają na klientów. Inne to krytyczne awarie, które zatrzymują cały proces zakupowy. Różnica między właścicielem sklepu, który czeka dniami na wsparcie techniczne, a takim, który naprawia problemy w kilka minut, często sprowadza się do jednej umiejętności: czytania logów błędów.

Logi błędów to diagnostyczny output Twojego serwera i aplikacji PrestaShop. Rejestrują każdy błąd PHP, każde nieudane zapytanie do bazy danych, każdy problem z uprawnieniami i każdy nieprzechwycony wyjątek. Gdy coś idzie nie tak, odpowiedź prawie zawsze znajduje się w pliku logów. Wyzwaniem jest wiedzieć, gdzie szukać, czego szukać i jak interpretować to, co znajdziesz.

Ten przewodnik obejmuje pełen krajobraz logowania błędów w PrestaShop. Dowiesz się, gdzie żyje każdy typ logów, jak włączyć szczegółowe raportowanie błędów, jak czytać stack trace'y i jak używać narzędzi linii poleceń do znalezienia igły w stogu siana. Niezależnie od tego, czy debugujesz biały ekran śmierci, czy tropiesz sporadyczną awarię procesu zakupowego — to jest wiedza, której potrzebujesz.

Gdzie znajdują się logi PrestaShop

PrestaShop generuje logi na wielu poziomach i każdy poziom ma własne pliki logów. Zrozumienie, który log sprawdzić w pierwszej kolejności, oszczędza ogromne ilości czasu.

Logi aplikacji PrestaShop (var/logs)

Począwszy od PrestaShop 1.7, aplikacja wykorzystuje framework Symfony do panelu administracyjnego i głównego routingu. Symfony zapisuje własne logi do katalogu var/logs/ w głównym katalogu PrestaShop. Znajdziesz tam pliki nazwane według bieżącego środowiska:

var/logs/dev.log zawiera logi, gdy PrestaShop działa w trybie deweloperskim. Ten plik jest niezwykle szczegółowy i rejestruje wszystko — od decyzji routingowych po zapytania do bazy danych. Może szybko urosnąć do setek megabajtów.

var/logs/prod.log zawiera logi z trybu produkcyjnego. Ten plik jest domyślnie znacznie mniej szczegółowy, rejestrując tylko ostrzeżenia i błędy. To jest plik, który powinieneś sprawdzić w pierwszej kolejności, gdy coś przestaje działać na działającym sklepie.

Te pliki logów mają format Monolog, który jest standardową biblioteką logowania w Symfony. Każda linia zawiera znacznik czasu, kanał logowania (np. request, security lub doctrine), poziom ważności i wiadomość. Typowy wpis wygląda tak:

[2024-03-15 14:22:33] request.CRITICAL: Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\NotFoundHttpException: "No route found for GET /admin/nonexistent" at /var/www/html/vendor/symfony/http-kernel/EventListener/RouterListener.php line 136

Poziomy ważności, od najmniej do najbardziej poważnego, to: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT i EMERGENCY. Podczas rozwiązywania problemów filtruj najpierw po ERROR i CRITICAL.

Log błędów PHP

Sam PHP prowadzi log błędów odrębny od logów aplikacji PrestaShop. Ten log przechwytuje błędy, które pojawiają się zanim framework logowania PrestaShop zostanie zainicjalizowany, lub błędy w kodzie, który nie korzysta z loggera Symfony. Lokalizacja tego pliku zależy od konfiguracji serwera.

Na większości serwerów Linux z Apache log błędów PHP znajduje się w /var/log/php_errors.log lub /var/log/php/error.log. Na współdzielonym hostingu z cPanel znajduje się często w /home/username/logs/error.log lub w katalogu public_html jako error_log.

Możesz znaleźć dokładną lokalizację, sprawdzając konfigurację PHP. Utwórz tymczasowy plik PHP z phpinfo(); i poszukaj dyrektywy error_log. Alternatywnie uruchom php -i | grep error_log z linii poleceń.

Logi błędów PHP przechwytują błędy fatalne, błędy parsowania, ostrzeżenia i powiadomienia. Typowy wpis błędu fatalnego wygląda tak:

[15-Mar-2024 14:22:33 UTC] PHP Fatal error: Uncaught Error: Class 'SomeModule\SomeClass' not found in /var/www/html/modules/somemodule/somemodule.php:45

Logi serwera webowego (Apache i Nginx)

Twój serwer webowy prowadzi własny zestaw logów niezależny od PHP i PrestaShop. Te logi są niezbędne do diagnozowania błędów 500, 404 i problemów z wydajnością.

Logi Apache zazwyczaj znajdują się w:

/var/log/apache2/error.log — log błędów na systemach Debian i Ubuntu.
/var/log/httpd/error_log — log błędów na systemach CentOS i RHEL.
/var/log/apache2/access.log — log dostępu, rejestrujący każde żądanie HTTP.

Logi Nginx zazwyczaj znajdują się w:

/var/log/nginx/error.log — log błędów.
/var/log/nginx/access.log — log dostępu.

Jeśli Twoja strona używa konfiguracji wirtualnych hostów, logi mogą być w lokalizacji specyficznej dla strony, zdefiniowanej przez dyrektywę ErrorLog (Apache) lub error_log (Nginx) w pliku wirtualnego hosta.

Logi błędów serwera webowego przechwytują takie problemy jak błędy braku uprawnień, gdy PHP próbuje pisać do katalogu, błędy składni konfiguracji po zmianie .htaccess oraz błędy timeout proxy, jeśli używasz PHP-FPM za Nginx. To są logi do sprawdzenia, gdy widzisz ogólny błąd 500 Internal Server Error bez szczegółów w logach PHP lub PrestaShop.

Starsze logi PrestaShop (panel administracyjny)

PrestaShop prowadzi również przeglądarkę logów w panelu administracyjnym w Zaawansowane > Logi. Ten interfejs pokazuje wpisy logów przechowywane w tabeli ps_log bazy danych. Te logi przechwytują zdarzenia, które PrestaShop jawnie rejestruje, takie jak nieudane próby logowania, błędy instalacji modułów i niepowodzenia wysyłki e-maili.

Choć przeglądarka logów w panelu administracyjnym jest wygodna, ma istotne ograniczenia. Nie przechwytuje błędów PHP, błędów serwera webowego ani większości błędów fatalnych, które uniemożliwiają załadowanie strony. Traktuj ją jako uzupełnienie logów plikowych, nie ich zamiennik.

Włączanie trybu debugowania w PrestaShop

Domyślnie PrestaShop działa w trybie produkcyjnym i ukrywa szczegółowe komunikaty o błędach przed odwiedzającymi. Jest to poprawne dla działającego sklepu, ale sprawia, że debugowanie jest prawie niemożliwe. Gdy coś się zepsuje, Twoim pierwszym krokiem powinno być włączenie trybu debugowania.

Metoda 1: Plik defines.inc.php

Otwórz plik config/defines.inc.php i znajdź linię ustawiającą _PS_MODE_DEV_. Zmień wartość z false na true:

define('_PS_MODE_DEV_', true);

Ta pojedyncza zmiana ma kilka efektów. Raportowanie błędów PHP jest ustawione na maksymalny poziom, pokazując wszystkie błędy, ostrzeżenia i powiadomienia. Buforowanie szablonów Smarty jest wyłączone, więc zmiany w szablonach pojawiają się natychmiast. Pasek profilowania Symfony pojawia się na dole stron panelu administracyjnego. I co najważniejsze, szczegóły błędów są wyświetlane na ekranie zamiast generycznej strony błędu.

Metoda 2: Tryb profilowania

Dla głębszej analizy możesz również włączyć profilowanie. W tym samym pliku ustaw:

define('_PS_DEBUG_PROFILING_', true);

To dodaje szczegółowe informacje o czasach wykonania i użyciu pamięci na dole każdej strony, pokazując, które hooki trwają najdłużej, które moduły zużywają najwięcej pamięci i ile zapytań do bazy danych generuje każda strona. Jest to nieocenione przy debugowaniu wydajności, ale nigdy nie powinno być włączone na produkcji.

Ostrzeżenie bezpieczeństwa

Tryb debugowania ujawnia wrażliwe informacje, w tym ścieżki plików, dane logowania do bazy danych w stack trace'ach i wewnętrzną strukturę aplikacji. Nigdy nie zostawiaj trybu debugowania włączonego na sklepie produkcyjnym dostępnym publicznie. Jeśli musisz debugować działający sklep, rozważ ograniczenie trybu debugowania do Twojego adresu IP, opakowując define w sprawdzenie IP, lub użyj środowiska stagingowego.

Czytanie stack trace'ów

Gdy PrestaShop napotyka błąd fatalny lub nieprzechwycony wyjątek w trybie debugowania, wyświetla stack trace. Stack trace to migawka łańcucha wywołań, który doprowadził do błędu, czytana od punktu awarii wstecz do oryginalnego punktu wejścia. Nauka czytania stack trace'ów to najcenniejsza umiejętność debugowania, jaką możesz rozwinąć.

Anatomia stack trace'a

Typowy stack trace PrestaShop wygląda tak:

PHP Fatal error: Uncaught TypeError: Argument 1 passed to Product::getProductProperties() must be of the type int, null given, called in /var/www/html/classes/Product.php on line 4523

Stack trace:
#0 /var/www/html/classes/Product.php(4523): Product::getProductProperties(NULL, Array)
#1 /var/www/html/modules/somemodule/somemodule.php(127): Product::getProductProperties(1, Array)
#2 /var/www/html/classes/Hook.php(523): SomeModule->hookDisplayHome(Array)
#3 /var/www/html/classes/Hook.php(460): Hook::coreCallHook(Object(SomeModule), 'hookDisplayHome', Array)
#4 /var/www/html/classes/Hook.php(408): Hook::exec('displayHome', Array)

Czytaj stack trace od góry do dołu. Pierwsza linia mówi Ci, co poszło nie tak: funkcja oczekiwała liczby całkowitej, ale otrzymała null. Linia #0 mówi Ci, gdzie wystąpił błąd. Linia #1 mówi Ci, co wywołało kod w #0. Linia #2 mówi Ci, co wywołało #1 i tak dalej.

W tym przykładzie łańcuch jest jasny: PrestaShop wykonał hook displayHome, który wywołał metodę hookDisplayHome w SomeModule, która wywołała Product::getProductProperties() z wartością null zamiast oczekiwanej liczby całkowitej. Błąd jest w module w linii 127, gdzie przekazuje nieprawidłową wartość.

Znajdowanie odpowiedniej ramki

Stack trace'y w PrestaShop mogą być długie, czasem 20 lub 30 ramek głębokie. Kluczem jest znalezienie ramki zawierającej Twój kod lub moduł powodujący problem. Szukaj ścieżek zawierających /modules/ lub /themes/, ponieważ to najbardziej prawdopodobne źródła błędów. Ramki odwołujące się do /classes/, /src/ lub /vendor/ to rdzeń PrestaShop lub biblioteki firm trzecich, które rzadziej są źródłem problemu, chyba że modyfikowałeś pliki rdzenia.

Typowe wzorce błędów PrestaShop

Po przeczytaniu tysięcy logów błędów PrestaShop pewne wzorce powtarzają się regularnie. Rozpoznanie tych wzorców pozwala diagnozować problemy w sekundach zamiast godzin.

Błędy "Class Not Found"

PHP Fatal error: Uncaught Error: Class 'ModuleName\ClassName' not found

Oznacza to, że autoloader nie może znaleźć określonej klasy. Typowe przyczyny to: brak pliku vendor/autoload.php (moduł wymaga uruchomienia composer install), niedopasowana deklaracja namespace, plik który nie został dołączony do archiwum ZIP modułu podczas instalacji, lub problem z wielkością liter na serwerach Linux, gdzie ClassName.php i classname.php to różne pliki.

Błędy braku uprawnień

Warning: file_put_contents(/var/www/html/var/cache/prod/some_file): failed to open stream: Permission denied

Występują, gdy użytkownik serwera webowego (zazwyczaj www-data na Debian/Ubuntu lub apache na CentOS) nie ma uprawnień do zapisu pliku lub katalogu. Napraw to, poprawiając właściciela: chown -R www-data:www-data var/cache/ i uprawnienia: chmod -R 775 var/cache/.

Błędy limitu pamięci

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 65536 bytes)

Liczba 134217728 bajtów to 128MB — domyślny limit pamięci PHP. PrestaShop zaleca minimum 256MB. Zwiększ go w pliku php.ini: memory_limit = 512M. Jeśli błąd utrzymuje się nawet przy wysokich limitach pamięci, kod prawdopodobnie ma wyciek pamięci, często spowodowany ładowaniem zbyt wielu produktów lub kategorii w jednym zapytaniu bez paginacji.

Błędy połączenia z bazą danych

Link to database cannot be established: SQLSTATE[HY000] [2002] Connection refused

Oznacza to, że PrestaShop nie może połączyć się z serwerem MySQL. Sprawdź, czy serwer bazy danych działa, czy dane logowania w app/config/parameters.php są poprawne i czy host bazy danych jest dostępny z serwera webowego.

Błędy szablonów Smarty

SmartyException: Unable to load template file 'module:somemodule/views/templates/hook/display.tpl'

Plik szablonu jest brakujący, błędnie nazwany lub w złym katalogu. Zweryfikuj, czy plik istnieje w oczekiwanej ścieżce i czy nazwa pliku dokładnie się zgadza, włącznie z wielkością liter.

Błędy tokena CSRF

Invalid token. Please try to log in again.

Pojawia się w panelu administracyjnym, gdy przesłanie formularza zawiera wygasły lub brakujący token bezpieczeństwa. Zwykle dzieje się tak, gdy sesja wygasa podczas długiej sesji edycji, gdy wiele zakładek jest otwartych na tej samej stronie admina lub gdy moduł nieprawidłowo generuje URL-e formularzy.

Używanie grep do wyszukiwania błędów

Gdy pliki logów są duże, ręczne ich przeglądanie jest niepraktyczne. Polecenie grep to Twój najlepszy przyjaciel do szybkiego znajdowania istotnych wpisów.

Podstawowe wyszukiwanie błędów

Aby znaleźć wszystkie błędy fatalne w logu PHP:

grep 'Fatal error' /var/log/php_errors.log

Aby znaleźć błędy z konkretnego modułu:

grep 'somemodule' /var/www/html/var/logs/prod.log

Aby znaleźć błędy tylko z dzisiaj (zakładając format daty w logu):

grep '2024-03-15' /var/www/html/var/logs/prod.log | grep 'ERROR\|CRITICAL'

Zaawansowane filtrowanie

Aby zobaczyć błędy z otaczającym kontekstem (3 linie przed i po każdym dopasowaniu):

grep -C 3 'Fatal error' /var/log/php_errors.log

Aby policzyć, ile razy pojawia się każdy unikalny błąd:

grep 'Fatal error' /var/log/php_errors.log | sort | uniq -c | sort -rn | head -20

Ten pipeline sortuje błędy, liczy duplikaty, sortuje malejąco po liczbie i pokazuje top 20. Jest to niezwykle przydatne do identyfikacji najczęściej występujących błędów wymagających uwagi w pierwszej kolejności.

Aby przeszukiwać jednocześnie wiele plików logów:

grep -r 'Fatal error' /var/log/ --include='*.log'

Flaga -r przeszukuje rekurencyjnie, a --include ogranicza wyszukiwanie do plików z rozszerzeniem .log.

Monitorowanie logów w czasie rzeczywistym za pomocą tail -f

Gdy aktywnie debugujesz problem, musisz widzieć błędy w momencie ich wystąpienia. Polecenie tail -f śledzi plik logów w czasie rzeczywistym, wyświetlając nowe wpisy w momencie ich zapisu.

Podstawowe monitorowanie w czasie rzeczywistym

Aby obserwować log produkcyjny PrestaShop w czasie rzeczywistym:

tail -f /var/www/html/var/logs/prod.log

Aby obserwować log błędów PHP:

tail -f /var/log/php_errors.log

Aby obserwować wiele plików logów jednocześnie:

tail -f /var/www/html/var/logs/prod.log /var/log/php_errors.log /var/log/apache2/error.log

Filtrowane monitorowanie w czasie rzeczywistym

Aby obserwować tylko wpisy poziomu error w czasie rzeczywistym, połącz tail z grep:

tail -f /var/www/html/var/logs/prod.log | grep --line-buffered 'ERROR\|CRITICAL'

Flaga --line-buffered jest tu ważna. Bez niej grep buforuje output i możesz nie widzieć dopasowań od razu.

Aby podświetlić konkretne słowa kluczowe, pokazując jednocześnie cały output:

tail -f /var/www/html/var/logs/prod.log | grep --color=always -E 'ERROR|CRITICAL|$'

To podświetla ERROR i CRITICAL kolorem, jednocześnie wyświetlając wszystkie linie.

Workflow debugowania

Najskuteczniejszy workflow debugowania łączy monitorowanie w czasie rzeczywistym z aktywnym testowaniem. Otwórz jedno okno terminala z uruchomionym tail -f na odpowiednich plikach logów. W przeglądarce odtwórz akcję powodującą błąd. Obserwuj terminal w poszukiwaniu nowych wpisów logów, które pojawiają się dokładnie w momencie wywołania problemu. To podejście eliminuje zgadywanie i pokazuje precyzyjnie, co dzieje się w momencie wystąpienia błędu.

Rotacja i zarządzanie logami

Pliki logów rosną nieprzerwanie i mogą zużyć całą dostępną przestrzeń dyskową, jeśli nie są zarządzane. Większość serwerów Linux używa logrotate do automatycznego zarządzania tym, ale własne logi PrestaShop w var/logs/ mogą nie być uwzględnione w domyślnej konfiguracji logrotate.

Zrozumienie logrotate

Narzędzie logrotate uruchamia się codziennie (zazwyczaj przez cron) i obsługuje rotację, kompresję i usuwanie plików logów. Pliki konfiguracyjne znajdują się w /etc/logrotate.d/. Rotacja logów Apache i Nginx jest zazwyczaj skonfigurowana fabrycznie.

Dla katalogu var/logs PrestaShop może być konieczne utworzenie niestandardowej konfiguracji logrotate:

/var/www/html/var/logs/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  create 0640 www-data www-data
}

To rotuje logi codziennie, przechowuje 14 dni historii, kompresuje stare logi i tworzy nowe pliki logów z poprawnymi uprawnieniami.

Ręczne czyszczenie logów

Jeśli plik logów urósł do ogromnych rozmiarów i musisz go wyczyścić bez utraty uchwytu pliku (ważne, jeśli jakiś proces aktywnie do niego pisze):

truncate -s 0 /var/www/html/var/logs/prod.log

Nie usuwaj pliku i nie twórz go ponownie, ponieważ każdy proces, który ma otwarty plik, będzie nadal pisał do inode'a usuniętego pliku do momentu restartu. Podejście z truncate czyści zawartość, zachowując inode.

Zrozumienie kontekstów błędów specyficznych dla PrestaShop

Błędy PrestaShop często pojawiają się z kontekstem unikalnym dla tej platformy. Zrozumienie tego kontekstu pomaga szybciej lokalizować i naprawiać problemy.

Błędy związane z hookami

Gdy błąd występuje wewnątrz hooka, stack trace będzie zawierał odwołania do Hook::exec() i Hook::coreCallHook(). Nazwa hooka mówi Ci dokładnie, w którym momencie renderowania strony pojawia się błąd. Na przykład błędy displayHome pojawiają się na stronie głównej, błędy actionValidateOrder podczas składania zamówienia, a błędy displayBackOfficeHeader przy ładowaniu dowolnej strony panelu administracyjnego.

Jeśli błąd hooka powoduje crash strony, możesz tymczasowo wyłączyć problematyczny moduł z bazy danych:

UPDATE ps_module SET active = 0 WHERE name = 'somemodule';

To pozwoli Ci uzyskać dostęp do panelu administracyjnego w celu prawidłowej diagnozy i naprawy problemu.

Konflikty nadpisań (override)

System nadpisań PrestaShop pozwala modułom rozszerzać klasy rdzenia, ale konflikty powstają, gdy dwa moduły nadpisują tę samą klasę. Błąd zazwyczaj pojawia się jako konflikt sygnatury metody lub nieoczekiwana zmiana zachowania. Sprawdź katalog override/, aby zobaczyć, które nadpisania są aktywne, i sprawdź plik cache/class_index.php, który mapuje klasy na ich pliki nadpisań. Usunięcie tego pliku cache zmusza PrestaShop do ponownego wygenerowania mapy nadpisań.

Błędy związane z cache

Wiele błędów PrestaShop jest spowodowanych przestarzałymi plikami cache. Jeśli widzisz błędy, które nie odpowiadają aktualnemu kodowi (na przykład błąd odwołujący się do numeru linii, który nie istnieje w pliku), cache jest prawdopodobnie nieaktualny. Wyczyść go, usuwając zawartość var/cache/prod/ i var/cache/dev/. W PrestaShop 1.6 wyczyść zamiast tego cache/smarty/compile/ i cache/smarty/cache/.

Błędy instalacji i aktualizacji modułów

Instalacje modułów mogą cicho się nie powieść, pozostawiając moduł w stanie częściowej instalacji. Sprawdź var/logs/prod.log pod kątem wpisów z czasu instalacji. Typowe problemy to brakujące tabele bazy danych (SQL w metodzie install() modułu się nie powiodło), brakujące hooki (wywołanie registerHook() się nie powiodło) oraz błędy duplikatu wpisu w tabeli ps_authorization_role przy ponownej instalacji modułu, który nie został w pełni odinstalowany.

Budowanie listy kontrolnej debugowania

Gdy napotkasz błąd PrestaShop, postępuj według tej systematycznej listy kontrolnej, aby efektywnie znaleźć przyczynę:

Po pierwsze, zidentyfikuj typ błędu. Czy to biały ekran (błąd 500), konkretny komunikat o błędzie, zepsuty układ strony czy nieoczekiwane zachowanie? Każdy typ wskazuje na inne pliki logów.

Po drugie, sprawdź najpierw najbardziej specyficzny log. Dla błędów PHP sprawdź log błędów PHP. Dla błędów HTTP sprawdź log serwera webowego. Dla błędów aplikacji sprawdź var/logs/prod.log.

Po trzecie, włącz tryb debugowania, jeśli logi nie ujawniają wystarczającej ilości informacji. Zmień _PS_MODE_DEV_ na true i odtwórz błąd.

Po czwarte, użyj tail -f na odpowiednich logach i odtwórz błąd w przeglądarce. To daje Ci widok w czasie rzeczywistym na dokładnie to, co się dzieje.

Po piąte, przeczytaj stack trace od góry do dołu. Znajdź ramkę odwołującą się do kodu Twojego modułu lub motywu. To tam trzeba zastosować poprawkę.

Po szóste, wyszukaj komunikat o błędzie w GitHub issues i na forach PrestaShop. Istnieje duże prawdopodobieństwo, że ktoś już napotkał i rozwiązał ten sam problem.

Po siódme, po zastosowaniu poprawki wyczyść wszystkie cache i monitoruj logi, aby potwierdzić, że błąd zniknął. Poprawka, która nie daje czystego logu, nie jest kompletną poprawką.

Podsumowanie

Czytanie logów błędów PrestaShop nie jest tajemną sztuką zarezerwowaną dla seniorskich programistów. To praktyczna umiejętność oparta na wiedzy, gdzie logi się znajdują, jak je filtrować i jak interpretować ich zawartość. Logi w var/logs/, log błędów PHP i log serwera webowego — każdy służy innemu celowi, a razem dają pełny obraz każdego problemu. Włączenie trybu debugowania daje szczegółowe komunikaty o błędach. Stack trace'y pokazują dokładny łańcuch wywołań funkcji, który doprowadził do awarii. Narzędzia takie jak grep i tail -f umożliwiają efektywne wyszukiwanie i monitorowanie błędów nawet w dużych, obciążonych plikach logów. Opanuj te techniki, a będziesz rozwiązywać problemy szybciej, z mniejszą frustracją i ze znacznie mniejszą zależnością od zewnętrznego wsparcia.