Por Jerry Fan

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.

Lectura en streaming con 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`);

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.

Pipelines con streams Transform
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.

Streaming con generadores
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.

Procesamiento en cadena con 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 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.

Servidor 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'));

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.

Cliente SSE (navegador)
// 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.

Servidor WebSocket con mensajes 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' }));

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.

Recolector de logs JSONL en tiempo real
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.

Trabaja con archivos JSONL en línea

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin subir archivos y con un procesamiento 100% privado.

Preguntas frecuentes

Referencias