- Startseite
- Anleitung
- Strukturiertes Logging mit JSONL
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
Empfohlenstructlog 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.
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 Loggerpino 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.
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 Speicherallokationenzerolog 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.
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.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.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.
[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 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.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
AWSCloudWatch 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.
# 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 descGCP Cloud Logging
GCPGoogle 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.
# 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 >= ERRORAzure Monitor Logs
AzureAzure 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.
// 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 CountBest 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.
{"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.
// 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 online validieren
Mit unseren kostenlosen Browser-Tools können Sie JSONL-Log-Dateien untersuchen, validieren und konvertieren. Ein Upload ist nicht nötig: Die gesamte Verarbeitung erfolgt lokal.
Erfahren Sie, wie Sie JSONL-Daten mit Node.js, Python, Server-Sent Events und WebSockets in Echtzeit streamen. Erstellen Sie Streaming-Pipelines für Logs, Metriken und Live-Datenfeeds.
Strategien für JSONL-Daten im Gigabyte-Bereich: Lesen per Streaming, Speicherverwaltung, Aufteilen von Dateien, Komprimierung und Online-Tools.
Validieren Sie JSONL-Dateien Zeile für Zeile und erkennen Sie Syntaxfehler, Probleme mit der Zeichenkodierung und Formatfehler sofort.
Formatieren Sie JSONL-Dateien übersichtlich und mit korrekter Einrückung. Das erleichtert das Debuggen und die Prüfung der Daten.
Öffne .jsonl- und .ndjson-Dateien direkt in deinem Editor als schnelle, durchsuchbare Tabelle. Für Dateien, die zu groß zum Durchscrollen sind, und für Logs, in die laufend neue Einträge geschrieben werden.