Von Jerry Fan

Strukturiertes Logging mit JSONL

Eine umfassende Anleitung zum strukturierten Logging im Format JSONL (JSON Lines). Erfahren Sie anhand produktionsreifer Codebeispiele, wie Sie JSONL-Logs in den ELK Stack, Fluentd, CloudWatch, GCP Logging und Azure Monitor integrieren.

Warum strukturiertes Logging mit JSONL?

Klassische Klartext-Logs lassen sich gut von Menschen lesen, sind aber maschinell kaum zuverlässig zu parsen. In einer Zeile wie '2024-01-15 ERROR User login failed for admin' stecken Schweregrad, Ereignistyp und Benutzername in einem unstrukturierten String. Jedes Tool zur Log-Aggregation muss diese Informationen mit fehleranfälligen regulären Ausdrücken extrahieren. Jede Änderung am Log-Format bringt dann die Pipeline zum Scheitern.

Strukturiertes Logging löst dieses Problem: Jeder Log-Eintrag wird als JSON-Objekt mit klar definierten Feldern ausgegeben. JSONL (JSON Lines) geht noch einen Schritt weiter: ein JSON-Objekt pro Zeile, ohne umschließendes Array und ohne abschließende Kommas. So lassen sich neue Einträge einfach anhängen, Logs als Stream verarbeiten und mit allen gängigen Log-Plattformen mühelos parsen. In dieser Anleitung erfahren Sie, wie Sie JSONL-Logs in Python, Node.js und Go erzeugen und an ELK, Fluentd sowie die drei großen Cloud-Anbieter senden.

Im Vergleich zu anderen strukturierten Formaten wie CSV oder XML bietet JSONL die beste Mischung aus Flexibilität, Tool-Unterstützung und guter Lesbarkeit. Felder lassen sich verschachteln, Datentypen bleiben erhalten, und Sie müssen vorab kein festes Schema definieren. Deshalb hat sich JSONL als De-facto-Standard für strukturiertes Logging in modernen Infrastrukturen etabliert.

Logging-Bibliotheken nach Programmiersprache

Die meisten modernen Logging-Bibliotheken unterstützen strukturierte JSON-Ausgaben entweder direkt oder nach einer einfachen Konfigurationsänderung. Im Folgenden stellen wir empfohlene Bibliotheken für Python, Node.js und Go vor, die alle JSONL-kompatible Ausgaben erzeugen.

Python: structlog

Empfohlen

structlog ist die führende Bibliothek für strukturiertes Logging in Python. Sie setzt auf dem logging-Modul der Standardbibliothek auf und gibt standardmäßig JSON aus. Über ihre Prozessor-Pipeline lassen sich Log-Einträge vor der Serialisierung anreichern, filtern und transformieren.

Python: structlog
import structlog


# structlog für JSONL-Ausgabe konfigurieren
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()


# Jeder Aufruf erzeugt eine JSONL-Zeile
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

Schnellster Logger

pino ist der schnellste Logger für Node.js und gibt ohne weitere Konfiguration standardmäßig JSONL aus. Asynchrones Schreiben und eine auf das Nötigste beschränkte Serialisierung halten den Overhead gering. Das ergänzende Paket pino-pretty sorgt bei der lokalen Entwicklung für eine gut lesbare Ausgabe.

Node.js: pino
import pino from 'pino';


// pino gibt standardmäßig JSONL aus
const log = pino({
  level: 'info',
  timestamp: pino.stdTimeFunctions.isoTime,
});


// Jeder Aufruf erzeugt eine JSONL-Zeile
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"}


// Kind-Logger erben den Kontext
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');

Go: zerolog

Ohne Speicherallokationen

zerolog ist ein JSON-Logger für Go, der ohne Speicherallokationen auskommt und auf maximale Performance in Services mit hohem Durchsatz ausgelegt ist. Er schreibt ohne zwischenzeitliche Allokationen direkt in einen io.Writer und eignet sich damit besonders für Anwendungen mit hohen Anforderungen an die Latenz. Seine API mit verketteten Methodenaufrufen ist angenehm zu verwenden und zugleich effizient.

Go: zerolog
package main


import (
    "os"
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)


func main() {
    // JSONL-Ausgabe nach stdout konfigurieren
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()


    // Jeder Aufruf erzeugt eine JSONL-Zeile
    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")
}

Integration in den ELK Stack

Der ELK Stack (Elasticsearch, Logstash, Kibana) ist die am weitesten verbreitete Open-Source-Plattform für Log-Management. JSONL-Logs lassen sich nahtlos einbinden: Logstash und Filebeat können JSON direkt parsen, sodass komplexe Grok-Muster entfallen.

Filebeat ist ein schlanker Log-Shipper, der neue Einträge aus Ihren JSONL-Log-Dateien fortlaufend einliest und an Logstash oder Elasticsearch weiterleitet. Mit json.keys_under_root auf true werden die JSON-Felder als Felder auf der obersten Ebene in Elasticsearch abgelegt und sind dadurch direkt in Kibana durchsuchbar.

Filebeat-Konfiguration
# 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: stattdessen an Logstash senden
# output.logstash:
#   hosts: ["logstash:5044"]

Wenn Sie Logs vor der Indexierung transformieren oder anreichern möchten, schalten Sie Logstash zwischen Filebeat und Elasticsearch. Der json-Codec parst jede JSONL-Zeile automatisch. Mit dem mutate-Filter können Sie vor dem Speichern Felder umbenennen, Tags hinzufügen oder sensible Daten entfernen.

Logstash-Pipeline
# logstash.conf
input {
  beats {
    port => 5044
    codec => json
  }
}


filter {
  # Zeitstempel aus dem JSON-Feld parsen
  date {
    match => ["timestamp", "ISO8601"]
    target => "@timestamp"
  }


  # Umgebungs-Tag hinzufügen
  mutate {
    add_field => { "environment" => "production" }
    remove_field => ["agent", "ecs", "host"]
  }


  # Nach Log-Level routen
  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 und die schlankere Alternative Fluent Bit haben beide den Graduated-Status der CNCF erreicht und sind in Kubernetes-Umgebungen weit verbreitet. Beide verarbeiten JSONL-Logs direkt und können sie an nahezu jedes Ziel weiterleiten – von Elasticsearch über S3 bis hin zu Cloud-nativen Logging-Diensten.

Fluent Bit ist der bevorzugte Log-Collector für Kubernetes und Umgebungen mit begrenzten Ressourcen. Er benötigt etwa 450 KB Arbeitsspeicher und kann Hunderttausende Datensätze pro Sekunde verarbeiten. Der json-Parser verarbeitet JSONL-Eingaben ohne spezielle Konfiguration.

Fluent-Bit-Konfiguration
[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 bietet mit über 500 Community-Plugins ein umfangreicheres Plugin-Ökosystem als Fluent Bit. Verwenden Sie Fluentd, wenn Sie erweiterte Funktionen für Routing, Pufferung oder Transformationen benötigen. Das Plugin in_tail liest JSONL-Dateien mit der Formateinstellung json direkt ein.

Fluentd-Konfiguration
# 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>

Cloud-Logging-Plattformen

Alle drei großen Cloud-Anbieter akzeptieren Logs im JSONL-Format und erschließen die JSON-Felder automatisch als durchsuchbare und filterbare Attribute. So können Sie auf eine eigene Log-Infrastruktur verzichten und trotzdem dieselben strukturierten Abfragen nutzen.

AWS CloudWatch Logs

AWS

CloudWatch Logs parst JSON-Log-Einträge automatisch, sodass Sie jedes Feld mit CloudWatch Logs Insights abfragen können. Läuft Ihre Anwendung auf ECS, Lambda oder EC2 mit dem CloudWatch-Agent, wird die JSONL-Ausgabe ohne zusätzliche Konfiguration als strukturierte Daten indexiert. Mit der SQL-ähnlichen Syntax von Logs Insights durchsuchen Sie Millionen von Log-Einträgen in Sekundenschnelle.

AWS CloudWatch Logs
# CloudWatch Logs Insights Abfragebeispiele
# Alle Fehler der letzten Stunde finden
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100


# Fehleranzahl nach Ereignistyp aggregieren
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc


# P99-Latenz nach Endpunkt
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 (ehemals Stackdriver) unterstützt JSON-Payloads von Haus aus als strukturierte Log-Einträge. Wenn Sie auf Cloud Run, GKE oder Cloud Functions JSONL auf stdout ausgeben, parst der Logging-Agent jede Zeile zu einem strukturierten LogEntry. Das Feld severity wird direkt dem entsprechenden Schweregrad in Cloud Logging zugeordnet. Die Felder in jsonPayload werden indexiert und sind durchsuchbar.

GCP Cloud Logging
# Python-Beispiel für Cloud Run / Cloud Functions
import json
import sys


def log(severity: str, message: str, **fields):
    """Einen JSONL-Log-Eintrag schreiben, der mit GCP Cloud Logging kompatibel ist."""
    entry = {
        "severity": severity.upper(),  # Wird auf Cloud Logging Schweregrad abgebildet
        "message": message,
        **fields,
    }
    print(json.dumps(entry), file=sys.stdout, flush=True)


# GCP parst diese automatisch als strukturierte Logs
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)


# Abfrage in Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERROR

Azure Monitor Logs

Azure

Azure Monitor nimmt JSONL-Logs über den Azure Monitor Agent oder direkt über die API entgegen. Application Insights parst JSON-Traces und benutzerdefinierte Events automatisch. Mit KQL (Kusto Query Language) können Sie strukturierte Log-Daten umfassend abfragen, aggregieren, als Zeitreihen analysieren und auf Anomalien untersuchen.

Azure Monitor Logs
// KQL-Abfragen für JSONL-Logs in Azure Monitor
// Aktuelle Fehler finden
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


// Fehlerrate über Zeit (5-Minuten-Intervalle)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart


// Top-Fehlerereignisse
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by Count

Best Practices für JSONL-Logging

Einheitliche Konventionen in allen Services erleichtern es, JSONL-Logs abzufragen, miteinander zu korrelieren und darauf basierende Alarme einzurichten. Diese Best Practices stammen aus Produktionssystemen, die täglich Milliarden von Log-Einträgen verarbeiten.

Konsistente Log-Level verwenden

Legen Sie eine einheitliche Skala für Schweregrade fest und verwenden Sie sie in allen Services. Die gängigste Konvention umfasst fünf Level: DEBUG für Diagnoseinformationen während der Entwicklung, INFO für den normalen Betrieb, WARN für behebbare Probleme, ERROR für Fehler, um die Sie sich kümmern müssen, und FATAL für nicht behebbare Abstürze. Ordnen Sie numerische Level (etwa auf der Skala 10-60 von pino) beim Einlesen diesen Bezeichnungen als Strings zu, damit Sie alle Logs einheitlich abfragen können.

Konsistente Log-Level verwenden
{"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"}

Feldnamen standardisieren

Definieren Sie für alle Services ein gemeinsames Schema für die üblichen Felder. Verwenden Sie snake_case für Feldnamen, ISO 8601 für Zeitstempel und einheitliche Namen für Korrelations-IDs. Jeder Log-Eintrag sollte mindestens timestamp, level, event (einen maschinenlesbaren Ereignisnamen) und service enthalten. Einträge, die sich auf einen Request beziehen, sollten für das Tracing außerdem request_id und user_id enthalten.

Feldnamen standardisieren
// Empfohlenes Feldschema
{
  "timestamp": "2026-02-15T08:30:00.000Z",  // ISO 8601, immer UTC
  "level": "info",                            // debug|info|warn|error|fatal
  "event": "order.created",                    // Punkt-Notation Ereignisname
  "service": "order-api",                      // Emittierender Service
  "version": "1.4.2",                          // Service-Version
  "request_id": "req-abc-123",                 // Korrelations-ID
  "trace_id": "4bf92f3577b34da6",              // Verteilte Trace-ID
  "user_id": "u-42",                           // Authentifizierter Benutzer
  "duration_ms": 120,                          // Numerisch, nicht String
  "order_id": "ord-789",                       // Domänenspezifischer Kontext
  "items_count": 3                             // Domänenspezifischer Kontext
}

Performance beachten

Bei strukturiertem Logging entsteht mit jedem Log-Aufruf zusätzlicher Aufwand für die Serialisierung. In Services mit hohem Durchsatz kann das deutlich ins Gewicht fallen. Nutzen Sie asynchrones Logging (pino, zerolog), um die Serialisierung aus dem kritischen Ausführungspfad auszulagern. Vermeiden Sie es, große Objekte oder Request- und Response-Bodies auf INFO-Level zu loggen. Nutzen Sie Sampling, wenn sehr viele Debug-Logs anfallen. Schreiben Sie Logs in lokale Dateien und überlassen Sie die Weiterleitung einem Sidecar (Filebeat, Fluent Bit), statt sie synchron über das Netzwerk zu senden.

Verwenden Sie asynchrone Logger (pino, zerolog), damit die JSON-Serialisierung den Hauptthread nicht blockiert.

Loggen Sie niemals vollständige Request- oder Response-Bodies auf INFO-Level. Verwenden Sie dafür DEBUG und aktivieren Sie dieses Level nur zur Fehlersuche.

Nutzen Sie Sampling bei häufig auftretenden Events. Loggen Sie beispielsweise nur 1 von 100 Health-Check-Requests statt jeden einzelnen.

Schreiben Sie Logs in lokale Dateien und leiten Sie sie mit Filebeat oder Fluent Bit asynchron weiter. Vermeiden Sie synchrone Netzwerkaufrufe bei der Log-Verarbeitung.

Begrenzen Sie die Größe einer Log-Zeile (z. B. auf 16 KB), damit übergroße Einträge die Pipeline nicht blockieren.

Nutzen Sie logrotate oder die integrierte Log-Rotation Ihrer Bibliothek, damit Log-Dateien nicht den gesamten Speicherplatz belegen.

JSONL-Logs im Browser untersuchen

JSONL-Log-Dateien bis zu 1 GB anzeigen, durchsuchen und validieren. Sofort geladen, direkt im Browser verarbeitet, zu 100 % privat.

Häufig gestellte Fragen

Quellen