Strukturyzowane logi JSON: przewodnik dla deweloperów

Strukturalizowane logi w JSON: praktyczny przewodnik dla programistów

Logowanie to krytycznie ważny komponent obserwowalności w nowoczesnych systemach rozproszonych. W przeciwieństwie do metryk i śladów, logi zapewniają maksymalną elastyczność w analizie zdarzeń w aplikacji. Ten artykuł oferuje konkretne wzorce do wdrożenia efektywnego logowania z wykorzystaniem strukturalizowanego formatu JSON, kontekstu MDC oraz wyraźnego podziału poziomów błędów.

Dlaczego strukturalizowane logi są ważniejsze niż zwykły tekst

Tradycyjne zwykłe logi, wygodne do czytania z konsoli, stwarzają znaczne problemy przy automatycznym przetwarzaniu. Ich parsowanie wymaga skomplikowanych wyrażeń regularnych, wyodrębnianie konkretnych danych jest utrudnione, a modyfikacja formatu staje się bolesną procedurą. W systemach rozproszonych, gdzie incydenty wymagają szybkiej analizy danych z wielu źródeł, te wady stają się krytyczne.

Strukturalizowane logi w formacie JSON rozwiązują te problemy:

• Upraszczają wyszukiwanie i filtrowanie po konkretnych polach
• Umożliwiają częściowe indeksowanie w systemach wyszukiwania
• Ułatwiają automatyczne wyodrębnianie danych po incydentach
• Upraszczają filtrowanie danych osobowych i dodawanie metainformacji

Przykład nieefektywnego zwykłego loga:

2025-03-15 10:16:01.795 INFO 12345 --- [nio-8080-exec-1] c.e.UserController : Użytkownik zapisany w bazie danych: User{id=123, [email protected], role=USER}

Przykład strukturalizowanego loga w JSON:

{
  "timestamp": "2025-03-22T10:15:30.123Z",
  "level": "ERROR",
  "service": "auth-service",
  "traceId": "1fd7a997-6517-4b63-9baa-4238f8012734",
  "entrypoint": "HTTP request POST /api/user/auth",
  "message": "Nieudane uwierzytelnienie użytkownika",
  "user_id": "user-789",
  "error": {
    "type": "InvalidCredentials",
    "details": "Podane hasło nie pasuje"
  }
}

Mapped Diagnostic Context dla ciągłej identyfikacji

Mapped Diagnostic Context (MDC) w SLF4J rozwiązuje problem przekazywania informacji kontekstowych przez łańcuch wywołań. Zamiast jawnego przekazywania identyfikatorów przez wszystkie metody, MDC pozwala powiązać dane z bieżącym wątkiem wykonania.

Kluczowe aspekty użycia MDC:

• Identyfikatory biznesowe — user_id, order_id, transaction_id
• Kontekst techniczny — traceId, spanId dla śledzenia
• Metainformacja EP — typ punktu wejścia, numer próby wykonania
• Automatyczne czyszczenie — obowiązkowe wyczyszczenie kontekstu po zakończeniu przetwarzania

MDC jest szczególnie ważny dla punktów wejścia, gdzie identyfikatory biznesowe muszą być dostępne od początku przetwarzania żądania, często wyodrębniane z nagłówków przed odczytem ładunku.

Punkty wejścia (Entrypoints) i ich logowanie

Punkt wejścia (EP) to abstrakcja oznaczająca początek wykonywania logiki biznesowej. W nowoczesnych aplikacjach powszechne są:

• Serwery HTTP/REST
• Serwery gRPC
• Konsumenci Kafka
• Zadania cron i zaplanowane zadania
• Odbiorcy kolejek wiadomości

Każdy EP powinien być logowany według jednolitego schematu:

• Parametry wejściowe — metadane i ładunek żądania
• Kontekst wykonania — identyfikatory biznesowe, parametry techniczne
• Dane wyjściowe — wynik przetwarzania lub błąd
• Status wykonania — sukces/porażka z uwzględnieniem polityki ponawiania

Rozdzielenie error i warning w systemach rozproszonych

W systemach rozproszonych mechanizmy ponawiania to standardowe podejście do zapewnienia niezawodności. To bezpośrednio wpływa na strategię logowania:

Poziom warning jest używany dla:

• Błędów podczas pośrednich prób wykonania
• Tymczasowych awarii, które mogą być naprawione ponowną próbą
• Sytuacji nie wymagających natychmiastowej uwagi operatora

Poziom error jest zarezerwowany dla:

• Ostatecznych nieudanych prób wykonania
• Krytycznych błędów, które czynią dalsze ponawianie bezsensownym
• Sytuacji wymagających natychmiastowej interwencji

Numeracja prób powinna być prowadzona od większej do mniejszej (2 → 1 → 0), gdzie 0 oznacza ostatnią próbę. To pozwala łatwo filtrować logi po finalnych błędach.

Praktyczna implementacja przez interceptory

Nowoczesne frameworki zapewniają mechanizmy interceptorów do implementacji funkcjonalności przechodzącej. Schemat logowania EP przez interceptory:

• Inicjalizacja kontekstu — ustawienie traceId, spanId w MDC
• Logowanie wejścia — zapis metadanych i parametrów wejściowych EP
• Przetwarzanie żądania — wykonanie logiki biznesowej z automatycznym logowaniem przez MDC
• Logowanie wyjścia — zapis wyniku lub błędu
• Czyszczenie kontekstu — usunięcie wszystkich danych z MDC

Kluczowe komponenty do implementacji:

• Interceptor logowania wejścia/wyjścia dla każdego typu EP
• Integracja z systemem śledzenia (Jaeger, Zipkin)
• Automatyczne wyodrębnianie identyfikatorów biznesowych z nagłówków
• Jednolity format serializacji logów w JSON

Obowiązkowe pola w strukturalizowanych logach

Aby zapewnić spójność i wygodę analizy, wszystkie logi powinny zawierać:

• Podstawowe pola techniczne

- timestamp w formacie ISO-8601

- poziom logowania (ERROR, WARN, INFO, DEBUG)

- nazwa serwisu i jego wersja

- identyfikator instancji aplikacji

• Kontekst wykonania

- traceId i spanId dla korelacji żądań

- identyfikator żądania (requestId)

- typ i nazwa punktu wejścia

- numer próby wykonania (retry count)

• Kontekst biznesowy

- główne identyfikatory biznesowe (user_id, order_id itp.)

- metadane żądania (metoda HTTP, endpoint, grupa konsumentów)

- środowisko wykonania (etap, region, klaster)

• Dane zdarzenia

- czytelna dla człowieka wiadomość

- strukturalizowane dane zdarzenia

- ślad stosu błędów (dla poziomu ERROR)

- czas trwania wykonania (dla logów EP)

Integracja z ekosystemem obserwowalności

Strukturalizowane logi nie istnieją w izolacji — są częścią kompleksowego systemu obserwowalności:

Korelacja z metrykami:

• Użycie identycznych identyfikatorów w logach i metrykach
• Powiązanie logów błędów z metrykami error rate
• Kontekstualizacja anomalii w metrykach przez logi

Integracja ze śledzeniem:

• Jednolite traceId/spanId w logach i śladach
• Uzupełnianie śladów szczegółami z logów
• Użycie logów do debugowania konkretnych spanów

Automatyzacja przetwarzania:

• Automatyczne powiadomienia na podstawie wzorców w logach
• Integracja z systemami zarządzania incydentami
• Automatyczne wyodrębnianie danych do odzyskiwania

Co jest ważne

• Strukturalizowane logi w JSON zapewniają format czytelny dla maszyn, upraszczający automatyczne przetwarzanie i analizę danych.
• Kontekst MDC rozwiązuje problem przekazywania identyfikatorów biznesowych przez łańcuch wywołań bez zmiany sygnatur metod.
• Wyraźne rozdzielenie error/warning jest konieczne dla poprawnej pracy mechanizmów ponawiania i zmniejszenia szumu w monitorowaniu.
• Jednolity schemat logowania EP zapewnia spójność i upraszcza analizę transakcji rozproszonych.
• Obowiązkowy zestaw pól w każdym logu gwarantuje możliwość korelacji zdarzeń i efektywnego wyszukiwania.

— Editorial Team