- Strona główna
- Przewodnik
- Strumieniowanie JSONL: przetwarzanie danych w czasie rzeczywistym
Strumieniowanie JSONL: przetwarzanie danych w czasie rzeczywistym
Szczegółowy przewodnik po strumieniowaniu danych JSONL w czasie rzeczywistym. Dowiedz się, jak budować potoki przetwarzania strumieniowego z użyciem modułu readline w Node.js, generatorów w Pythonie, Server-Sent Events i WebSockets oraz jak strumieniować logi w środowisku produkcyjnym.
Dlaczego JSONL idealnie nadaje się do strumieniowania
JSONL (JSON Lines) zapisuje po jednym kompletnym obiekcie JSON w każdej linii, a kolejne obiekty oddziela znakami nowej linii. Dzięki temu idealnie nadaje się do strumieniowania: każda linia stanowi samodzielną całość, którą można osobno sparsować. W odróżnieniu od jednej dużej tablicy JSON nie musisz wczytywać całego zbioru danych do pamięci, aby rozpocząć przetwarzanie rekordów. Odbiorca danych może odczytać jedną linię, sparsować ją, przetworzyć i przejść do następnej. Zużycie pamięci pozostaje stałe niezależnie od tego, jak duże staje się źródło danych.
Właśnie dlatego JSONL dominuje w systemach agregacji logów, potokach analitycznych działających w czasie rzeczywistym, strumieniach danych do uczenia maszynowego i strumieniowych odpowiedziach API. Narzędzia takie jak API OpenAI, AWS CloudWatch i Apache Kafka korzystają z obiektów JSON rozdzielanych znakami nowej linii, ponieważ ten format łączy powszechnie zrozumiały zapis JSON z wydajnym strumieniowaniem charakterystycznym dla protokołów opartych na liniach. W tym przewodniku dowiesz się, jak strumieniować JSONL w Node.js i Pythonie, przesyłać dane do przeglądarek w czasie rzeczywistym za pomocą Server-Sent Events, wymieniać rekordy JSONL przez WebSockets oraz wdrożyć system strumieniowania logów gotowy do pracy w środowisku produkcyjnym.
Strumieniowanie JSONL w Node.js
Node.js opiera się na zdarzeniowym modelu z nieblokującymi operacjami I/O, dzięki czemu świetnie sprawdza się w przetwarzaniu strumieniowym. Wbudowane moduły readline i stream zapewniają wszystko, czego potrzebujesz, by przetwarzać pliki JSONL i strumienie sieciowe linia po linii, bez wczytywania wszystkich danych do pamięci.
Moduł readline w połączeniu z fs.createReadStream to standardowy sposób odczytu plików JSONL w Node.js. Odczytuje plik porcjami i udostępnia kompletne linie, dzięki czemu zużycie pamięci pozostaje stałe nawet przy plikach o rozmiarze wielu gigabajtów.
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
async function streamJsonl(filePath, onRecord) {
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
let count = 0;
for await (const line of rl) {
const trimmed = line.trim();
if (!trimmed) continue;
try {
const record = JSON.parse(trimmed);
await onRecord(record);
count++;
} catch (err) {
console.error(`Skipping invalid line: ${err.message}`);
}
}
return count;
}
// Usage: process each record as it arrives
const total = await streamJsonl('events.jsonl', async (record) => {
console.log(`Event: ${record.type} at ${record.timestamp}`);
});
console.log(`Processed ${total} records`);Strumienie Transform w Node.js pozwalają budować potoki przetwarzania z połączonych etapów: odczytu JSONL, filtrowania lub wzbogacania każdego rekordu oraz zapisu wyników. Ten wzorzec automatycznie obsługuje backpressure, wstrzymując źródło danych, gdy odbiorca nie nadąża z ich przetwarzaniem.
import { createReadStream, createWriteStream } from 'node:fs';
import { Transform } from 'node:stream';
import { pipeline } from 'node:stream/promises';
// Split incoming chunks into individual lines
class LineSplitter extends Transform {
constructor() {
super({ readableObjectMode: true });
this.buffer = '';
}
_transform(chunk, encoding, cb) {
this.buffer += chunk.toString();
const lines = this.buffer.split('\n');
this.buffer = lines.pop();
for (const line of lines) {
if (line.trim()) this.push(line.trim());
}
cb();
}
_flush(cb) {
if (this.buffer.trim()) this.push(this.buffer.trim());
cb();
}
}
// Parse, transform, and re-serialize each record
class JsonlTransform extends Transform {
constructor(transformFn) {
super({ objectMode: true });
this.transformFn = transformFn;
}
_transform(line, encoding, cb) {
try {
const record = JSON.parse(line);
const result = this.transformFn(record);
if (result) cb(null, JSON.stringify(result) + '\n');
else cb(); // Filter out null results
} catch (err) {
cb(); // Skip invalid lines
}
}
}
// Build the pipeline: read -> split -> transform -> write
await pipeline(
createReadStream('input.jsonl', 'utf-8'),
new LineSplitter(),
new JsonlTransform((record) => {
if (record.level === 'error') {
return { ...record, flagged: true, reviewedAt: new Date().toISOString() };
}
return null; // Filter out non-error records
}),
createWriteStream('errors.jsonl', 'utf-8')
);
console.log('Pipeline complete');Strumieniowanie JSONL w Pythonie
Generatory w Pythonie to wygodny sposób na strumieniowanie danych JSONL. Generator zwraca po jednym rekordzie i przechodzi dalej dopiero wtedy, gdy odbiorca zażąda kolejnej wartości, więc zużycie pamięci pozostaje minimalne. W połączeniu z wbudowanym modułem json pozwala to budować rozbudowane potoki przetwarzania strumieniowego w zaledwie kilku liniach kodu.
Funkcja generatora w Pythonie odczytuje plik linia po linii za pomocą zwykłej pętli for. Każde wywołanie next() odczytuje dokładnie jedną linię, parsuje ją i zwraca wynik. Uchwyt pliku pozostaje otwarty, a pozycja odczytu przesuwa się tylko wtedy, gdy odbiorca pobiera kolejne rekordy.
import json
from typing import Generator, Any
def stream_jsonl(file_path: str) -> Generator[dict[str, Any], None, None]:
"""Stream JSONL records one at a time using a generator."""
with open(file_path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, 1):
line = line.strip()
if not line:
continue
try:
yield json.loads(line)
except json.JSONDecodeError as e:
print(f"Skipping line {line_num}: {e}")
# Usage: process records lazily
for record in stream_jsonl('events.jsonl'):
if record.get('level') == 'error':
print(f"ERROR: {record['message']}")
# Or collect a subset with itertools
import itertools
first_100 = list(itertools.islice(stream_jsonl('large.jsonl'), 100))
print(f"Loaded first {len(first_100)} records")Moduł itertools w Pythonie pozwala łączyć operacje strumieniowe, takie jak filtrowanie, dzielenie na partie i wybieranie fragmentów sekwencji, bez zapisywania wyników pośrednich w pamięci. Każdy etap przetwarza po jednym rekordzie, dzięki czemu możesz obsługiwać pliki większe niż dostępna pamięć RAM.
import json
import itertools
from typing import Generator, Iterable
def stream_jsonl(path: str) -> Generator[dict, None, None]:
with open(path, 'r') as f:
for line in f:
if line.strip():
yield json.loads(line)
def filter_records(records: Iterable[dict], key: str, value) -> Generator[dict, None, None]:
"""Filter records where key equals value."""
for record in records:
if record.get(key) == value:
yield record
def batch(iterable: Iterable, size: int) -> Generator[list, None, None]:
"""Yield successive batches of the given size."""
it = iter(iterable)
while True:
chunk = list(itertools.islice(it, size))
if not chunk:
break
yield chunk
# Compose a streaming pipeline
records = stream_jsonl('access_logs.jsonl')
errors = filter_records(records, 'status', 500)
for i, error_batch in enumerate(batch(errors, 50)):
print(f"Batch {i + 1}: {len(error_batch)} errors")
# Send batch to alerting system, database, etc.
for record in error_batch:
print(f" {record['timestamp']} - {record['path']}")Server-Sent Events z JSONL
Server-Sent Events (SSE) to prosty protokół oparty na HTTP, który pozwala serwerowi przesyłać aktualizacje do klienta w czasie rzeczywistym. Każde zdarzenie SSE zawiera pole data, a JSONL jest naturalnym formatem przesyłanych danych: każda linia to kompletny obiekt JSON, który klient może od razu sparsować. W odróżnieniu od WebSockets SSE korzysta ze standardowego HTTP, nie wymaga specjalnej konfiguracji proxy i automatycznie wznawia połączenie po awarii.
Serwer ustawia nagłówek Content-Type na text/event-stream i zapisuje każdy rekord JSONL w polu data zdarzenia SSE. Połączenie pozostaje otwarte, a serwer wysyła kolejne zdarzenia, gdy tylko się pojawią.
import express from 'express';
const app = express();
// Simulate a real-time data source
function* generateMetrics() {
let id = 0;
while (true) {
yield {
id: ++id,
cpu: Math.random() * 100,
memory: Math.random() * 16384,
timestamp: new Date().toISOString(),
};
}
}
app.get('/api/stream/metrics', (req, res) => {
// SSE headers
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.setHeader('Access-Control-Allow-Origin', '*');
res.flushHeaders();
const metrics = generateMetrics();
const interval = setInterval(() => {
const record = metrics.next().value;
// Each SSE event contains one JSONL record
res.write(`data: ${JSON.stringify(record)}\n\n`);
}, 1000);
req.on('close', () => {
clearInterval(interval);
res.end();
});
});
app.listen(3000, () => console.log('SSE server on :3000'));Przeglądarka łączy się z endpointem SSE za pomocą API EventSource. Każde odebrane zdarzenie zawiera rekord JSONL, który jest na bieżąco parsowany i wyświetlany. W razie zerwania połączenia EventSource automatycznie je wznawia.
// Connect to the SSE endpoint
const source = new EventSource('/api/stream/metrics');
// Parse each JSONL record as it arrives
source.onmessage = (event) => {
const record = JSON.parse(event.data);
console.log(`[${record.timestamp}] CPU: ${record.cpu.toFixed(1)}%`);
// Update your UI in real time
updateDashboard(record);
};
source.onerror = (err) => {
console.error('SSE connection error:', err);
// EventSource automatically reconnects
};
// For Fetch-based SSE (more control over the stream)
async function fetchSSE(url, onRecord) {
const response = await fetch(url);
const reader = response.body
.pipeThrough(new TextDecoderStream())
.getReader();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += value;
const events = buffer.split('\n\n');
buffer = events.pop();
for (const event of events) {
const dataLine = event.split('\n').find(l => l.startsWith('data: '));
if (dataLine) {
const record = JSON.parse(dataLine.slice(6));
onRecord(record);
}
}
}
}
await fetchSSE('/api/stream/metrics', (record) => {
console.log('Metric:', record);
});Strumieniowanie JSONL przez WebSocket
SSE pozwala serwerowi wysyłać dane do klienta, a WebSockets umożliwiają jednoczesną komunikację w obu kierunkach: każda ze stron może w dowolnym momencie wysyłać rekordy JSONL. To idealne rozwiązanie dla aplikacji interaktywnych, takich jak narzędzia do wspólnej edycji, dashboardy aktualizowane w czasie rzeczywistym i obsługujące polecenia użytkownika czy systemy dwukierunkowej synchronizacji danych. Każda wiadomość WebSocket zawiera jeden rekord JSONL, co ułatwia parsowanie po obu stronach.
import { WebSocketServer } from 'ws';
const wss = new WebSocketServer({ port: 8080 });
wss.on('connection', (ws) => {
console.log('Client connected');
// Send JSONL records to the client
const interval = setInterval(() => {
const record = {
type: 'metric',
value: Math.random() * 100,
timestamp: new Date().toISOString(),
};
ws.send(JSON.stringify(record));
}, 500);
// Receive JSONL records from the client
ws.on('message', (data) => {
try {
const record = JSON.parse(data.toString());
console.log(`Received: ${record.type}`, record);
// Echo back an acknowledgment
ws.send(JSON.stringify({
type: 'ack',
originalId: record.id,
processedAt: new Date().toISOString(),
}));
} catch (err) {
ws.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
}
});
ws.on('close', () => {
clearInterval(interval);
console.log('Client disconnected');
});
});
// Client-side usage:
// const ws = new WebSocket('ws://localhost:8080');
// ws.onmessage = (e) => {
// const record = JSON.parse(e.data);
// console.log(record);
// };
// ws.send(JSON.stringify({ type: 'subscribe', channel: 'metrics' }));Każda wiadomość WebSocket zawiera jeden obiekt JSON, zgodnie z zasadą JSONL: jeden rekord na wiadomość. Serwer przesyła klientowi metryki co 500ms, a jednocześnie odbiera od niego polecenia. W obu kierunkach dane są serializowane tak samo, do formatu JSON, dzięki czemu protokół jest symetryczny i łatwy do debugowania.
Strumieniowanie logów w praktyce
Jednym z najczęstszych praktycznych zastosowań strumieniowania JSONL jest centralne zbieranie logów. Aplikacje zapisują wpisy logów w ustrukturyzowanej postaci, jako linie JSONL, na stdout lub do pliku. Agent zbierający logi na bieżąco śledzi dopisywane dane i przekazuje rekordy do centralnego systemu. Z tego wzorca korzystają Docker, Kubernetes i większość usług gromadzenia logów w chmurze.
import { createReadStream, watchFile } from 'node:fs';
import { createInterface } from 'node:readline';
import { stat } from 'node:fs/promises';
class JsonlLogCollector {
constructor(filePath, handlers = {}) {
this.filePath = filePath;
this.handlers = handlers;
this.position = 0;
this.running = false;
}
async start() {
this.running = true;
// Read existing content first
await this.readFrom(0);
// Watch for new appends
this.watch();
}
async readFrom(startPos) {
const rl = createInterface({
input: createReadStream(this.filePath, {
encoding: 'utf-8',
start: startPos,
}),
crlfDelay: Infinity,
});
for await (const line of rl) {
if (!line.trim()) continue;
try {
const record = JSON.parse(line);
await this.dispatch(record);
} catch (err) {
this.handlers.onError?.(err, line);
}
}
const info = await stat(this.filePath);
this.position = info.size;
}
watch() {
watchFile(this.filePath, { interval: 500 }, async (curr, prev) => {
if (!this.running) return;
if (curr.size > this.position) {
await this.readFrom(this.position);
}
});
}
async dispatch(record) {
const level = record.level || 'info';
this.handlers[level]?.(record);
this.handlers.onRecord?.(record);
}
stop() {
this.running = false;
}
}
// Usage
const collector = new JsonlLogCollector('app.log.jsonl', {
error: (r) => console.error(`[ERROR] ${r.message}`),
warn: (r) => console.warn(`[WARN] ${r.message}`),
onRecord: (r) => forwardToElasticsearch(r),
onError: (err, line) => console.error('Bad line:', line),
});
await collector.start();Ten kolektor na bieżąco śledzi plik logów JSONL i przekazuje rekordy do odpowiednich handlerów zależnie od poziomu logowania. Zapamiętuje pozycję w pliku, więc po odczytaniu istniejącej zawartości wczytuje już tylko nowe dane. W wersji produkcyjnej warto dodać wykrywanie rotacji plików, kontrolowane zamykanie oraz wysyłanie rekordów partiami, aby ograniczyć liczbę wywołań sieciowych do centralnego systemu zbierania logów.
Wypróbuj nasze bezpłatne narzędzia do JSONL
Chcesz przejrzeć lub przekonwertować dane JSONL, zanim zbudujesz potok przetwarzania strumieniowego? Skorzystaj z naszych bezpłatnych narzędzi online do przeglądania, konwertowania i formatowania plików JSONL bezpośrednio w przeglądarce. Wszystkie operacje odbywają się lokalnie, więc Twoje dane pozostają prywatne.
Sposoby przetwarzania gigabajtów danych JSONL: odczyt strumieniowy, zarządzanie pamięcią, dzielenie plików, kompresja i narzędzia online.
Poznaj logowanie strukturalne w formacie JSONL i integrację z ELK Stack, Fluentd, CloudWatch, GCP Logging oraz Azure Monitor. Skorzystaj z przykładów dla Pythona, Node.js i Go, gotowych do użycia na produkcji.
Poznaj dobre praktyki pracy z JSONL: formatowanie, spójność schematu, obsługę błędów, optymalizację wydajności i organizację plików. Praktyczne przykłady pomogą Ci uniknąć typowych pułapek.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Dowiedz sie, jak korzystac z formatu JSONL w JavaScript i Node.js.