著者: Jerry Fan

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 を出力します。プロセッサーパイプラインを使うと、シリアライズする前にログエントリへの情報の付加、フィルタリング、変換を行えます。

Python:structlog
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 が使えます。

Node.js:pino
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 で、使いやすさと効率を両立しています。

Go:zerolog
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 の設定
# 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 のパイプライン
# 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 を取り込めます。

Fluent Bit の設定
[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 On

Fluentd は Fluent Bit よりもプラグインが充実しており、コミュニティが提供するプラグインは 500 を超えます。高度なルーティング、バッファリング、データ変換が必要な場合に適しています。in_tail プラグインで format json を指定すれば、JSONL ファイルをそのまま読み込めます。

Fluentd の設定
# 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

AWS

CloudWatch Logs は JSON のログエントリを自動でパースし、すべてのフィールドを CloudWatch Logs Insights でクエリできるようにします。ECS、Lambda、または CloudWatch エージェントを導入した EC2 上でアプリケーションを実行していれば、JSONL 出力は追加設定なしで構造化データとしてインデックスに登録されます。Logs Insights の SQL に似た構文を使うと、数百万件のログエントリを数秒で検索できます。

AWS CloudWatch Logs
# 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 desc

GCP Cloud Logging

GCP

Google Cloud Logging(旧 Stackdriver)は、JSON ペイロードを構造化ログエントリとして標準で扱えます。Cloud Run、GKE、Cloud Functions で JSONL を stdout に出力すると、ログエージェントが各行をパースして構造化された LogEntry に変換します。severity フィールドは Cloud Logging の重大度レベルに直接対応し、jsonPayload の各フィールドはインデックスに登録され、検索できるようになります。

GCP Cloud Logging
# 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 >= ERROR

Azure Monitor Logs

Azure

Azure Monitor は、Azure Monitor Agent または API 経由の直接送信で JSONL のログを取り込みます。Application Insights は JSON 形式のトレースとカスタムイベントを自動でパースします。KQL(Kusto Query Language)では、構造化ログデータに対して高度なクエリを実行でき、集計、時系列分析、異常検知にも対応しています。

Azure Monitor Logs
// 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 Count

JSONL ログのベストプラクティス

すべてのサービスで規約を統一すると、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 のログを確認

最大 1GB の JSONL ログファイルを表示、検索、検証できます。すぐに読み込めて、処理はすべてクライアント側で完結。プライバシーは 100% 守られます。

よくある質問

参考資料