CodeGym /Kursy /JAVA 25 SELF /Formatowanie i poziomy logów: najlepsze praktyki

Formatowanie i poziomy logów: najlepsze praktyki

JAVA 25 SELF
Poziom 63, Lekcja 1
Dostępny

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
ERROR
Krytyczne awarie, przez które system działa nieprawidłowo lub w ogóle nie działa „Błąd połączenia z bazą danych”
WARN
Ważne ostrzeżenia, niekrytyczne, ale wymagające uwagi „Nie udało się znaleźć użytkownika, używam guest”
INFO
Zwykłe zdarzenia odzwierciedlające normalną pracę aplikacji „Użytkownik zarejestrowany: user”
DEBUG
Szczegółowe informacje do debugowania, niepotrzebne na produkcji „Wywołano metodę checkPassword z parametrami ...”
TRACE
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.

1
Zadanie
JAVA 25 SELF, poziom 63, lekcja 1
Niedostępne
Architekt
Architekt
1
Zadanie
JAVA 25 SELF, poziom 63, lekcja 1
Niedostępne
Serwis społecznościowy
Serwis społecznościowy
Komentarze
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION