Streaming de JSONL: procesa datos en tiempo real
Una guía completa sobre el streaming de datos JSONL en tiempo real. Aprende a crear pipelines de streaming con readline de Node.js, generadores de Python, Server-Sent Events y WebSockets, y a aplicar patrones de streaming de logs en producción.
Por qué JSONL es ideal para el streaming
JSONL (JSON Lines) almacena un objeto JSON completo por línea y separa los objetos mediante saltos de línea. Esta estructura lo convierte en un formato ideal para el streaming: cada línea es una unidad independiente que se puede parsear por sí sola. A diferencia de lo que ocurre con un único array JSON de gran tamaño, no necesitas cargar todo el conjunto de datos en memoria para empezar a procesar los registros. Un consumidor puede leer una línea, parsearla, procesarla y pasar a la siguiente. Así, el uso de memoria se mantiene constante, por mucho que crezca la fuente de datos.
Por eso JSONL predomina en los sistemas de agregación de logs, los pipelines de análisis en tiempo real, los flujos de datos para aprendizaje automático y las respuestas de API en streaming. Herramientas como la API de OpenAI, AWS CloudWatch y Apache Kafka utilizan JSON delimitado por saltos de línea porque combina la facilidad de lectura de JSON con la eficiencia de los protocolos orientados a líneas para el streaming. En esta guía aprenderás a crear soluciones de streaming de JSONL en Node.js y Python, enviar datos en tiempo real a los navegadores mediante Server-Sent Events, intercambiar JSONL a través de WebSockets e implementar un sistema de streaming de logs listo para producción.
Streaming de JSONL en Node.js
Node.js se basa en un modelo de E/S no bloqueante y orientado a eventos, especialmente adecuado para el procesamiento en streaming. Sus módulos nativos readline y stream te ofrecen todo lo necesario para procesar archivos JSONL y flujos de datos de red línea a línea, sin cargar todo el contenido en memoria.
La combinación del módulo readline con fs.createReadStream es la forma habitual de leer un archivo JSONL en Node.js. El archivo se lee por bloques y se emiten líneas completas, de modo que el uso de memoria se mantiene constante incluso con archivos de varios 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`);Los streams Transform de Node.js te permiten crear pipelines de datos a partir de componentes combinables que leen JSONL, filtran o enriquecen cada registro y escriben los resultados. Este patrón gestiona automáticamente la contrapresión (backpressure): pausa el origen cuando el destino no puede seguir el ritmo.
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');Streaming de JSONL en Python
Los generadores de Python ofrecen una forma elegante de procesar datos JSONL en streaming. Como entregan un registro cada vez y solo avanzan cuando el consumidor solicita el siguiente valor, el uso de memoria se mantiene al mínimo. Con los generadores y el módulo nativo json puedes crear potentes pipelines de streaming con unas pocas líneas de código.
Una función generadora de Python lee el archivo línea a línea con un bucle for convencional. Cada llamada a next() lee exactamente una línea, la parsea y entrega el resultado. El archivo permanece abierto y la posición de lectura solo avanza a medida que el consumidor solicita registros.
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")El módulo itertools de Python te permite combinar operaciones de streaming, como filtrar, agrupar por lotes y seleccionar rangos, sin materializar resultados intermedios. Cada paso de la cadena procesa un registro cada vez, por lo que puedes trabajar con archivos que superan 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']}")Server-Sent Events con JSONL
Server-Sent Events (SSE) ofrece un protocolo sencillo basado en HTTP para enviar actualizaciones en tiempo real del servidor al cliente. Cada evento SSE incluye un campo de datos, y JSONL encaja de forma natural como formato del contenido: cada línea es un objeto JSON completo que el cliente puede parsear de inmediato. A diferencia de WebSockets, SSE utiliza HTTP estándar, no requiere una configuración especial del proxy y restablece la conexión automáticamente si se produce un fallo.
El servidor establece Content-Type en text/event-stream y escribe cada registro JSONL en el campo de datos de un evento SSE. La conexión permanece abierta y el servidor envía nuevos eventos a medida que están 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'));El navegador utiliza la API EventSource para conectarse al endpoint SSE. Cada evento recibido contiene un registro JSONL que se parsea y se muestra en tiempo real. Si se interrumpe la conexión, EventSource se encarga de restablecerla automáticamente.
// 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 de JSONL con WebSocket
SSE permite enviar datos del servidor al cliente; WebSockets ofrece comunicación full-duplex, en la que ambos extremos pueden enviar registros JSONL en cualquier momento. Esto resulta ideal para aplicaciones interactivas, como la edición colaborativa, los paneles en tiempo real que admiten comandos del usuario y la sincronización bidireccional de datos. Cada mensaje WebSocket contiene un único registro JSONL, lo que facilita el parseo en ambos extremos.
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' }));Cada mensaje WebSocket contiene un único objeto JSON, siguiendo la convención de JSONL de un registro por mensaje. El servidor envía métricas al cliente a intervalos de 500ms y, al mismo tiempo, acepta comandos del cliente. En ambas direcciones se utiliza la misma serialización JSON, de modo que el protocolo es simétrico y fácil de depurar.
Streaming de logs en la práctica
Uno de los usos más habituales del streaming de JSONL es la recopilación centralizada de logs. Las aplicaciones escriben entradas de log estructuradas como líneas JSONL en stdout o en un archivo. Un agente recolector sigue la salida en tiempo real y reenvía los registros a un sistema central. Docker, Kubernetes y la mayoría de los servicios de logs en la nube utilizan este patrón.
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();Este recolector sigue un archivo de logs JSONL en tiempo real y envía cada registro al manejador correspondiente según su nivel de log. Guarda la posición de lectura del archivo para leer solo el contenido nuevo después de la lectura inicial del contenido existente. En producción, añadirías detección de rotación de archivos, un cierre ordenado y envío por lotes para reducir las llamadas de red al sistema centralizado de logs.
Prueba nuestras herramientas gratuitas de JSONL
¿Quieres inspeccionar o convertir datos JSONL antes de crear tu pipeline de streaming? Usa nuestras herramientas gratuitas en línea para ver, convertir y formatear archivos JSONL directamente en tu navegador. Todo se procesa localmente, por lo que tus datos se mantienen privados.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Aprende a generar logs estructurados en formato JSONL y a integrarlos con ELK Stack, Fluentd, CloudWatch, GCP Logging y Azure Monitor, con ejemplos listos para producción en Python, Node.js y Go.
Domina las buenas prácticas de JSONL: formato, coherencia del esquema, gestión de errores, optimización del rendimiento y organización de archivos. Evita los errores habituales con ejemplos prácticos.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Aprende a usar el formato JSONL en JavaScript y Node.js.