Strukturované logy JSON: průvodce pro vývojáře

Strukturované logy v JSON: praktický průvodce pro vývojáře

Logování je kriticky důležitá součást observability v moderních distribuovaných systémech. Na rozdíl od metrik a stop poskytují logy maximální flexibilitu pro analýzu událostí v aplikaci. Tento článek nabízí konkrétní vzory pro implementaci efektivního logování s využitím strukturovaného formátu JSON, MDC kontextu a jasného rozdělení úrovní chyb.

Proč jsou strukturované logy důležitější než prostý text

Tradiční prosté logy, vhodné pro čtení z konzole, vytvářejí významné problémy při automatickém zpracování. Jejich parsování vyžaduje složité regulární výrazy, extrakce konkrétních dat je obtížná a změna formátu se stává bolestivým procesem. V distribuovaných systémech, kde incidenty vyžadují rychlou analýzu dat z mnoha zdrojů, se tyto nedostatky stávají kritickými.

Strukturované logy ve formátu JSON řeší tyto problémy:

• Zjednodušují vyhledávání a filtraci podle konkrétních polí
• Umožňují částečné indexování v vyhledávacích systémech
• Usnadňují automatickou extrakci dat po incidentech
• Zjednodušují filtraci osobních údajů a přidávání metainformací

Příklad neefektivního prostého logu:

2025-03-15 10:16:01.795 INFO 12345 --- [nio-8080-exec-1] c.e.UserController : Uživatel uložen v databázi: User{id=123, [email protected], role=USER}

Příklad strukturovaného logu v 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": "Selhalo ověření uživatele",
  "user_id": "user-789",
  "error": {
    "type": "InvalidCredentials",
    "details": "Poskytnuté heslo se neshoduje"
  }
}

Mapped Diagnostic Context pro průchozí identifikaci

Mapped Diagnostic Context (MDC) v SLF4J řeší problém přenosu kontextových informací přes řetězec volání. Namísto explicitního předávání identifikátorů přes všechny metody umožňuje MDC asociovat data s aktuálním vláknem provádění.

Klíčové aspekty použití MDC:

• Business identifikátory — user_id, order_id, transaction_id
• Technický kontext — traceId, spanId pro trasování
• Metainformace EP — typ entrypointu, číslo pokusu provedení
• Automatické čištění — povinné vyčištění kontextu po dokončení zpracování

MDC je zvláště důležitý pro entrypointy, kde musí být business identifikátory dostupné od samého začátku zpracování požadavku, často extrahované z hlaviček před čtením payload.

Body vstupu (Entrypoints) a jejich logování

Entrypoint (EP) — abstrakce označující začátek provedení business logiky. V moderních aplikacích jsou běžné:

• HTTP/REST servery
• gRPC servery
• Kafka consumers
• Cron jobs a scheduled tasks
• Message queue listeners

Každý EP by měl být logován podle jednotného schématu:

• Vstupní parametry — metadata a payload požadavku
• Kontext provedení — business identifikátory, technické parametry
• Výstupní data — výsledek zpracování nebo chyba
• Stav provedení — úspěch/neúspěch s ohledem na retry politiku

Rozdělení error a warning v distribuovaných systémech

V distribuovaných systémech jsou retry mechanismy standardním přístupem pro zajištění spolehlivosti. To přímo ovlivňuje strategii logování:

Warning úroveň se používá pro:

• Chyby při mezilehlých pokusech provedení
• Dočasné výpadky, které mohou být opraveny opakovaným pokusem
• Situace, které nevyžadují okamžitou pozornost operátora

Error úroveň je rezervována pro:

• Finální neúspěšné pokusy provedení
• Kritické chyby, které činí další retry zbytečné
• Situace vyžadující okamžitý zásah

Číslování pokusů by mělo být od většího k menšímu (2 → 1 → 0), kde 0 znamená poslední pokus. To umožňuje snadno filtrovat logy podle finálních chyb.

Praktická implementace přes interceptory

Moderní frameworky poskytují mechanismy interceptorů pro implementaci průchozí funkčnosti. Schéma logování EP přes interceptory:

• Inicializace kontextu — nastavení traceId, spanId v MDC
• Logování vstupu — zápis metadat a vstupních parametrů EP
• Zpracování požadavku — provedení business logiky s automatickým logováním přes MDC
• Logování výstupu — zápis výsledku nebo chyby
• Vyčištění kontextu — odstranění všech dat z MDC

Klíčové komponenty pro implementaci:

• Interceptor logování vstupu/výstupu pro každý typ EP
• Integrace se systémem trasování (Jaeger, Zipkin)
• Automatická extrakce business identifikátorů z hlaviček
• Jednotný formát serializace logů v JSON

Povinná pole ve strukturovaných logách

Pro zajištění konzistence a pohodlí analýzy by všechny logy měly obsahovat:

• Základní technická pole

- timestamp ve formátu ISO-8601

- úroveň logování (ERROR, WARN, INFO, DEBUG)

- název služby a její verze

- identifikátor instance aplikace

• Kontext provedení

- traceId a spanId pro korelaci požadavků

- identifikátor požadavku (requestId)

- typ a název entrypointu

- číslo pokusu provedení (retry count)

• Business kontext

- hlavní business identifikátory (user_id, order_id atd.)

- metadata požadavku (HTTP metoda, endpoint, consumer group)

- prostředí provedení (stage, region, cluster)

• Data události

- čitelné zprávy pro člověka

- strukturovaná data události

- stacktrace chyb (pro ERROR úroveň)

- doba trvání provedení (pro EP logy)

Integrace s ekosystémem observability

Strukturované logy neexistují izolovaně — jsou součástí komplexního systému observability:

Korelace s metrikami:

• Použití stejných identifikátorů v lozích a metrikách
• Spojení logů chyb s metrikami error rate
• Kontextualizace anomálií v metrikách přes logy

Integrace s trasováním:

• Jednotné traceId/spanId v lozích a stopách
• Doplnění stop detaily z logů
• Použití logů pro debug konkrétních spanů

Automatizace zpracování:

• Automatické upozornění na základě vzorů v lozích
• Integrace se systémy incident managementu
• Automatická extrakce dat pro obnovu

Co je důležité

• Strukturované logy v JSON zajišťují strojově čitelný formát, který zjednodušuje automatické zpracování a analýzu dat.
• MDC kontext řeší problém předávání business identifikátorů přes řetězec volání bez změny signatur metod.
• Jasné rozdělení error/warning je nezbytné pro správnou funkci retry mechanismů a snížení šumu v monitorování.
• Jednotné schéma logování EP zajišťuje konzistenci a zjednodušuje analýzu distribuovaných transakcí.
• Povinná sada polí v každém logu garantuje možnost korelace událostí a efektivního vyhledávání.

— Editorial Team