Door Jerry Fan

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

Aanbevolen

structlog 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.

Python: structlog
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

Snelste

pino 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.

Node.js: pino
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 geheugenallocaties

zerolog 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.

Go: zerolog
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-configuratie
# 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-pipeline
# 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.

Fluent Bit-configuratie
[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 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-configuratie
# 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

AWS

CloudWatch 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.

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

GCP Cloud Logging

GCP

Google 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.

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

Azure Monitor Logs

Azure

Azure 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.

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

Best 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.

Gebruik consistente logniveaus
{"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.

Standaardiseer veldnamen
// 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.

Inspecteer JSONL-logs in je browser

Bekijk, doorzoek en valideer JSONL-logbestanden tot 1GB. Ze laden direct, worden volledig in je browser verwerkt en blijven 100% privé.

Veelgestelde vragen

Bronnen