Monolog porządkuje logi w aplikacjach PHP, zapisując zdarzenia do plików, sysloga, baz danych albo zewnętrznych usług. W backendzie i API daje przewagę wtedy, gdy trzeba szybko odróżnić zwykły ruch od realnego problemu, znaleźć źródło błędu i zachować kontekst żądania. W praktyce monolog php działa najlepiej wtedy, gdy jest ustawiony świadomie: z właściwymi handlerami, poziomami logowania i formatem danych.
Najważniejsze rzeczy, które warto wiedzieć o Monologu od razu
- To biblioteka do logowania zdarzeń w PHP, a nie ciężki framework.
- W nowych projektach najlepiej zakładać Monolog 3 i PHP 8.1 lub nowsze.
- Największą wartość daje w backendzie, API, integracjach i systemach e-commerce.
- Logi są przetwarzane przez łańcuch handlerów, formatterów i processorów.
- W aplikacjach produkcyjnych warto łączyć rotację plików z filtrowaniem szumu i kontekstem żądania.
Czym jest Monolog i kiedy naprawdę się przydaje
Monolog to elastyczna biblioteka logowania dla PHP, która pozwala kierować wpisy do różnych miejsc bez przepisywania logiki w całej aplikacji. Możesz wysyłać logi do plików, socketów, baz danych, systemów kolejkowych albo zewnętrznych usług monitoringu, a wszystko spinać jednym loggerem i zestawem handlerów.
Ja sięgam po Monolog wtedy, gdy projekt przestaje być prostym skryptem i zaczyna mieć prawdziwy cykl życia: osobne endpointy API, integracje z płatnościami, zadania w tle, webhooki, kolejki lub rozbudowane panele administracyjne. W takim środowisku zwykłe `error_log()` szybko staje się zbyt ubogie, bo nie daje wygodnego filtrowania, poziomów zdarzeń ani sensownego formatu danych.
Warto też rozróżnić dwa scenariusze. Dla małej aplikacji wystarczy prosty zapis do pliku. Dla systemu backendowego, który obsługuje wiele usług i wiele typów błędów, lepiej od razu myśleć o kanałach logów, strukturze wpisu i sposobie przeszukiwania historii. To właśnie w takich projektach Monolog pokazuje pełnię możliwości, a nie tylko podstawowe logowanie komunikatów.
Żeby dobrze dobrać konfigurację, trzeba najpierw zobaczyć, jak biblioteka przetwarza pojedynczy rekord i gdzie po drodze można go wzbogacić lub odfiltrować.
Jak działa przepływ logów w praktyce
W Monologu najważniejsze są cztery elementy: logger, handler, formatter i processor. Logger zbiera wpis, handler decyduje, dokąd go wysłać, formatter zamienia go na czytelny lub strukturalny zapis, a processor dorzuca dodatkowy kontekst, na przykład identyfikator żądania, klasę wyjątku albo nazwę użytkownika.
Logger
To punkt wejścia. W kodzie aplikacji wywołujesz metodę typu `info()`, `warning()` albo `error()`, a logger tworzy rekord z wiadomością, poziomem i kontekstem. W Monologu 3 rekordy są reprezentowane przez obiekt `Monolog\LogRecord`, więc całość jest bardziej uporządkowana niż w starszych podejściach opartych na luźnych tablicach.
Handler
Handler odpowiada za wysyłkę danych. Jeden logger może mieć kilka handlerów naraz, więc ten sam wpis może trafić do pliku, do sysloga i do kanału alertowego. To ważne w backendzie, bo nie każdy wpis powinien być traktowany tak samo. Informacja diagnostyczna może iść do logu aplikacyjnego, a błąd krytyczny równolegle do miejsca, które uruchomi alert.
Formatter
Formatter decyduje o tym, jak rekord zostanie zapisany. Dla prostych plików wystarczy format liniowy, ale dla API i środowisk z centralnym zbieraniem logów dużo lepiej sprawdza się JSON. Taki zapis łatwiej analizować automatycznie, filtrować po polach i łączyć z metrykami.
Processor
Processor wzbogaca rekord o dane, których nie chcesz dopisywać ręcznie w każdym miejscu kodu. To dobry moment na `request_id`, `user_id`, ścieżkę endpointu, nazwę mikroserwisu czy skrócony kontekst wyjątku. W praktyce właśnie ten element robi największą różnicę, gdy po kilku godzinach trzeba ustalić, co dokładnie zaszło w jednym żądaniu.
Jeśli chcesz widzieć całość jako prosty łańcuch, myśl o tym tak: aplikacja tworzy zdarzenie, Monolog je normalizuje, handler podejmuje decyzję, a formatter i processor dopracowują szczegóły. Dopiero po takim rozbiciu łatwo przejść do wdrożenia.
Jak wdrożyć Monolog w projekcie PHP
W nowym projekcie zwykle instaluję bibliotekę przez Composer i od razu ustawiam ją pod aktualną wersję PHP. W 2026 roku rozsądny punkt wyjścia to Monolog 3, ale pamiętaj o wymaganiu PHP 8.1 lub nowszego. Jeśli pracujesz na starszym środowisku, trzeba zostać przy odpowiedniej gałęzi 2.x.
composer require monolog/monolog:^3.0Minimalna konfiguracja nie musi być rozbudowana, ale powinna już pokazywać kierunek, w którym chcesz iść. Dla API najczęściej wybieram zapis do pliku w formacie JSON, bo taki log łatwiej potem przeszukać lub przekazać do narzędzia obserwowalności.
setFormatter(new JsonFormatter());
$logger->pushHandler($handler);
$logger->info('Request completed', [
'request_id' => $requestId,
'method' => 'GET',
'path' => '/orders/123',
'duration_ms' => 184,
]);To jest dobry punkt startowy, bo od razu pokazuje dwie praktyczne zasady: log ma mieć sensowny kanał oraz czytelny format. W Symfony ten sam model da się spiąć przez MonologBundle, co upraszcza konfigurację kanałów i handlerów. W innych projektach warto trzymać podobny podział ręcznie, zamiast upychać wszystko w jednym loggerze.
Sam bootstrap to jednak dopiero połowa roboty. O jakości logowania dużo bardziej decyduje wybór handlera i sposób użycia poziomów zdarzeń.
Które handlery wybrać do backendu i API
Największy błąd, jaki widzę w projektach, to traktowanie wszystkich logów jednakowo. Tymczasem inny handler sprawdzi się przy debugowaniu lokalnym, inny na produkcji, a jeszcze inny przy alertach, które mają obudzić zespół tylko wtedy, gdy naprawdę dzieje się coś złego.
| Handler | Kiedy go użyć | Na co uważać |
|---|---|---|
| StreamHandler | Prosty zapis do pliku lub strumienia w środowisku dev, staging albo w mniejszych usługach | Bez rotacji plik szybko urośnie i zacznie przeszkadzać w utrzymaniu |
| RotatingFileHandler | Gdy chcesz automatycznie dzielić logi na pliki dzienne lub okresowe | To nadal lokalny zapis, więc trzeba zadbać o retencję i backup |
| FingersCrossedHandler | W produkcji, gdy chcesz ograniczyć szum i zapisywać pełny kontekst dopiero po błędzie | Buforuje wpisy, więc opóźnia ich zapis do momentu przekroczenia progu |
| SyslogUdpHandler | Gdy logi mają trafiać do centralnego sysloga lub infrastruktury ops | Wymaga dopasowania sieci i konfiguracji po stronie odbiorcy |
| SlackWebhookHandler | Do krótkich alertów o awariach, które powinny trafić do zespołu od razu | Nie używaj go do masowego logowania, bo skończysz z chaosem w komunikatorze |
W backendzie API najczęściej wybieram zestaw: zapis do pliku albo sysloga, do tego filtr szumu i osobny kanał na zdarzenia krytyczne. To daje dobrą równowagę między ilością informacji a kosztem utrzymania. Jeśli logi są zbyt głośne, zespół przestaje je czytać. Jeśli są zbyt skąpe, tracą wartość diagnostyczną.
Dobór handlera ma jednak sens tylko wtedy, gdy równie dobrze ustawisz poziomy logowania i kontekst, bo bez tego nawet najlepszy zapis będzie mało użyteczny.
Jak logować sensownie w backendzie i API
W praktyce logowanie działa dobrze wtedy, gdy jest spójne. Nie chodzi o to, żeby zapisać wszystko, tylko o to, żeby zapisać to, co pozwala odtworzyć przebieg zdarzenia. W API oznacza to zwykle identyfikator żądania, endpoint, metodę HTTP, czas trwania, status odpowiedzi i szczegóły wyjątku, jeśli coś się wysypało.
Poziomy logów, które mają sens
Monolog wspiera standardowe poziomy znane z ekosystemu PHP i logowania zgodnego z RFC 5424. W większości projektów backendowych nie potrzebujesz wszystkich naraz w codziennej pracy, ale warto wiedzieć, po co każdy z nich istnieje.
| Poziom | Kiedy go używać |
|---|---|
| Debug | Do szczegółowej diagnostyki w czasie pracy deweloperskiej lub podczas trudnego śledzenia błędu |
| Info | Do ważnych, prawidłowych zdarzeń, na przykład zakończenia procesu lub przyjęcia żądania |
| Notice | Do sytuacji nietypowych, ale jeszcze poprawnych z punktu widzenia działania systemu |
| Warning | Do zdarzeń ryzykownych, które zostały obsłużone, ale mogą wymagać uwagi |
| Error | Do błędów, które przerwały operację albo zwróciły niepoprawny wynik |
| Critical, Alert, Emergency | Do awarii, które wpływają na dostępność usługi albo wymagają natychmiastowej reakcji |
W większości API nie ma sensu zalewać produkcji `debugiem`. Ja zazwyczaj zostawiam go lokalnie, a na produkcji ograniczam się do `info`, `warning`, `error` i wyżej. To zmniejsza szum i ułatwia analizę realnych incydentów.
Przeczytaj również: Backend i API - Jak wybrać stos technologiczny?
Co warto dopisywać do contextu
Dobry log bez kontekstu bywa tylko ładnie nazwanym napisem. W aplikacjach backendowych najczęściej dopisuję te pola: `request_id`, `user_id` lub `account_id`, metodę HTTP, ścieżkę endpointu, kod odpowiedzi, czas wykonania, nazwę integracji zewnętrznej i skróconą informację o wyjątku.
Jednocześnie trzeba uważać na dane wrażliwe. Nie loguję haseł, tokenów, pełnych numerów kart, tajnych nagłówków ani całych payloadów z danymi osobowymi, jeśli nie ma do tego twardej potrzeby i odpowiednich zabezpieczeń. W praktyce lepszy jest krótki, precyzyjny log niż „bogaty” wpis, który później staje się ryzykiem bezpieczeństwa.
Jeśli aplikacja ma kilka usług, bardzo pomaga też spójny format logów i wspólny identyfikator korelacji. Dzięki temu jeden problem można prześledzić przez kilka komponentów bez ręcznego składania historii z fragmentów. Gdy to wszystko działa razem, Monolog przestaje być tylko biblioteką, a staje się realnym narzędziem diagnostycznym.
Co wdrożyć od razu, żeby logi pomagały, a nie przeszkadzały
Gdybym miał wskazać kilka decyzji, które naprawdę robią różnicę, postawiłbym na trzy rzeczy: użycie Monolog 3 w nowych projektach, rozdzielenie kanałów logów według obszarów systemu i zapis strukturalny tam, gdzie liczy się analiza automatyczna. To daje lepszy efekt niż dokładanie kolejnych komunikatów bez ładu.
- Traktuj logger jak część architektury, a nie jako miejsce na przypadkowe komunikaty.
- Rozdziel logi aplikacyjne, integracyjne i krytyczne alerty.
- Stosuj `Monolog\Level` zamiast starego stylu stałych `Logger::DEBUG`, jeśli budujesz nowy kod.
- Dbaj o rotację, retencję i czytelny format, szczególnie przy logach produkcyjnych.
- Loguj wyjątki razem z kontekstem żądania, bo dopiero wtedy diagnostyka ma sens.
Jeśli chcesz zacząć od jednej decyzji, wybierz najpierw poprawny format i jeden spójny kanał dla błędów API. Resztę da się rozbudować później, ale bez tego fundamentu logi szybko zamieniają się w hałas, a nie w narzędzie pracy.
