Streaming de JSONL: processe dados em tempo real
Um guia completo sobre streaming de dados JSONL em tempo real. Aprenda a criar pipelines de streaming com readline do Node.js, geradores do Python, Server-Sent Events e WebSockets, além de padrões de streaming de logs em produção.
Por que JSONL é ideal para streaming
JSONL (JSON Lines) armazena um objeto JSON completo por linha, com as linhas separadas por caracteres de quebra de linha. Essa estrutura é ideal para streaming, pois cada linha é uma unidade independente que pode ser interpretada por si só. Ao contrário do que acontece com um único array JSON grande, você não precisa carregar todo o conjunto de dados na memória para começar a processar os registros. O consumidor pode ler uma linha, interpretar seu conteúdo, processá-lo e passar para a próxima, mantendo o uso de memória constante, por mais que a fonte de dados cresça.
É essa característica que faz do JSONL o formato predominante em sistemas de agregação de logs, pipelines de análise em tempo real, feeds de dados para aprendizado de máquina e respostas de APIs em streaming. Ferramentas como a API da OpenAI, o AWS CloudWatch e o Apache Kafka usam JSON delimitado por quebras de linha porque ele combina a legibilidade universal do JSON com a eficiência dos protocolos orientados a linhas para streaming. Neste guia, você vai aprender a criar soluções de streaming de JSONL em Node.js e Python, enviar dados em tempo real para navegadores com Server-Sent Events, trocar registros JSONL via WebSockets e implementar um sistema de streaming de logs pronto para produção.
Streaming de JSONL em Node.js
O Node.js usa um modelo de I/O não bloqueante e orientado a eventos, o que o torna especialmente adequado para cargas de trabalho de streaming. Os módulos nativos readline e stream oferecem tudo de que você precisa para processar arquivos JSONL e streams de rede linha por linha, sem carregar todo o payload na memória.
Combinar o módulo readline com fs.createReadStream é a forma padrão de consumir um arquivo JSONL em Node.js. O arquivo é lido em blocos, e as linhas são emitidas por inteiro. Assim, o uso de memória se mantém estável mesmo com arquivos de vários 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`);Os streams Transform do Node.js permitem criar pipelines de dados com etapas que podem ser combinadas para ler JSONL, filtrar ou enriquecer cada registro e gravar os resultados. Esse padrão trata o backpressure automaticamente, pausando a origem quando o destino não consegue acompanhar o 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 em Python
Os geradores do Python oferecem uma forma elegante de fazer streaming de dados JSONL. Como um gerador fornece um registro por vez e só avança quando o consumidor solicita o próximo valor, o uso de memória se mantém mínimo. Com o módulo nativo json, você pode criar pipelines de streaming poderosos com poucas linhas de código.
Uma função geradora em Python lê o arquivo linha por linha com um loop for comum. Cada chamada a next() lê exatamente uma linha, interpreta seu conteúdo e fornece o resultado. O arquivo permanece aberto, e a posição de leitura só avança à medida que o 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")O itertools do Python permite combinar operações de streaming, como filtragem, agrupamento em lotes e fatiamento, sem materializar os resultados intermediários. Cada etapa da cadeia processa um registro por vez, permitindo trabalhar com arquivos maiores que a RAM disponível.
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 com JSONL
Server-Sent Events (SSE) é um protocolo simples, baseado em HTTP, para enviar atualizações em tempo real do servidor para o cliente. Cada evento SSE contém um campo de dados, e JSONL é uma escolha natural para o payload: cada linha é um objeto JSON completo que o cliente pode interpretar imediatamente. Ao contrário dos WebSockets, SSE funciona com HTTP padrão, dispensa configurações especiais de proxy e restabelece a conexão automaticamente em caso de falha.
O servidor define Content-Type como text/event-stream e escreve cada registro JSONL no campo de dados de um evento SSE. A conexão permanece aberta, e o servidor envia novos eventos assim que ficam disponíveis.
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'));O navegador usa a API EventSource para se conectar ao endpoint SSE. Cada evento recebido contém um registro JSONL, que é interpretado e renderizado em tempo real. Se a conexão cair, o EventSource a restabelece automaticamente.
// 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);
});WebSocket + streaming de JSONL
Enquanto SSE permite enviar dados do servidor para o cliente, WebSockets oferecem comunicação full-duplex, em que os dois lados podem enviar registros JSONL a qualquer momento. Isso é ideal para aplicações interativas, como edição colaborativa, dashboards em tempo real que aceitam comandos do usuário e sincronização bidirecional de dados. Cada mensagem WebSocket contém um único registro JSONL, o que simplifica a interpretação dos dados nas duas pontas.
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 mensagem WebSocket contém um único objeto JSON, seguindo a convenção do JSONL de um registro por mensagem. O servidor envia métricas ao cliente em intervalos de 500ms e, ao mesmo tempo, aceita comandos enviados por ele. As duas direções usam a mesma serialização JSON, o que torna o protocolo simétrico e fácil de depurar.
Streaming de logs na prática
Um dos usos mais comuns do streaming de JSONL na prática é a coleta centralizada de logs. As aplicações escrevem entradas de log estruturadas como linhas JSONL em stdout ou em um arquivo, e um agente coletor acompanha a saída em tempo real, encaminhando os registros para um sistema central. Esse padrão é usado pelo Docker, pelo Kubernetes e pela maioria dos serviços de logs em nuvem.
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 coletor acompanha um arquivo de log JSONL em tempo real e encaminha os registros aos handlers de acordo com o nível de log. Ele mantém a posição de leitura no arquivo para ler apenas o conteúdo novo após a leitura inicial do conteúdo existente. Em produção, você adicionaria detecção de rotação de arquivos, encerramento controlado e envio em lotes para reduzir as chamadas de rede ao sistema centralizado de logs.
Experimente nossas ferramentas gratuitas para JSONL
Quer inspecionar ou converter dados JSONL antes de criar seu pipeline de streaming? Use nossas ferramentas online gratuitas para visualizar, converter e formatar arquivos JSONL diretamente no navegador. Todo o processamento é local, mantendo a privacidade dos seus dados.
Estratégias para processar gigabytes de dados JSONL: leitura por streaming, gerenciamento de memória, divisão de arquivos, compressão e ferramentas online.
Aprenda a gerar logs estruturados no formato JSONL. Integre com ELK Stack, Fluentd, CloudWatch, GCP Logging e Azure Monitor, com exemplos prontos para produção em Python, Node.js e Go.
Domine as boas práticas de JSONL para formatação, consistência de schema, tratamento de erros, otimização de desempenho e organização de arquivos. Evite problemas comuns com exemplos práticos.
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Aprenda a usar o formato JSONL em JavaScript e Node.js.