- Strona główna
- Przewodnik
- Logowanie strukturalne z JSONL
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
Polecanastructlog 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ą.
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
Najszybszypino 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.
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 alokacjizerolog 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.
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.
# 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.
# 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.
[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 OnFluentd 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.
# 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
AWSCloudWatch 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.
# 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 descGCP Cloud Logging
GCPGoogle 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ć.
# 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 >= ERRORAzure Monitor Logs
AzureAzure 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.
// 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 CountDobre 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.
{"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.
// 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.
Sprawdź poprawność logów JSONL online
Korzystaj z naszych bezpłatnych narzędzi w przeglądarce, aby przeglądać pliki logów JSONL, sprawdzać ich poprawność i konwertować je na inne formaty. Nie musisz przesyłać plików na serwer — całe przetwarzanie odbywa się lokalnie.
Dowiedz się, jak strumieniować dane JSONL w Node.js i Pythonie. Obejmuje SSE, WebSockets i przetwarzanie logów w czasie rzeczywistym.
Sposoby przetwarzania gigabajtów danych JSONL: odczyt strumieniowy, zarządzanie pamięcią, dzielenie plików, kompresja i narzędzia online.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Formatuj pliki JSONL, nadając im czytelny układ z odpowiednimi wcięciami. Ułatw sobie debugowanie i przeglądanie danych.
Otwieraj pliki .jsonl i .ndjson w postaci tabeli, którą można szybko przeglądać i przeszukiwać — bezpośrednio w edytorze. Rozszerzenie powstało z myślą o plikach zbyt dużych do zwykłego przewijania oraz logach, do których wciąż dopisywane są nowe wpisy.