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.
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.
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.
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.
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.
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.
// 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.
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.
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.
Probeer onze gratis JSONL-tools
Wil je JSONL-gegevens bekijken of converteren voordat je een streamingpipeline bouwt? Met onze gratis online tools kun je JSONL-bestanden direct in je browser bekijken, converteren en formatteren. Alles wordt lokaal verwerkt, dus je gegevens blijven privé.
Strategieën om gigabytes aan JSONL-data te verwerken. Met aandacht voor lezen via streaming, geheugenbeheer, het splitsen van bestanden, compressie en online tools.
Leer gestructureerd loggen met JSONL. Integreer met ELK Stack, Fluentd, CloudWatch, GCP Logging en Azure Monitor, met voorbeelden voor Python, Node.js en Go die geschikt zijn voor productie.
Leer de best practices voor JSONL toepassen: opmaak, consistente schema’s, foutafhandeling, prestatieoptimalisatie en het organiseren van bestanden. Vermijd veelvoorkomende valkuilen aan de hand van praktische voorbeelden.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Leer hoe je het JSONL-formaat gebruikt in JavaScript en Node.js.