1. Struktura komunikatu logu
Wyobraźmy sobie, że logi to nie tylko „strumień świadomości” twojego programu, ale cenny dziennik, w którym za miesiąc lub rok ty lub twój kolega znajdzie odpowiedź na pytanie: „Co tu się, do diabła, stało?”. Aby było to możliwe, każdy komunikat logu musi być ustrukturyzowany. Zazwyczaj (i to jest standard w większości bibliotek) każdy komunikat zawiera:
- Czas zdarzenia — kiedy to się wydarzyło.
- Poziom — jak ważne jest zdarzenie (INFO, ERROR itd.).
- Nazwa loggera — zazwyczaj to nazwa klasy lub komponentu.
- Treść komunikatu — co dokładnie się stało.
- Stack trace (jeśli jest błąd) — aby zrozumieć gdzie i dlaczego.
Oto przykład dobrze sformatowanej linii logu (na przykładzie Log4j/SLF4J):
2024-06-16 18:42:07,123 INFO com.example.MainApp - Użytkownik zalogował się do systemu: username=user
A jeśli wystąpił błąd:
2024-06-16 18:42:10,456 ERROR com.example.LoginService - Błąd autoryzacji użytkownika: user
java.lang.IllegalArgumentException: Nieprawidłowe hasło
at com.example.LoginService.checkPassword(LoginService.java:42)
...
Dlaczego to ważne?
Gdy aplikacja działa długo, logi mogą zajmować gigabajty. Jeśli komunikaty nie są ustrukturyzowane, znalezienie problemu staje się zadaniem w stylu „zgadnij melodię po szumie wentylatora”.
2. Formatowanie komunikatów
Dlaczego nie należy robić tak:
logger.info("Użytkownik " + username + " zalogował się do systemu");
Niby wszystko proste, ale jest haczyk: nawet jeśli poziom logowania jest ustawiony na ERROR, łańcuch w nawiasach i tak zostanie zbudowany (konkatenacja się wykona), a to oznacza zbędne zużycie zasobów. W dużych systemach, gdzie logów są tysiące linii na sekundę, może to powodować realne opóźnienia.
Jak poprawnie: wzorce i parametry
Współczesne biblioteki (np. SLF4J i Log4j 2) wspierają wzorce z parametrami:
logger.info("Użytkownik {} zalogował się do systemu", username);
Tutaj łańcuch zostanie zbudowany tylko wtedy, gdy poziom logowania pozwala na wypisanie tego komunikatu. Jeśli ustawiono np. WARN, to nawet nie dojdzie do obliczenia łańcucha — oszczędność zasobów i nerwów.
Bonus: jeśli przekażesz kilka parametrów, zostaną wstawione po kolei:
logger.info("Użytkownik {} wykonał akcję {} na obiekcie {}", username, action, objectId);
Logowanie wyjątków (stack trace)
Jeśli łapiesz wyjątek, nie dodawaj ręcznie stack trace do komunikatu:
// NIE NALEŻY:
logger.error("Błąd: " + ex.getMessage() + "\n" + Arrays.toString(ex.getStackTrace()));
Poprawnie:
logger.error("Błąd podczas przetwarzania żądania", ex);
SLF4J i Log4j same ładnie dodadzą stack trace do logu.
Przykład: porównanie podejść
// Źle (konkatenacja zawsze się wykonuje)
logger.debug("Obiekt: " + expensiveToString(obj));
// Dobrze (leniwe tworzenie)
logger.debug("Obiekt: {}", obj);
3. Wybór poziomów logowania
Jeśli masz w logach wszystko jak leci na poziomie ERROR, to to już nie logi, tylko „czerwona lampka”. Jeśli wszystko jest na DEBUG, utoniesz w szczegółach. Zobaczmy, kiedy używać którego poziomu.
| Poziom | Do czego służy | Przykład komunikatu |
|---|---|---|
|
Krytyczne awarie, przez które system działa nieprawidłowo lub w ogóle nie działa | „Błąd połączenia z bazą danych” |
|
Ważne ostrzeżenia, niekrytyczne, ale wymagające uwagi | „Nie udało się znaleźć użytkownika, używam guest” |
|
Zwykłe zdarzenia odzwierciedlające normalną pracę aplikacji | „Użytkownik zarejestrowany: user” |
|
Szczegółowe informacje do debugowania, niepotrzebne na produkcji | „Wywołano metodę checkPassword z parametrami ...” |
|
Najbardziej szczegółowe informacje, zwykle do głębokiej diagnostyki | „Początek pętli przetwarzania: i=0” |
Przykłady typowych komunikatów
- ERROR — nie udało się zapisać pliku, przechwycono nieobsługiwany wyjątek, usługa niedostępna.
- WARN — przestarzałe API, podejrzane zachowanie użytkownika, przekroczony limit prób.
- INFO — użytkownik zalogował się/wylogował, zakończono przetwarzanie zamówienia, start aplikacji.
- DEBUG — parametry żądania, wartości zmiennych, pośrednie wyniki obliczeń.
- TRACE — wejścia/wyjścia do metod, wewnętrzne pętle, szczegóły działania algorytmów.
Wskazówka:
Na produkcji zwykle włącza się tylko INFO i wyżej, czasem WARN i ERROR. DEBUG i TRACE — tylko podczas szukania trudnych błędów.
4. Best practices (najlepsze praktyki logowania)
Nie loguj danych wrażliwych
Hasła, tokeny, numery kart kredytowych — to nie należy do logów. Nawet jeśli wydaje się, że „plik logu jest tylko dla mnie”, pamiętaj o RODO i koledze, który przypadkowo wyśle log na wspólny czat.
// Źle:
logger.info("Użytkownik {} zalogował się z hasłem {}", username, password);
// Dobrze:
logger.info("Użytkownik {} zalogował się do systemu", username);
Nie nadużywaj poziomu ERROR
Jeśli wszystko zapisujesz przez logger.error, to gdy naprawdę wydarzy się katastrofa, nikt jej nie zauważy — wszyscy przywykli do „czerwonych lampek”. Używaj ERROR tylko w sytuacjach, kiedy aplikacja naprawdę nie może kontynuować pracy lub została naruszona logika biznesowa.
Loguj wyjątki z pełnym stack trace
Nie zapisuj tylko ex.getMessage(), inaczej nigdy nie dowiesz się, gdzie dokładnie wystąpił błąd. Przekazuj wyjątek jako drugi parametr do loggera.
logger.error("Błąd podczas przetwarzania żądania", ex);
Używaj unikalnych identyfikatorów (korelacja zdarzeń)
W dużych systemach warto przypisywać każdemu żądaniu, użytkownikowi lub operacji unikalny identyfikator. To pomaga „zszyć” zdarzenia z różnych części systemu.
logger.info("Rozpoczęto przetwarzanie zamówienia: orderId={}", orderId);
logger.info("Zamówienie przetworzono pomyślnie: orderId={}", orderId);
Nie zapisuj do logów wszystkiego jak leci
Jeśli logów jest za dużo — stają się bezużyteczne. Nie loguj każdej linijki kodu, bo znalezienie potrzebnej informacji stanie się niemożliwe.
Formatuj komunikaty w sposób zrozumiały
Pisz tak, aby komunikaty były zrozumiałe nie tylko dla autora kodu, ale i dla osoby, która będzie czytać logi za pół roku. Unikaj skrótów, nieoczywistych akronimów i „żartów dla swoich”.
5. Praktyka: konfiguracja formatu logu i poziomów
Przykład konfiguracji formatu w Log4j2 (log4j2.xml)
<Configuration>
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %logger{36} - %msg%n"/>
</Console>
</Appenders>
<Loggers>
<Root level="info">
<AppenderRef ref="Console"/>
</Root>
</Loggers>
</Configuration>
Co to oznacza?
- %d{...} — czas zdarzenia.
- %-5level — poziom (ERROR, INFO itd.).
- %logger{36} — nazwa loggera (zwykle klasa).
- %msg — sam komunikat.
Przykład kodu z różnymi poziomami logowania (SLF4J)
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class LogDemo {
private static final Logger logger = LoggerFactory.getLogger(LogDemo.class);
public static void main(String[] args) {
logger.info("Aplikacja uruchomiona");
logger.debug("Wartość zmiennej x: {}", 42);
try {
throw new IllegalArgumentException("Aj, aj, aj!");
// ...
} catch (Exception ex) {
logger.error("Wystąpił błąd podczas uruchamiania", ex);
}
}
}
Demonstracja różnicy między poziomami
Jeśli w ustawieniach loggera jest poziom INFO, komunikaty z poziomem DEBUG i niższym nie będą wypisywane. Spróbuj zmienić poziom na debug w konfiguracji — zobaczysz więcej szczegółów.
6. Typowe błędy
Błąd nr 1: Konkatenacja łańcuchów w logach. Bardzo często początkujący piszą tak:
logger.debug("Użytkownik: " + user.getName() + ", rola: " + user.getRole());
W rezultacie nawet przy wyłączonym poziomie DEBUG te łańcuchy będą budowane, co prowadzi do zbędnego obciążenia. Używaj parametrów!
Błąd nr 2: Logowanie bez stack trace wyjątku. Zapisują tylko komunikat:
logger.error("Błąd: " + ex.getMessage());
W efekcie w logach nie ma informacji, gdzie dokładnie wystąpił błąd. Przekazuj wyjątek jako drugi parametr!
Błąd nr 3: Logowanie wszystkiego na poziomie ERROR. Jeśli wszystko jest czerwone — nic nie jest czerwone. Używaj poziomów zgodnie z przeznaczeniem, inaczej ważne błędy zginą wśród „drobiazgów”.
Błąd nr 4: Logowanie danych wrażliwych. Nigdy nie zapisuj do logów haseł, tokenów, numerów kart. Nawet jeśli wydaje się, że nikt ich nie zobaczy, życie lubi niespodzianki.
Błąd nr 5: Niezrozumiałe komunikaty. Jeśli komunikat w logu wygląda jak „ERR42: fail”, to za miesiąc sam nie będziesz pamiętać, co to znaczy. Pisz jasno i szczegółowo.
Błąd nr 6: Brak unikalnych identyfikatorów. W złożonych systemach bez orderId, userId i innych identyfikatorów nie będziesz w stanie „zszyć” zdarzeń i zrozumieć, co działo się z konkretnym użytkownikiem lub zamówieniem.
GO TO FULL VERSION