Autor: Jerry Fan

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.

Odczyt strumieniowy z readline
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.

Strumienie Transform w potokach przetwarzania
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.

Strumieniowanie z użyciem generatorów
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.

Łączenie etapów przetwarzania z itertools
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ą.

Serwer SSE (Node.js / Express)
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.

Klient SSE w przeglądarce
// 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.

Serwer WebSocket przesyłający wiadomości JSONL
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.

Kolektor logów JSONL działający w czasie rzeczywistym
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.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez wysyłania plików na serwer, ze 100% prywatności.

Najczęściej zadawane pytania

Źródła