JSONLストリーミング:データをリアルタイムに処理する
JSONLデータをリアルタイムにストリーミング処理するための総合ガイドです。Node.jsのreadline、Pythonのジェネレーター、Server-Sent Events、WebSocketを使ったパイプラインの構築方法と、本番環境でのログストリーミングの実装パターンを解説します。
JSONLがストリーミングに適している理由
JSONL(JSON Lines)は、1行に1つの完全なJSONオブジェクトを記述し、改行文字で区切る形式です。各行がそれだけで完結し、単独でパースできるため、ストリーミングに最適です。単一の大きなJSON配列を扱う場合と違い、データセット全体をメモリに読み込まなくてもレコードの処理を始められます。読み取り側では、1行を読み込んでパースし、必要な処理を済ませてから次の行に進めます。そのため、データソースがどれだけ大きくなっても、メモリ使用量を一定に保てます。
この特性から、JSONLはログ集約システム、リアルタイム分析パイプライン、機械学習向けのデータ配信、APIのストリーミングレスポンスで広く使われています。OpenAIのAPI、AWS CloudWatch、Apache Kafkaなども、改行区切りのJSONを採用しています。JSONの汎用性と読みやすさに、行単位のプロトコルが持つストリーミングの効率性を組み合わせられるためです。このガイドでは、Node.jsとPythonによるJSONLストリーミングの実装、Server-Sent Eventsを使ったブラウザへのリアルタイムデータ配信、WebSocketでのJSONLの送受信、本番運用に対応したログストリーミングシステムの実装を解説します。
Node.jsでJSONLをストリーミング処理する
Node.jsは、イベント駆動のノンブロッキングI/Oモデルを採用しており、ストリーミング処理に非常に適しています。組み込みのreadlineモジュールとstreamモジュールには、データ全体をメモリに読み込まずに、JSONLファイルやネットワークストリームを1行ずつ処理するための機能が揃っています。
Node.jsでJSONLファイルを読み込む定番の方法は、readlineモジュールとfs.createReadStreamを組み合わせることです。ファイルをチャンク単位で読み込み、行が揃ったところで渡してくれるため、数ギガバイトのファイルでもメモリ使用量を一定に保てます。
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`);Node.jsのTransformストリームを使うと、JSONLの読み込み、各レコードのフィルタリングや情報の付加、結果の書き出しといった処理を組み合わせて、データパイプラインを構築できます。バックプレッシャーも自動的に処理され、書き込み先の処理が追いつかなくなると、読み込み元を一時停止します。
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');PythonでJSONLをストリーミング処理する
Pythonのジェネレーターを使うと、JSONLのストリーミング処理をすっきりと実装できます。ジェネレーターは一度に1レコードをyieldし、読み取り側が次の値を要求したときだけ処理を進めるため、メモリ使用量を最小限に抑えられます。組み込みのjsonモジュールと組み合わせれば、わずか数行のコードで高機能なストリーミングパイプラインを構築できます。
Pythonのジェネレーター関数では、通常のforループでファイルを1行ずつ読み込みます。next()が呼ばれるたびに1行だけを読み込み、パースした結果をyieldします。ファイルハンドルは開いたまま維持され、読み取り側がレコードを取得したときだけ読み取り位置が進みます。
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")Pythonのitertoolsを使うと、中間結果をメモリ上にまとめて保持せずに、フィルタリング、バッチ処理、スライスなどのストリーミング操作を組み合わせられます。つないだ各処理が一度に1レコードずつ処理するため、使用可能な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でJSONLを配信する
Server-Sent Events(SSE)は、サーバーからクライアントへ更新情報をリアルタイムにプッシュ配信する、HTTPベースのシンプルなプロトコルです。各SSEイベントにはdataフィールドがあります。JSONLは各行が完全なJSONオブジェクトで、クライアントがすぐにパースできるため、ペイロードの形式として適しています。WebSocketとは異なり、SSEは標準のHTTPで動作し、特別なプロキシ設定は不要です。接続に障害が発生した場合も自動的に再接続します。
サーバーではContent-Typeをtext/event-streamに設定し、各JSONLレコードをSSEのdataフィールドとして書き込みます。接続を開いたまま維持し、新しいイベントが発生するたびにクライアントへプッシュ配信します。
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'));ブラウザではEventSource APIを使ってSSEエンドポイントに接続します。受信する各イベントにはJSONLレコードが含まれており、リアルタイムにパースして画面に反映します。接続が切れた場合の再接続は、EventSourceが自動的に行います。
// 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でJSONLをストリーミングする
SSEがサーバーからクライアントへのプッシュ配信を担うのに対し、WebSocketは全二重通信に対応し、双方がいつでもJSONLレコードを送信できます。共同編集、ユーザーのコマンドを受け付けるリアルタイムダッシュボード、双方向のデータ同期など、対話的なアプリケーションに最適です。各WebSocketメッセージに単一の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' }));各WebSocketメッセージには単一のJSONオブジェクトを格納し、メッセージ単位で1レコードを扱うJSONLの方式に従います。サーバーは500ms間隔でクライアントへメトリクスを配信しながら、クライアントからのコマンドも受け付けます。送受信の両方向で同じJSONのシリアライズ方式を使うため、プロトコルが対称的になり、デバッグもしやすくなります。
ログストリーミングの実践
JSONLストリーミングの代表的な用途の1つが、ログの一元収集です。アプリケーションは構造化ログをJSONL形式の行としてstdoutまたはファイルに書き込み、収集エージェントがその出力への追記をリアルタイムに読み取って、集約先のシステムにレコードを転送します。このパターンは、Docker、Kubernetes、そして大半のクラウドログサービスで使われています。
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();このコレクターは、JSONLログファイルへの追記をリアルタイムに読み取り、ログレベルに応じたハンドラーにレコードを振り分けます。ファイルの読み取り位置を記録しているため、既存の内容を初回に読み込んだ後は、追加された内容だけを読み込みます。本番環境で使う際は、ファイルのローテーション検出とグレースフルシャットダウンに加え、ログ集約システムへのネットワーク呼び出しを減らすためのバッチ転送を追加します。
無料のJSONLツールを試す
ストリーミングパイプラインを構築する前に、JSONLデータを確認したり変換したりするなら、無料のオンラインツールをご利用ください。ブラウザ上でJSONLファイルの表示、変換、整形ができます。処理はすべてローカルで行われるため、データのプライバシーを保てます。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
JSONL 形式による構造化ログの扱い方を解説します。Python、Node.js、Go の本番環境向けサンプルとともに、ELK Stack、Fluentd、CloudWatch、GCP Logging、Azure Monitor との連携方法を紹介します。
整形、スキーマの一貫性、エラーハンドリング、パフォーマンスの最適化、ファイル整理に関する JSONL のベストプラクティスを解説します。実践的な例を通じて、よくある落とし穴を避ける方法を学べます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
JavaScript と Node.js で JSONL ファイルを扱うための完全ガイドです。実践的な例を通じて、JSONL データの読み書き、パース、ストリーミング処理を学べます。