Door Jerry Fan

JSONL streamen: gegevens in realtime verwerken

Een uitgebreide gids voor het streamen van JSONL-gegevens in realtime. Leer streamingpipelines bouwen met readline in Node.js, generators in Python, Server-Sent Events en WebSockets, en ontdek patronen voor logstreaming in productie.

Waarom JSONL ideaal is voor streaming

JSONL (JSON Lines) slaat per regel één volledig JSON-object op, met een newline-teken tussen de regels. Deze structuur maakt het formaat ideaal voor streaming: elke regel staat op zichzelf en kan afzonderlijk worden geparseerd. Bij één grote JSON-array moet je eerst de volledige dataset in het geheugen laden voordat je records kunt verwerken; bij JSONL hoeft dat niet. Een consumer kan een regel lezen, parseren en verwerken, en daarna doorgaan met de volgende. Het geheugengebruik blijft daarbij constant, ongeacht hoe groot de gegevensbron wordt.

Daarom wordt JSONL veel gebruikt in systemen voor logaggregatie, pipelines voor realtime analyses, datafeeds voor machine learning en streamingresponses van API's. Tools zoals de OpenAI API, AWS CloudWatch en Apache Kafka gebruiken allemaal JSON met newline-tekens als scheiding. Zo combineren ze de universele leesbaarheid van JSON met de efficiënte streaming van protocollen die regel voor regel werken. In deze gids leer je hoe je JSONL-streamingoplossingen bouwt in Node.js en Python, realtime gegevens naar browsers pusht met Server-Sent Events, JSONL uitwisselt via WebSockets en een logstreamingsysteem implementeert dat geschikt is voor productie.

JSONL streamen in Node.js

Node.js werkt met een event-driven, non-blocking I/O-model en is daardoor bijzonder geschikt voor streaming. Met de ingebouwde modules readline en stream heb je alles in huis om JSONL-bestanden en netwerkstreams regel voor regel te verwerken, zonder de volledige payload in het geheugen te laden.

De readline-module in combinatie met fs.createReadStream is de gebruikelijke manier om een JSONL-bestand in Node.js te lezen. Het bestand wordt in chunks ingelezen en als volledige regels doorgegeven. Daardoor blijft het geheugengebruik constant, zelfs bij bestanden van meerdere gigabytes.

Streams lezen met 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`);

Met Transform-streams in Node.js bouw je datapipelines uit losse, combineerbare onderdelen die JSONL lezen, records filteren of verrijken en de resultaten weer wegschrijven. Backpressure wordt daarbij automatisch afgehandeld: de bron pauzeert wanneer de bestemming de gegevens niet snel genoeg kan verwerken.

Pipelines bouwen met Transform-streams
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');

JSONL streamen in Python

Met generators in Python kun je JSONL-gegevens op een elegante manier streamen. Een generator levert telkens één record op en gaat pas verder wanneer de consumer de volgende waarde opvraagt. Daardoor blijft het geheugengebruik minimaal. In combinatie met de ingebouwde json-module bouw je met slechts een paar regels code krachtige streamingpipelines.

Een generatorfunctie in Python leest het bestand regel voor regel met een gewone for-lus. Elke aanroep van next() leest precies één regel, parseert die en levert het resultaat op. De file handle blijft open en de leespositie schuift pas op wanneer de consumer records opvraagt.

Streamen met een generator
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")

Met itertools in Python combineer je streamingbewerkingen zoals filteren, batchen en slicen zonder tussenresultaten in het geheugen op te slaan. Elke stap in de keten verwerkt één record tegelijk. Zo kun je bestanden verwerken die groter zijn dan het beschikbare RAM.

Verwerkingsstappen combineren met 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 met JSONL

Server-Sent Events (SSE) bieden een eenvoudig protocol op basis van HTTP om realtime updates van de server naar de client te pushen. Elk SSE-event bevat een data-veld. JSONL is daarvoor een logisch payloadformaat: elke regel is een volledig JSON-object dat de client direct kan parseren. Anders dan WebSockets werkt SSE via standaard HTTP, zonder speciale proxyconfiguratie. Bij uitval wordt de verbinding automatisch hersteld.

De server stelt Content-Type in op text/event-stream en schrijft elk JSONL-record naar het data-veld van een SSE-event. De verbinding blijft open en de server pusht nieuwe events zodra ze beschikbaar zijn.

SSE-server (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'));

De browser maakt via de EventSource API verbinding met het SSE-endpoint. Elk binnenkomend event bevat een JSONL-record dat direct wordt geparseerd en in realtime wordt weergegeven. Valt de verbinding weg, dan maakt EventSource automatisch opnieuw verbinding.

SSE-client (browser)
// 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);
});

JSONL streamen via WebSockets

Met SSE pusht de server gegevens naar de client. WebSockets bieden full-duplex communicatie: beide kanten kunnen op elk moment JSONL-records versturen. Dat is ideaal voor interactieve toepassingen, zoals samen documenten bewerken, realtime dashboards met gebruikerscommando's en gegevenssynchronisatie in beide richtingen. Elk WebSocket-bericht bevat één JSONL-record, zodat beide kanten de berichten eenvoudig kunnen parseren.

WebSocket-server met JSONL-berichten
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' }));

Elk WebSocket-bericht bevat één JSON-object, volgens de JSONL-conventie van één record per bericht. De server streamt elke 500ms metrics naar de client en accepteert tegelijkertijd commando's van de client. In beide richtingen wordt dezelfde JSON-serialisatie gebruikt. Daardoor is het protocol symmetrisch en eenvoudig te debuggen.

Logstreaming in de praktijk

Een van de meest voorkomende toepassingen van JSONL-streaming is het centraal verzamelen van logs. Applicaties schrijven gestructureerde logregels als JSONL naar stdout of een bestand. Een collector-agent volgt de uitvoer in realtime en stuurt de records door naar een centraal systeem. Docker, Kubernetes en de meeste cloudloggingdiensten gebruiken dit patroon.

JSONL-logs verzamelen in realtime
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();

Deze collector volgt een JSONL-logbestand in realtime en stuurt records op basis van hun logniveau door naar de bijbehorende handlers. De collector houdt de leespositie in het bestand bij en leest, nadat de bestaande inhoud is verwerkt, alleen nog nieuwe inhoud. Voor gebruik in productie zou je detectie van logrotatie en graceful shutdown toevoegen. Ook zou je records in batches doorsturen om het aantal netwerkaanroepen naar je centrale loggingsysteem te beperken.

Online met JSONL-bestanden werken

Bekijk, valideer en converteer JSONL-bestanden tot 1GB direct in je browser. Je hoeft niets te uploaden: 100% privé.

Veelgestelde vragen

Bronnen