JSONL による構造化ログ
JSONL(JSON Lines)形式で構造化ログを出力するための実践ガイドです。本番環境で使えるコード例を通じて、ELK Stack、Fluentd、CloudWatch、GCP Logging、Azure Monitor との連携方法を解説します。
構造化ログに JSONL を使う理由
従来のプレーンテキストのログは人間には読めますが、プログラムで確実にパースするのはほぼ不可能です。「2024-01-15 ERROR User login failed for admin」のような行では、ログレベル、イベントの種類、ユーザー名が、構造を持たない文字列の中に埋もれています。どのログ集約ツールも、情報を取り出すには変更に弱い正規表現に頼るしかなく、ログ形式が変わるとパイプラインが機能しなくなります。
構造化ログでは、各ログエントリを、明確に定義したフィールドを持つ JSON オブジェクトとして出力することで、この問題を解決します。JSONL(JSON Lines)はこの仕組みをさらに進め、1行に1つの JSON オブジェクトを記述します。全体を配列で囲む必要も、末尾にカンマを付ける必要もありません。そのため、JSONL のログは追記しやすく、ストリーミング処理にも適しており、主要なログプラットフォームならどれでも簡単にパースできます。このガイドでは、Python、Node.js、Go で JSONL のログを出力する方法と、ELK、Fluentd、3大クラウドプロバイダーに転送する方法を解説します。
CSV や XML などの構造化形式と比べて、JSONL は柔軟性、対応ツールの充実度、人間にとっての読みやすさのバランスに優れています。フィールドをネストでき、データの型も保持されるうえ、あらかじめ固定のスキーマを定義する必要もありません。こうした理由から、JSONL は現在のインフラで構造化ログの事実上の標準となっています。
言語別のログライブラリ
最近のログライブラリの多くは、標準機能として、あるいは簡単な設定変更だけで、構造化された JSON を出力できます。ここでは、Python、Node.js、Go 向けのおすすめのライブラリを紹介します。いずれも JSONL と互換性のある形式で出力できます。
Python:structlog
推奨structlog は、Python を代表する構造化ログライブラリです。標準の logging モジュールをラップし、デフォルトで JSON を出力します。プロセッサーパイプラインを使うと、シリアライズする前にログエントリへの情報の付加、フィルタリング、変換を行えます。
import structlog
# Configure structlog for JSONL output
structlog.configure(
processors=[
structlog.processors.TimeStamper(fmt="iso"),
structlog.processors.add_log_level,
structlog.processors.StackInfoRenderer(),
structlog.processors.JSONRenderer(),
],
wrapper_class=structlog.BoundLogger,
context_class=dict,
logger_factory=structlog.PrintLoggerFactory(),
)
log = structlog.get_logger()
# Each call produces one JSONL line
log.info("user.login", user_id="u-42", ip="10.0.0.1")
# {"event":"user.login","user_id":"u-42","ip":"10.0.0.1","level":"info","timestamp":"2026-02-15T08:30:00Z"}
log.error("db.connection_failed", host="db-primary", retries=3)
# {"event":"db.connection_failed","host":"db-primary","retries":3,"level":"error","timestamp":"2026-02-15T08:30:01Z"}Node.js:pino
最速pino は Node.js 向けの最速のロガーで、設定しなくてもデフォルトで JSONL を出力します。非同期の書き込みと、シリアライズ時の処理を最小限に抑える設計により、低いオーバーヘッドを実現しています。ローカルでの開発には、ログを読みやすく整形して出力する関連パッケージの pino-pretty が使えます。
import pino from 'pino';
// pino outputs JSONL by default
const log = pino({
level: 'info',
timestamp: pino.stdTimeFunctions.isoTime,
});
// Each call produces one JSONL line
log.info({ userId: 'u-42', ip: '10.0.0.1' }, 'user.login');
// {"level":30,"time":"2026-02-15T08:30:00.000Z","userId":"u-42","ip":"10.0.0.1","msg":"user.login"}
log.error({ host: 'db-primary', retries: 3 }, 'db.connection_failed');
// {"level":50,"time":"2026-02-15T08:30:01.000Z","host":"db-primary","retries":3,"msg":"db.connection_failed"}
// Child loggers inherit context
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');Go:zerolog
ゼロアロケーションzerolog は、スループットの高いサービスで最大限のパフォーマンスを発揮するよう設計された、Go 向けのゼロアロケーション JSON ロガーです。中間処理でメモリを確保せず、io.Writer に直接書き込むため、低レイテンシが求められるアプリケーションに最適です。メソッドチェーン形式の API で、使いやすさと効率を両立しています。
package main
import (
"os"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func main() {
// Configure JSONL output to stdout
zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()
// Each call produces one JSONL line
log.Info().
Str("user_id", "u-42").
Str("ip", "10.0.0.1").
Msg("user.login")
// {"level":"info","user_id":"u-42","ip":"10.0.0.1","time":1739608200,"message":"user.login"}
log.Error().
Str("host", "db-primary").
Int("retries", 3).
Msg("db.connection_failed")
}ELK Stack との連携
ELK Stack(Elasticsearch、Logstash、Kibana)は、最も広く導入されているオープンソースのログ管理プラットフォームです。Logstash と Filebeat は標準で JSON をパースできるため、JSONL のログをスムーズに取り込めます。複雑な grok パターンを用意する必要はありません。
Filebeat は、JSONL ログファイルへの追記を監視し、Logstash や Elasticsearch に転送する軽量なログ転送ツールです。json.keys_under_root を true に設定すると、JSON の各フィールドが Elasticsearch のトップレベルのフィールドとして扱われ、Kibana から直接検索できるようになります。
# filebeat.yml
filebeat.inputs:
- type: log
enabled: true
paths:
- /var/log/app/*.jsonl
json.keys_under_root: true
json.add_error_key: true
json.message_key: message
json.overwrite_keys: true
output.elasticsearch:
hosts: ["http://elasticsearch:9200"]
index: "app-logs-%{+yyyy.MM.dd}"
# Optional: send to Logstash instead
# output.logstash:
# hosts: ["logstash:5044"]インデックスに登録する前にログを変換したり、情報を付加したりする場合は、Filebeat と Elasticsearch の間に Logstash を配置します。json コーデックが JSONL の各行を自動でパースします。mutate フィルターを使えば、保存前にフィールド名を変更したり、タグを追加したり、機密データを削除したりできます。
# logstash.conf
input {
beats {
port => 5044
codec => json
}
}
filter {
# Parse timestamp from the JSON field
date {
match => ["timestamp", "ISO8601"]
target => "@timestamp"
}
# Add environment tag
mutate {
add_field => { "environment" => "production" }
remove_field => ["agent", "ecs", "host"]
}
# Route by log level
if [level] == "error" or [level] == "fatal" {
mutate { add_tag => ["alert"] }
}
}
output {
elasticsearch {
hosts => ["http://elasticsearch:9200"]
index => "app-logs-%{+YYYY.MM.dd}"
}
}Fluentd と Fluent Bit
Fluentd とその軽量版である Fluent Bit は、いずれも CNCF の Graduated プロジェクトで、Kubernetes 環境で広く使われています。どちらも標準で JSONL のログを扱え、Elasticsearch、S3、クラウドネイティブなログサービスなど、ほぼあらゆる転送先に対応しています。
Fluent Bit は、Kubernetes やリソースに制約のある環境で推奨されるログコレクターです。メモリ使用量は約 450KB で、毎秒数十万件のレコードを処理できます。json パーサーを使えば、独自の設定を追加せずに JSONL を取り込めます。
[SERVICE]
Flush 5
Daemon Off
Log_Level info
Parsers_File parsers.conf
[INPUT]
Name tail
Path /var/log/app/*.jsonl
Parser json
Tag app.*
Refresh_Interval 5
[FILTER]
Name modify
Match app.*
Add cluster production-us-east-1
Add service my-api
[OUTPUT]
Name es
Match app.*
Host elasticsearch
Port 9200
Index app-logs
Type _doc
Logstash_Format OnFluentd は Fluent Bit よりもプラグインが充実しており、コミュニティが提供するプラグインは 500 を超えます。高度なルーティング、バッファリング、データ変換が必要な場合に適しています。in_tail プラグインで format json を指定すれば、JSONL ファイルをそのまま読み込めます。
# fluentd.conf
<source>
@type tail
path /var/log/app/*.jsonl
pos_file /var/log/fluentd/app.pos
tag app.logs
<parse>
@type json
time_key timestamp
time_format %Y-%m-%dT%H:%M:%S%z
</parse>
</source>
<filter app.logs>
@type record_transformer
<record>
hostname "#{Socket.gethostname}"
environment production
</record>
</filter>
<match app.logs>
@type elasticsearch
host elasticsearch
port 9200
index_name app-logs
logstash_format true
<buffer>
@type memory
flush_interval 5s
chunk_limit_size 5m
</buffer>
</match>クラウドのログ管理サービス
3大クラウドプロバイダーはいずれも JSONL 形式のログを受け付け、JSON の各フィールドを自動でパースして、検索やフィルタリングに使える属性として扱います。ログ基盤を自前で運用せずに、同等の構造化データのクエリ機能を利用できます。
AWS CloudWatch Logs
AWSCloudWatch Logs は JSON のログエントリを自動でパースし、すべてのフィールドを CloudWatch Logs Insights でクエリできるようにします。ECS、Lambda、または CloudWatch エージェントを導入した EC2 上でアプリケーションを実行していれば、JSONL 出力は追加設定なしで構造化データとしてインデックスに登録されます。Logs Insights の SQL に似た構文を使うと、数百万件のログエントリを数秒で検索できます。
# CloudWatch Logs Insights query examples
# Find all errors in the last hour
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100
# Aggregate error counts by event type
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc
# P99 latency by endpoint
fields path, duration_ms
| filter ispresent(duration_ms)
| stats pct(duration_ms, 99) as p99 by path
| sort p99 descGCP Cloud Logging
GCPGoogle Cloud Logging(旧 Stackdriver)は、JSON ペイロードを構造化ログエントリとして標準で扱えます。Cloud Run、GKE、Cloud Functions で JSONL を stdout に出力すると、ログエージェントが各行をパースして構造化された LogEntry に変換します。severity フィールドは Cloud Logging の重大度レベルに直接対応し、jsonPayload の各フィールドはインデックスに登録され、検索できるようになります。
# Python example for Cloud Run / Cloud Functions
import json
import sys
def log(severity: str, message: str, **fields):
"""Write a JSONL log entry compatible with GCP Cloud Logging."""
entry = {
"severity": severity.upper(), # Maps to Cloud Logging severity
"message": message,
**fields,
}
print(json.dumps(entry), file=sys.stdout, flush=True)
# GCP automatically parses these as structured logs
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)
# Query in Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERRORAzure Monitor Logs
AzureAzure Monitor は、Azure Monitor Agent または API 経由の直接送信で JSONL のログを取り込みます。Application Insights は JSON 形式のトレースとカスタムイベントを自動でパースします。KQL(Kusto Query Language)では、構造化ログデータに対して高度なクエリを実行でき、集計、時系列分析、異常検知にも対応しています。
// KQL queries for JSONL logs in Azure Monitor
// Find recent errors
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| project TimeGenerated, parsed.event, parsed.user_id,
parsed.error_message
| order by TimeGenerated desc
| take 100
// Error rate over time (5-minute buckets)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart
// Top error events
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by CountJSONL ログのベストプラクティス
すべてのサービスで規約を統一すると、JSONL のログをクエリしたり、ログ同士を関連付けたり、アラートを設定したりしやすくなります。ここでは、毎日数十億件のログエントリを処理する本番システムでの知見に基づくベストプラクティスを紹介します。
ログレベルを統一する
標準的なログレベルの体系を採用し、すべてのサービスで使い方を統一します。一般的には、開発時の診断情報に DEBUG、通常の動作に INFO、回復可能な問題に WARN、対処が必要な障害に ERROR、回復不能なクラッシュに FATAL という5つのレベルを使います。pino の 10-60 のような数値のレベルは、ログを取り込む際にこれらの文字列にマッピングすると、共通の条件でクエリできます。
{"level":"debug","event":"cache.miss","key":"user:42","timestamp":"2026-02-15T08:30:00Z"}
{"level":"info","event":"request.completed","method":"GET","path":"/api/users","status":200,"duration_ms":45,"timestamp":"2026-02-15T08:30:01Z"}
{"level":"warn","event":"rate_limit.approaching","client_id":"c-99","current":950,"limit":1000,"timestamp":"2026-02-15T08:30:02Z"}
{"level":"error","event":"payment.failed","order_id":"ord-123","error":"card_declined","timestamp":"2026-02-15T08:30:03Z"}
{"level":"fatal","event":"startup.failed","reason":"missing DATABASE_URL","timestamp":"2026-02-15T08:30:04Z"}フィールド名を統一する
すべてのサービスで使う共通フィールドのスキーマを定義します。フィールド名は snake_case、タイムスタンプは ISO 8601 に統一し、ログ同士を関連付ける識別子にも共通の命名規則を使います。どのログエントリにも、少なくとも timestamp、level、event(プログラムで処理できるイベント名)、service を含めます。リクエストに紐づくログエントリには、追跡できるよう request_id と user_id も含めます。
// Recommended field schema
{
"timestamp": "2026-02-15T08:30:00.000Z", // ISO 8601, always UTC
"level": "info", // debug|info|warn|error|fatal
"event": "order.created", // dot-notation event name
"service": "order-api", // emitting service
"version": "1.4.2", // service version
"request_id": "req-abc-123", // correlation ID
"trace_id": "4bf92f3577b34da6", // distributed trace ID
"user_id": "u-42", // authenticated user
"duration_ms": 120, // numeric, not string
"order_id": "ord-789", // domain-specific context
"items_count": 3 // domain-specific context
}パフォーマンス上の注意点
構造化ログでは、ログを出力するたびにシリアライズのオーバーヘッドが発生します。スループットの高いサービスでは、この負荷が無視できなくなることがあります。pino や zerolog による非同期ログ出力を使い、頻繁に実行される処理からシリアライズを切り離します。INFO レベルでは、大きなオブジェクトやリクエスト・レスポンスのボディを記録しないようにします。大量のデバッグログにはサンプリングを使います。ログをネットワーク経由で同期的に送信するのではなく、ローカルファイルに書き込み、転送はサイドカー(Filebeat、Fluent Bit)に任せます。
非同期ロガー(pino、zerolog)を使い、JSON のシリアライズでメインスレッドをブロックしないようにします。
INFO レベルでは、リクエストやレスポンスのボディ全体を記録しないでください。記録する場合は DEBUG レベルを使い、トラブルシューティング時にだけ有効にします。
大量に発生するイベントにはサンプリングを使います。ヘルスチェックのリクエストは全件を記録せず、100 件に 1 件を記録します。
ログはローカルファイルに書き込み、Filebeat や Fluent Bit で非同期に転送します。ログ出力の処理内では、同期的なネットワーク通信を避けます。
ログの各行の最大サイズ(例:16KB)を設定し、大きすぎるエントリでパイプラインが詰まるのを防ぎます。
logrotate やライブラリ組み込みのローテーション機能でログファイルをローテーションし、ディスク容量の枯渇を防ぎます。
JSONL のログをオンラインで検証
無料のブラウザツールで、JSONL ログファイルの確認、検証、変換ができます。ファイルのアップロードは不要で、処理はすべてローカルで行われます。
Node.jsとPythonでJSONLデータをストリーミングする方法を学びます。SSE、WebSocket、リアルタイムログ処理をカバー。
ギガバイト規模の JSONL データを処理する方法を紹介します。ストリーミングでの読み込み、メモリ管理、ファイル分割、圧縮、オンラインツールを取り上げます。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
JSONL ファイルに適切なインデントを付けて、読みやすく整形できます。デバッグやデータのレビューがしやすくなります。
.jsonl や .ndjson ファイルを、エディタ内で高速に操作・検索できるテーブルとして開けます。スクロールして確認するには大きすぎるファイルや、書き込みが続いているログを扱うための拡張機能です。