Autor: Jerry Fan

Logowanie strukturalne z JSONL

Kompletny przewodnik po logowaniu strukturalnym w formacie JSONL (JSON Lines). Dowiedz się, jak zintegrować logi z ELK Stack, Fluentd, CloudWatch, GCP Logging i Azure Monitor, korzystając z przykładów kodu gotowych do użycia w środowisku produkcyjnym.

Dlaczego warto stosować logowanie strukturalne z JSONL?

Tradycyjne logi tekstowe są czytelne dla człowieka, ale ich niezawodne parsowanie przez maszyny jest niemal niemożliwe. We wpisie takim jak '2024-01-15 ERROR User login failed for admin' poziom ważności, typ zdarzenia i nazwa użytkownika są ukryte w nieustrukturyzowanym ciągu tekstu. Każde narzędzie do agregacji logów musi korzystać z podatnych na błędy wyrażeń regularnych, aby wydobyć te informacje, a każda zmiana formatu logów zakłóca cały proces ich przetwarzania.

Logowanie strukturalne rozwiązuje ten problem: każdy wpis jest zapisywany jako obiekt JSON z jasno zdefiniowanymi polami. JSONL (JSON Lines) idzie o krok dalej: jeden obiekt JSON w każdym wierszu, bez otaczającej tablicy i bez końcowych przecinków. Dzięki temu do logów JSONL łatwo dopisywać kolejne wpisy, można je przetwarzać strumieniowo, a ich parsowanie jest proste w każdej z głównych platform do obsługi logów. W tym przewodniku dowiesz się, jak generować logi JSONL w Pythonie, Node.js i Go oraz jak przesyłać je do ELK, Fluentd i usług trzech głównych dostawców chmury.

W porównaniu z innymi formatami danych strukturalnych, takimi jak CSV czy XML, JSONL najlepiej łączy elastyczność, obsługę w narzędziach i czytelność dla człowieka. Pola mogą być zagnieżdżone, typy danych są zachowywane, a stałego schematu nie trzeba definiować z góry. Właśnie dlatego JSONL stał się de facto standardem logowania strukturalnego w nowoczesnej infrastrukturze.

Biblioteki do logowania w poszczególnych językach

Większość współczesnych bibliotek do logowania obsługuje zapis danych strukturalnych w formacie JSON od razu lub po prostej zmianie konfiguracji. Poniżej znajdziesz polecane biblioteki dla Pythona, Node.js i Go. Każda z nich generuje dane zgodne z formatem JSONL.

Python: structlog

Polecana

structlog to wiodąca biblioteka do logowania strukturalnego w Pythonie. Stanowi warstwę nad standardowym modułem logging i domyślnie zapisuje logi w formacie JSON. Łańcuch procesorów pozwala uzupełniać, filtrować i przekształcać wpisy przed serializacją.

Python: structlog
import structlog


# Konfiguracja structlog dla wyjscia JSONL
structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.add_log_level,
        structlog.processors.StackInfoRenderer(),
        structlog.processors.JSONRenderer(),
    ],
    wrapper_class=structlog.BoundLogger,
    context_class=dict,
    logger_factory=structlog.PrintLoggerFactory(),
)


log = structlog.get_logger()


# Kazde wywolanie generuje jedna linie JSONL
log.info("user.login", user_id="u-42", ip="10.0.0.1")
# {"event":"user.login","user_id":"u-42","ip":"10.0.0.1","level":"info","timestamp":"2026-02-15T08:30:00Z"}


log.error("db.connection_failed", host="db-primary", retries=3)
# {"event":"db.connection_failed","host":"db-primary","retries":3,"level":"error","timestamp":"2026-02-15T08:30:01Z"}

Node.js: pino

Najszybszy

pino to najszybszy logger dla Node.js. Domyślnie zapisuje logi w formacie JSONL i nie wymaga konfiguracji. Asynchroniczny zapis i ograniczenie do minimum operacji związanych z serializacją zapewniają niski narzut. Dodatkowy pakiet pino-pretty pozwala wyświetlać logi w czytelnej postaci podczas pracy lokalnej.

Node.js: pino
import pino from 'pino';


// pino domyslnie generuje wyjscie JSONL
const log = pino({
  level: 'info',
  timestamp: pino.stdTimeFunctions.isoTime,
});


// Kazde wywolanie generuje jedna linie JSONL
log.info({ userId: 'u-42', ip: '10.0.0.1' }, 'user.login');
// {"level":30,"time":"2026-02-15T08:30:00.000Z","userId":"u-42","ip":"10.0.0.1","msg":"user.login"}


log.error({ host: 'db-primary', retries: 3 }, 'db.connection_failed');
// {"level":50,"time":"2026-02-15T08:30:01.000Z","host":"db-primary","retries":3,"msg":"db.connection_failed"}


// Loggery potomne dziedzicza kontekst
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');

Go: zerolog

Bez alokacji

zerolog to logger JSON dla Go, który nie alokuje pamięci i został zaprojektowany z myślą o maksymalnej wydajności w usługach o dużej przepustowości. Zapisuje dane bezpośrednio do io.Writer, bez pośrednich alokacji, dzięki czemu idealnie nadaje się do aplikacji wrażliwych na opóźnienia. API oparte na łańcuchach wywołań jest wygodne i wydajne.

Go: zerolog
package main


import (
    "os"
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)


func main() {
    // Konfiguracja wyjscia JSONL do stdout
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()


    // Kazde wywolanie generuje jedna linie JSONL
    log.Info().
        Str("user_id", "u-42").
        Str("ip", "10.0.0.1").
        Msg("user.login")
    // {"level":"info","user_id":"u-42","ip":"10.0.0.1","time":1739608200,"message":"user.login"}


    log.Error().
        Str("host", "db-primary").
        Int("retries", 3).
        Msg("db.connection_failed")
}

Integracja z ELK Stack

ELK Stack (Elasticsearch, Logstash, Kibana) to najpowszechniej wdrażana platforma open source do zarządzania logami. Integracja z logami JSONL jest prosta, ponieważ Logstash i Filebeat mają wbudowaną obsługę parsowania JSON. Eliminuje to potrzebę tworzenia złożonych wzorców grok.

Filebeat to lekki agent, który na bieżąco odczytuje nowe wpisy z plików logów JSONL i przesyła je do Logstash lub Elasticsearch. Ustawienie json.keys_under_root na true umieszcza pola JSON na najwyższym poziomie dokumentu w Elasticsearch, dzięki czemu można je bezpośrednio przeszukiwać w Kibanie.

Konfiguracja Filebeat
# filebeat.yml
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/app/*.jsonl
    json.keys_under_root: true
    json.add_error_key: true
    json.message_key: message
    json.overwrite_keys: true


output.elasticsearch:
  hosts: ["http://elasticsearch:9200"]
  index: "app-logs-%{+yyyy.MM.dd}"


# Opcjonalnie: wyslij do Logstash zamiast
# output.logstash:
#   hosts: ["logstash:5044"]

Jeśli przed indeksowaniem potrzebujesz przekształcić logi lub uzupełnić je o dodatkowe dane, umieść Logstash między Filebeat a Elasticsearch. Kodek json automatycznie parsuje każdy wiersz JSONL. Użyj filtra mutate, aby zmienić nazwy pól, dodać tagi lub usunąć dane wrażliwe przed zapisaniem logów.

Potok przetwarzania w Logstash
# logstash.conf
input {
  beats {
    port => 5044
    codec => json
  }
}


filter {
  # Parsuj znacznik czasu z pola JSON
  date {
    match => ["timestamp", "ISO8601"]
    target => "@timestamp"
  }


  # Dodaj tag srodowiska
  mutate {
    add_field => { "environment" => "production" }
    remove_field => ["agent", "ecs", "host"]
  }


  # Kieruj wedlug poziomu logu
  if [level] == "error" or [level] == "fatal" {
    mutate { add_tag => ["alert"] }
  }
}


output {
  elasticsearch {
    hosts => ["http://elasticsearch:9200"]
    index => "app-logs-%{+YYYY.MM.dd}"
  }
}

Fluentd i Fluent Bit

Fluentd i jego lżejszy odpowiednik Fluent Bit to projekty o statusie Graduated w CNCF, powszechnie używane w środowiskach Kubernetes. Oba mają wbudowaną obsługę logów JSONL i mogą przesyłać je praktycznie wszędzie: do Elasticsearch, S3 czy natywnych usług chmurowych do obsługi logów.

Fluent Bit to preferowany kolektor logów dla Kubernetes i środowisk o ograniczonych zasobach. Zużywa około 450KB pamięci i może przetwarzać setki tysięcy rekordów na sekundę. Parser json obsługuje dane wejściowe JSONL bez dodatkowej konfiguracji.

Konfiguracja Fluent Bit
[SERVICE]
    Flush        5
    Daemon       Off
    Log_Level    info
    Parsers_File parsers.conf


[INPUT]
    Name         tail
    Path         /var/log/app/*.jsonl
    Parser       json
    Tag          app.*
    Refresh_Interval 5


[FILTER]
    Name         modify
    Match        app.*
    Add          cluster production-us-east-1
    Add          service my-api


[OUTPUT]
    Name         es
    Match        app.*
    Host         elasticsearch
    Port         9200
    Index        app-logs
    Type         _doc
    Logstash_Format On

Fluentd ma bogatszy ekosystem wtyczek niż Fluent Bit — ponad 500 wtyczek tworzonych przez społeczność. Wybierz go, gdy potrzebujesz zaawansowanego routingu, buforowania lub przekształcania danych. Wtyczka in_tail z ustawieniem format json ma wbudowaną obsługę odczytu plików JSONL.

Konfiguracja Fluentd
# fluentd.conf
<source>
  @type tail
  path /var/log/app/*.jsonl
  pos_file /var/log/fluentd/app.pos
  tag app.logs
  <parse>
    @type json
    time_key timestamp
    time_format %Y-%m-%dT%H:%M:%S%z
  </parse>
</source>


<filter app.logs>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    environment production
  </record>
</filter>


<match app.logs>
  @type elasticsearch
  host elasticsearch
  port 9200
  index_name app-logs
  logstash_format true
  <buffer>
    @type memory
    flush_interval 5s
    chunk_limit_size 5m
  </buffer>
</match>

Usługi do obsługi logów w chmurze

Wszyscy trzej główni dostawcy chmury przyjmują logi w formacie JSONL i automatycznie parsują pola JSON, udostępniając je jako atrybuty, które można przeszukiwać i filtrować. Dzięki temu nie musisz utrzymywać własnej infrastruktury do obsługi logów, a zachowujesz te same możliwości wykonywania zapytań na danych strukturalnych.

AWS CloudWatch Logs

AWS

CloudWatch Logs automatycznie parsuje wpisy logów w formacie JSON, dzięki czemu każde pole jest dostępne w zapytaniach CloudWatch Logs Insights. Jeśli aplikacja działa w ECS, Lambda lub EC2 z agentem CloudWatch, logi JSONL są indeksowane jako dane strukturalne bez dodatkowej konfiguracji. Składnia Logs Insights, zbliżona do SQL, pozwala w kilka sekund wykonywać zapytania obejmujące miliony wpisów.

AWS CloudWatch Logs
# Przyklady zapytan CloudWatch Logs Insights
# Znajdz wszystkie bledy z ostatniej godziny
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100


# Agreguj liczbe bledow wedlug typu zdarzenia
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc


# P99 opoznienia wedlug endpointu
fields path, duration_ms
| filter ispresent(duration_ms)
| stats pct(duration_ms, 99) as p99 by path
| sort p99 desc

GCP Cloud Logging

GCP

Google Cloud Logging (dawniej Stackdriver) ma pełną, wbudowaną obsługę danych JSON jako strukturalnych wpisów logów. Gdy zapisujesz JSONL na stdout w Cloud Run, GKE lub Cloud Functions, agent zbierający logi parsuje każdy wiersz do postaci strukturalnego obiektu LogEntry. Pole severity odpowiada bezpośrednio poziomom ważności w Cloud Logging, a pola jsonPayload są indeksowane i można je przeszukiwać.

GCP Cloud Logging
# Przyklad Python dla Cloud Run / Cloud Functions
import json
import sys


def log(severity: str, message: str, **fields):
    """Zapisz wpis logu JSONL kompatybilny z GCP Cloud Logging."""
    entry = {
        "severity": severity.upper(),  # Mapuje na poziom waznosci Cloud Logging
        "message": message,
        **fields,
    }
    print(json.dumps(entry), file=sys.stdout, flush=True)


# GCP automatycznie parsuje te jako strukturalne logi
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)


# Zapytanie w Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERROR

Azure Monitor Logs

Azure

Azure Monitor przyjmuje logi JSONL za pośrednictwem Azure Monitor Agent lub bezpośrednio przez API. Application Insights automatycznie parsuje ślady w formacie JSON i zdarzenia niestandardowe. KQL (Kusto Query Language) oferuje rozbudowane możliwości wykonywania zapytań na strukturalnych danych z logów, w tym agregację, analizę szeregów czasowych i wykrywanie anomalii.

Azure Monitor Logs
// Zapytania KQL dla logow JSONL w Azure Monitor
// Znajdz ostatnie bledy
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| project TimeGenerated, parsed.event, parsed.user_id,
          parsed.error_message
| order by TimeGenerated desc
| take 100


// Wskaznik bledow w czasie (kubly 5-minutowe)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart


// Najczestsze zdarzenia bledow
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by Count

Dobre praktyki logowania w formacie JSONL

Spójne konwencje we wszystkich usługach ułatwiają przeszukiwanie i korelowanie logów JSONL oraz definiowanie alertów na ich podstawie. Poniższe dobre praktyki pochodzą z systemów produkcyjnych przetwarzających miliardy wpisów dziennie.

Stosuj spójne poziomy logowania

Przyjmij standardową skalę ważności i stosuj ją konsekwentnie we wszystkich usługach. Najczęściej używa się pięciu poziomów: DEBUG do diagnostyki podczas tworzenia aplikacji, INFO do rejestrowania normalnego działania, WARN do problemów, po których aplikacja może kontynuować pracę, ERROR do błędów wymagających uwagi i FATAL do awarii, po których nie da się wznowić działania. Podczas przyjmowania logów mapuj poziomy liczbowe (np. skalę 10-60 w pino) na te nazwy tekstowe, aby ujednolicić zapytania.

Stosuj spójne poziomy logowania
{"level":"debug","event":"cache.miss","key":"user:42","timestamp":"2026-02-15T08:30:00Z"}
{"level":"info","event":"request.completed","method":"GET","path":"/api/users","status":200,"duration_ms":45,"timestamp":"2026-02-15T08:30:01Z"}
{"level":"warn","event":"rate_limit.approaching","client_id":"c-99","current":950,"limit":1000,"timestamp":"2026-02-15T08:30:02Z"}
{"level":"error","event":"payment.failed","order_id":"ord-123","error":"card_declined","timestamp":"2026-02-15T08:30:03Z"}
{"level":"fatal","event":"startup.failed","reason":"missing DATABASE_URL","timestamp":"2026-02-15T08:30:04Z"}

Stosuj jednolite nazwy pól

Zdefiniuj wspólny schemat dla pól używanych we wszystkich usługach. Stosuj snake_case w nazwach pól, ISO 8601 w znacznikach czasu oraz spójne nazwy identyfikatorów korelacji. Każdy wpis powinien zawierać co najmniej pola: timestamp, level, event (nazwa zdarzenia przeznaczona do przetwarzania maszynowego) i service. Wpisy dotyczące konkretnego żądania powinny też zawierać request_id i user_id, aby umożliwić śledzenie.

Stosuj jednolite nazwy pól
// Zalecany schemat pol
{
  "timestamp": "2026-02-15T08:30:00.000Z",  // ISO 8601, zawsze UTC
  "level": "info",                            // debug|info|warn|error|fatal
  "event": "order.created",                    // nazwa zdarzenia w notacji kropkowej
  "service": "order-api",                      // usluga emitujaca
  "version": "1.4.2",                          // wersja uslugi
  "request_id": "req-abc-123",                 // ID korelacji
  "trace_id": "4bf92f3577b34da6",              // ID sladu rozproszonego
  "user_id": "u-42",                           // uwierzytelniony uzytkownik
  "duration_ms": 120,                          // numeryczny, nie string
  "order_id": "ord-789",                       // kontekst domenowy
  "items_count": 3                             // kontekst domenowy
}

Wydajność

Logowanie strukturalne wiąże się z narzutem serializacji przy każdym wywołaniu loggera. W usługach o dużej przepustowości może on być znaczący. Stosuj logowanie asynchroniczne (pino, zerolog), aby przenieść serializację poza najczęściej wykonywaną ścieżkę kodu. Unikaj logowania dużych obiektów oraz treści żądań i odpowiedzi na poziomie INFO. Stosuj próbkowanie, gdy logów diagnostycznych jest dużo. Zapisuj logi do lokalnych plików, a ich wysyłanie powierz komponentowi typu sidecar (Filebeat, Fluent Bit), zamiast przesyłać je synchronicznie przez sieć.

Używaj asynchronicznych loggerów (pino, zerolog), aby nie blokować głównego wątku podczas serializacji JSON.

Nigdy nie loguj pełnej treści żądań ani odpowiedzi na poziomie INFO. Używaj do tego poziomu DEBUG i włączaj go tylko podczas diagnozowania problemów.

Stosuj próbkowanie zdarzeń, które występują bardzo często. Loguj 1 na 100 żądań sprawdzających stan usługi zamiast wszystkich.

Zapisuj logi do lokalnych plików i przesyłaj je asynchronicznie za pomocą Filebeat lub Fluent Bit. Unikaj synchronicznych wywołań sieciowych w kodzie obsługującym logowanie.

Ustaw maksymalny rozmiar wiersza logu (np. 16KB), aby zbyt duże wpisy nie blokowały potoku przetwarzania.

Stosuj rotację plików logów za pomocą logrotate lub mechanizmu wbudowanego w bibliotekę, aby nie zabrakło miejsca na dysku.

Przeglądaj logi JSONL w przeglądarce

Przeglądaj pliki logów JSONL o rozmiarze do 1GB, przeszukuj je i sprawdzaj ich poprawność. Błyskawiczne wczytywanie, przetwarzanie po stronie klienta, 100% prywatności.

Najczęściej zadawane pytania

Źródła