Gestructureerde logging met JSONL
Een uitgebreide handleiding voor gestructureerde logging in JSONL-formaat (JSON Lines). Leer hoe je logs koppelt aan de ELK Stack, Fluentd, CloudWatch, GCP Logging en Azure Monitor, met codevoorbeelden die je in productie kunt gebruiken.
Waarom gestructureerde logging met JSONL?
Traditionele logs in platte tekst zijn goed leesbaar voor mensen, maar voor machines bijna onmogelijk om betrouwbaar te parsen. In een regel als '2024-01-15 ERROR User login failed for admin' zitten het logniveau, het eventtype en de gebruikersnaam verstopt in een ongestructureerde string. Elke tool voor logaggregatie is daardoor aangewezen op kwetsbare reguliere expressies om de informatie eruit te halen. Elke wijziging in het logformaat laat de pipeline vastlopen.
Gestructureerde logging lost dit op door elke logregel als een JSON-object met duidelijk gedefinieerde velden weg te schrijven. JSONL (JSON Lines) gaat nog een stap verder: één JSON-object per regel, zonder een array eromheen of afsluitende komma’s. Daardoor kun je eenvoudig nieuwe regels aan JSONL-logs toevoegen, ze streamen en ze met elk groot logplatform parsen. In deze handleiding leer je hoe je JSONL-logs genereert in Python, Node.js en Go, en hoe je ze doorstuurt naar ELK, Fluentd en de drie grote cloudproviders.
Vergeleken met andere gestructureerde formaten, zoals CSV en XML, biedt JSONL de beste balans tussen flexibiliteit, ondersteuning door tools en leesbaarheid voor mensen. Je kunt velden nesten, datatypes blijven behouden en je hoeft nooit vooraf een vast schema te definiëren. Daarom is JSONL de de facto standaard geworden voor gestructureerde logging in moderne infrastructuur.
Logginglibraries per taal
De meeste moderne logginglibraries ondersteunen gestructureerde JSON-output standaard of na een eenvoudige configuratiewijziging. Hieronder vind je de aanbevolen libraries voor Python, Node.js en Go. Ze leveren allemaal output die compatibel is met JSONL.
Python: structlog
Aanbevolenstructlog is de toonaangevende library voor gestructureerde logging in Python. De library bouwt voort op de standaardmodule logging en levert standaard JSON-output. Met de processorpipeline kun je logregels verrijken, filteren en transformeren voordat ze worden geserialiseerd.
import structlog
# Configureer structlog voor 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()
# Elke aanroep produceert één JSONL-regel
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
Snelstepino is de snelste logger voor Node.js en levert standaard JSONL-output, zonder dat je iets hoeft te configureren. Door asynchroon te schrijven en de serialisatie tot een minimum te beperken, blijft de overhead laag. Het bijbehorende pakket pino-pretty maakt de output goed leesbaar voor lokale ontwikkeling.
import pino from 'pino';
// pino geeft standaard JSONL uit
const log = pino({
level: 'info',
timestamp: pino.stdTimeFunctions.isoTime,
});
// Elke aanroep produceert één JSONL-regel
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 erven context
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');Go: zerolog
Zonder geheugenallocatieszerolog is een JSON-logger voor Go die geen geheugen alloceert en is ontworpen voor maximale prestaties in services die veel data verwerken. De logger schrijft rechtstreeks naar een io.Writer, zonder tussentijdse allocaties. Dat maakt zerolog ideaal voor applicaties waarin een lage latency belangrijk is. Met de API kun je aanroepen aan elkaar koppelen; dat werkt prettig en efficiënt.
package main
import (
"os"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func main() {
// Configureer JSONL-output naar stdout
zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()
// Elke aanroep produceert één JSONL-regel
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")
}Integratie met de ELK Stack
De ELK Stack (Elasticsearch, Logstash, Kibana) is het meest gebruikte opensourceplatform voor logbeheer. JSONL-logs sluiten hier naadloos op aan: Logstash en Filebeat kunnen standaard JSON parsen, waardoor je geen complexe grok-patronen nodig hebt.
Filebeat is een lichtgewicht log shipper die nieuwe regels in je JSONL-logbestanden volgt en doorstuurt naar Logstash of Elasticsearch. Als je json.keys_under_root op true zet, komen de JSON-velden op het hoogste niveau in Elasticsearch te staan. Je kunt ze dan direct doorzoeken in 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}"
# Optioneel: verstuur naar Logstash in plaats daarvan
# output.logstash:
# hosts: ["logstash:5044"]Wil je logs transformeren of verrijken voordat je ze indexeert, plaats dan Logstash tussen Filebeat en Elasticsearch. De json-codec parst elke JSONL-regel automatisch. Met het mutate-filter kun je velden hernoemen, tags toevoegen of gevoelige gegevens verwijderen voordat je de logs opslaat.
# logstash.conf
input {
beats {
port => 5044
codec => json
}
}
filter {
# Parseer timestamp uit het JSON-veld
date {
match => ["timestamp", "ISO8601"]
target => "@timestamp"
}
# Voeg omgevingstag toe
mutate {
add_field => { "environment" => "production" }
remove_field => ["agent", "ecs", "host"]
}
# Routeer op logniveau
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 en de lichtere variant Fluent Bit hebben allebei de graduated-status binnen de CNCF en worden veel gebruikt in Kubernetes-omgevingen. Beide ondersteunen JSONL-logs standaard en kunnen ze naar vrijwel elke bestemming doorsturen, van Elasticsearch en S3 tot cloud-native logdiensten.
Fluent Bit is de logcollector bij uitstek voor Kubernetes en omgevingen met beperkte systeemresources. De collector gebruikt ongeveer 450KB geheugen en kan honderdduizenden records per seconde verwerken. De json-parser kan JSONL-invoer verwerken zonder dat je daarvoor een specifieke configuratie nodig hebt.
[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 heeft een uitgebreider ecosysteem van plugins dan Fluent Bit, met meer dan 500 plugins uit de community. Gebruik Fluentd als je geavanceerde routering, buffering of transformaties nodig hebt. De in_tail-plugin leest JSONL-bestanden standaard met format json.
# 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>Logplatforms in de cloud
Alle drie de grote cloudproviders accepteren logs in JSONL-formaat en zetten JSON-velden automatisch om in attributen waarop je kunt zoeken en filteren. Zo hoef je geen eigen loginfrastructuur te beheren en houd je dezelfde mogelijkheden om gestructureerde queries uit te voeren.
AWS CloudWatch Logs
AWSCloudWatch Logs parst JSON-logregels automatisch, zodat je elk veld kunt bevragen met CloudWatch Logs Insights. Draait je applicatie op ECS, Lambda of EC2 met de CloudWatch-agent, dan wordt JSONL-output zonder extra configuratie geïndexeerd als gestructureerde data. Met de SQL-achtige syntaxis van Logs Insights doorzoek je miljoenen logregels in enkele seconden.
# CloudWatch Logs Insights queryvoorbeelden
# Zoek alle fouten in het afgelopen uur
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100
# Aggregeer foutaantallen per eventtype
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc
# P99 latentie per 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 (voorheen Stackdriver) biedt volwaardige ondersteuning voor JSON-payloads als gestructureerde logregels. Schrijf je JSONL naar stdout op Cloud Run, GKE of Cloud Functions, dan zet de logging-agent elke regel om in een gestructureerd LogEntry-object. Het veld severity komt rechtstreeks overeen met de logniveaus van Cloud Logging. De velden in jsonPayload worden geïndexeerd en zijn doorzoekbaar.
# Python-voorbeeld voor Cloud Run / Cloud Functions
import json
import sys
def log(severity: str, message: str, **fields):
"""Schrijf een JSONL-logvermelding compatibel met GCP Cloud Logging."""
entry = {
"severity": severity.upper(), # Mapt naar Cloud Logging-ernst
"message": message,
**fields,
}
print(json.dumps(entry), file=sys.stdout, flush=True)
# GCP parst deze automatisch als gestructureerde 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 leest JSONL-logs in via de Azure Monitor Agent of rechtstreeks via de API. Application Insights parst JSON-traces en custom events automatisch. Met KQL (Kusto Query Language) kun je krachtige queries uitvoeren op gestructureerde logdata, met ondersteuning voor aggregatie, tijdreeksanalyse en anomaliedetectie.
// KQL-queries voor JSONL-logs in Azure Monitor
// Zoek recente fouten
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
// Foutenpercentage over tijd (5-minuten buckets)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart
// Top foutevents
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by CountBest practices voor JSONL-logging
Als je in al je services dezelfde conventies volgt, kun je JSONL-logs eenvoudiger bevragen, met elkaar in verband brengen en gebruiken om alerts in te stellen. Deze best practices komen uit productiesystemen die miljarden logregels per dag verwerken.
Gebruik consistente logniveaus
Kies een standaardschaal voor logniveaus en pas die in alle services consequent toe. De gangbaarste conventie kent vijf niveaus: DEBUG voor diagnostiek tijdens het ontwikkelen, INFO voor de normale werking, WARN voor herstelbare problemen, ERROR voor fouten die aandacht vereisen en FATAL voor onherstelbare crashes. Zet numerieke niveaus (zoals de schaal van 10-60 in pino) bij het inlezen om naar deze namen, zodat je overal dezelfde queries kunt gebruiken.
{"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"}Standaardiseer veldnamen
Definieer een gedeeld schema voor velden die in al je services terugkomen. Gebruik snake_case voor veldnamen, ISO 8601 voor timestamps en een vaste naamgeving voor correlatie-ID’s. Elke logregel moet minimaal timestamp, level, event (een machineleesbare eventnaam) en service bevatten. Neem bij logregels die bij een request horen ook request_id en user_id op voor tracing.
// Aanbevolen veldschema
{
"timestamp": "2026-02-15T08:30:00.000Z", // ISO 8601, altijd UTC
"level": "info", // debug|info|warn|error|fatal
"event": "order.created", // punt-notatie eventnaam
"service": "order-api", // uitzendende service
"version": "1.4.2", // serviceversie
"request_id": "req-abc-123", // correlatie-ID
"trace_id": "4bf92f3577b34da6", // gedistribueerde trace-ID
"user_id": "u-42", // geauthenticeerde gebruiker
"duration_ms": 120, // numeriek, geen string
"order_id": "ord-789", // domein-specifieke context
"items_count": 3 // domein-specifieke context
}Aandachtspunten voor prestaties
Gestructureerde logging brengt bij elke logaanroep overhead door serialisatie met zich mee. In services die veel data verwerken, kan die flink oplopen. Gebruik asynchrone logging (pino, zerolog) om serialisatie buiten het kritieke uitvoeringspad te houden. Log geen grote objecten of request- en responsebodies op INFO-niveau. Gebruik sampling als je veel debuglogs genereert. Schrijf logs naar lokale bestanden en laat een sidecar (Filebeat, Fluent Bit) ze doorsturen, in plaats van ze synchroon over het netwerk te verzenden.
Gebruik asynchrone loggers (pino, zerolog) om te voorkomen dat JSON-serialisatie de hoofdthread blokkeert.
Log nooit volledige request- of responsebodies op INFO-niveau. Gebruik daarvoor DEBUG-niveau en schakel dat alleen in als je problemen onderzoekt.
Gebruik sampling voor events die vaak voorkomen. Log bijvoorbeeld 1 op de 100 healthcheckrequests in plaats van elk request.
Schrijf logs naar lokale bestanden en stuur ze asynchroon door met Filebeat of Fluent Bit. Vermijd synchrone netwerkaanroepen tijdens het loggen.
Stel een maximale grootte voor logregels in (bijv. 16KB), zodat te grote regels de pipeline niet verstoppen.
Roteer logbestanden met logrotate of de ingebouwde logrotatie van je library om te voorkomen dat de schijf vol raakt.
Valideer je JSONL-logs online
Gebruik onze gratis tools in je browser om JSONL-logbestanden te inspecteren, valideren en converteren. Je hoeft niets te uploaden: alle verwerking gebeurt lokaal.
Leer hoe je JSONL-data in realtime streamt met Node.js, Python, Server-Sent Events en WebSockets. Bouw streamingpipelines voor logs, metrics en live datafeeds.
Strategieën om gigabytes aan JSONL-data te verwerken. Met aandacht voor lezen via streaming, geheugenbeheer, het splitsen van bestanden, compressie en online tools.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Maak JSONL-bestanden overzichtelijk met de juiste inspringing. Dat maakt debuggen en het controleren van data eenvoudiger.
Open .jsonl- en .ndjson-bestanden als een snelle, doorzoekbare tabel, direct in je editor. Gemaakt voor bestanden die te groot zijn om doorheen te scrollen en voor logs die nog worden weggeschreven.