Streaming JSONL : traiter les données en temps réel
Un guide complet pour traiter des données JSONL en streaming et en temps réel. Apprenez à créer des pipelines avec readline de Node.js, les générateurs Python, les Server-Sent Events et les WebSockets, ainsi qu’à mettre en œuvre des architectures de streaming de logs en production.
Pourquoi JSONL se prête si bien au streaming
JSONL (JSON Lines) stocke un objet JSON complet par ligne, les lignes étant séparées par des caractères de saut de ligne. Cette organisation en fait un format idéal pour le streaming : chaque ligne est autonome et peut être parsée indépendamment. Avec JSONL, vous n’avez jamais besoin de charger tout le jeu de données en mémoire avant de commencer à traiter les enregistrements, comme ce serait le cas avec un seul grand tableau JSON. Le consommateur peut lire une ligne, la parser, la traiter, puis passer à la suivante. La consommation mémoire reste ainsi constante, même lorsque le volume de données augmente.
C’est cette propriété qui explique la prédominance de JSONL dans les systèmes d’agrégation de logs, les pipelines d’analyse en temps réel, les flux de données de machine learning et les réponses d’API en streaming. Des outils comme l’API d’OpenAI, AWS CloudWatch et Apache Kafka utilisent tous du JSON avec un enregistrement par ligne : ce format allie la lisibilité universelle de JSON à l’efficacité des protocoles de streaming organisés par lignes. Ce guide vous explique comment créer des solutions de streaming JSONL en Node.js et en Python, envoyer des données en temps réel aux navigateurs avec les Server-Sent Events, échanger du JSONL via WebSockets et mettre en place un système de streaming de logs adapté à la production.
Traiter du JSONL en streaming avec Node.js
Node.js repose sur un modèle d’entrées-sorties événementiel et non bloquant, particulièrement adapté au streaming. Les modules intégrés readline et stream offrent tout le nécessaire pour traiter des fichiers JSONL et des flux réseau ligne par ligne, sans charger l’intégralité des données en mémoire.
Associer le module readline à fs.createReadStream est la méthode habituelle pour lire un fichier JSONL en Node.js. Le fichier est lu par blocs, puis restitué sous forme de lignes complètes. La consommation mémoire reste donc stable, même avec des fichiers de plusieurs gigaoctets.
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`);Les flux Transform de Node.js permettent d’assembler des pipelines de données qui lisent du JSONL, filtrent ou enrichissent chaque enregistrement, puis écrivent les résultats. Cette approche gère automatiquement la backpressure : la source est mise en pause lorsque la destination ne peut plus suivre le rythme.
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');Traiter du JSONL en streaming avec Python
Les générateurs Python offrent une solution élégante pour traiter des données JSONL en streaming. Un générateur fournit un enregistrement à la fois et ne passe au suivant que lorsque le consommateur le demande, ce qui réduit au minimum la consommation mémoire. Associés au module intégré json, les générateurs permettent de créer de puissants pipelines de streaming en quelques lignes de code.
Une fonction génératrice Python lit le fichier ligne par ligne à l’aide d’une simple boucle for. Chaque appel à next() lit exactement une ligne, la parse et fournit le résultat. Le fichier reste ouvert et la position de lecture n’avance qu’à mesure que le consommateur demande des enregistrements.
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")Le module itertools de Python permet d’enchaîner des opérations de streaming, comme le filtrage, le regroupement par lots et la sélection de tranches, sans stocker les résultats intermédiaires en mémoire. Chaque étape traite un enregistrement à la fois : vous pouvez ainsi travailler sur des fichiers dont la taille dépasse la RAM disponible.
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']}")Utiliser les Server-Sent Events avec JSONL
Les Server-Sent Events (SSE) offrent un protocole simple, fondé sur HTTP, pour envoyer des mises à jour en temps réel du serveur vers le client. Chaque événement SSE contient un champ data. JSONL convient naturellement à son contenu, puisque chaque ligne est un objet JSON complet que le client peut parser immédiatement. Contrairement aux WebSockets, SSE utilise une connexion HTTP standard, ne nécessite aucune configuration particulière du proxy et rétablit automatiquement la connexion en cas de problème.
Le serveur définit l’en-tête Content-Type sur text/event-stream et écrit chaque enregistrement JSONL dans le champ data d’un événement SSE. La connexion reste ouverte et le serveur envoie les nouveaux événements dès qu’ils sont disponibles.
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'));Le navigateur utilise l’API EventSource pour se connecter à l’endpoint SSE. Chaque événement reçu contient un enregistrement JSONL, parsé et affiché en temps réel. EventSource se charge de rétablir automatiquement la connexion en cas de coupure.
// 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);
});Streaming JSONL avec WebSocket
SSE permet au serveur d’envoyer des données au client, tandis que les WebSockets offrent une communication full-duplex : chaque côté peut envoyer des enregistrements JSONL à tout moment. Ce fonctionnement convient particulièrement aux applications interactives, comme l’édition collaborative, les tableaux de bord en temps réel pilotés par des commandes utilisateur ou la synchronisation bidirectionnelle de données. Chaque message WebSocket contient un seul enregistrement JSONL, ce qui simplifie le parsing des deux côtés.
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' }));Chaque message WebSocket contient un seul objet JSON, selon le principe JSONL d’un enregistrement par message. Le serveur envoie des métriques au client toutes les 500 ms et accepte en parallèle les commandes de celui-ci. La sérialisation JSON est la même dans les deux sens : le protocole est donc symétrique et facile à déboguer.
Le streaming de logs en pratique
La collecte centralisée de logs est l’un des usages les plus courants du streaming JSONL. Les applications écrivent leurs logs structurés sous forme de lignes JSONL dans stdout ou dans un fichier. Un agent de collecte suit cette sortie en temps réel et transmet les enregistrements à un système central. Docker, Kubernetes et la plupart des services cloud de gestion des logs utilisent cette approche.
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();Ce collecteur suit un fichier de logs JSONL en temps réel et transmet chaque enregistrement au gestionnaire correspondant à son niveau de log. Il mémorise la position de lecture pour ne lire que le contenu ajouté après la première lecture de l’existant. Pour un usage en production, vous ajouteriez la détection de la rotation des fichiers, un arrêt propre et l’envoi par lots afin de réduire les appels réseau au système centralisé de gestion des logs.
Essayez nos outils JSONL gratuits
Vous souhaitez examiner ou convertir des données JSONL avant de créer votre pipeline de streaming ? Nos outils en ligne gratuits vous permettent de visualiser, convertir et formater des fichiers JSONL directement dans votre navigateur. Tous les traitements s’effectuent localement : vos données restent privées.
Les stratégies pour traiter des gigaoctets de données JSONL : lecture en streaming, gestion de la mémoire, découpage des fichiers, compression et outils en ligne.
Apprenez à produire des logs structurés au format JSONL et à les intégrer à ELK Stack, Fluentd, CloudWatch, GCP Logging et Azure Monitor, avec des exemples prêts pour la production en Python, Node.js et Go.
Maîtrisez les bonnes pratiques JSONL : mise en forme, cohérence des schémas, gestion des erreurs, optimisation des performances et organisation des fichiers. Des exemples concrets vous aident à éviter les pièges courants.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Apprenez à utiliser le format JSONL en JavaScript et Node.js.