NDJSON in CSV umwandeln

Ein Admin, der einer Auffälligkeit im Zugriffslog nachgeht, oder eine Analystin, die einen Exportjob prüfen soll, bekommt die Rohdaten fast immer als eine Zeile pro Ereignis — ein JSON-Objekt je Zugriff, je Fehler, je abgeschlossenem Job. Für eine Frage, die sich in einer Tabellenkalkulation in fünf Minuten beantworten ließe, ist das Format unpraktisch, bis es als Tabelle vorliegt.

In einem deutschen IT-Betrieb kommt dabei fast immer eine zweite Ebene dazu: Ein Zugriffslog enthält IP-Adressen, und personenbezogene Protokolldaten unterliegen der DSGVO ebenso wie, in vielen Betrieben, der Mitbestimmung des Betriebsrats nach § 87 BetrVG, sobald sie zur Verhaltens- oder Leistungskontrolle geeignet sind. Wo die Auswertung stattfindet, ist deshalb keine Nebenfrage.

Die Rechnung ist hier einfacher als bei jeder anderen Quelle auf dieser Website. NDJSON garantiert genau einen vollständigen Datensatz je Zeile, die Anzahl der Zeilen in der Datei ist also die Anzahl der Zeilen, die man bekommt — wc -l auf der Kommandozeile oder die Zeilenanzahl in jedem Editor, der die Datei öffnen kann. Ein Zeilenumbruch innerhalb eines Werts kann in der Quelle gar nicht vorkommen, weil er innerhalb des JSON-Strings maskiert ist.

Das macht die Umwandlung vorhersehbar, wie es ein JSON-Array nicht ist. Stehen in der Datei 412.000 Zeilen, kommen 412.000 Zeilen plus Kopfzeile heraus, und fehlen welche, lag es an der Eingabe und nicht an der Umwandlung. Leerzeilen werden übersprungen, auch die abschließende, die praktisch jeder Log-Writer am Dateiende hinterlässt.

Jede Zeile in einer NDJSON-Datei steht für sich, nichts verpflichtet die zweite Zeile, dieselben Felder wie die erste zu tragen. Ein Log-Stream, der mehrere Ereignistypen schreibt — eine Anfrage, ein Fehler, ein abgeschlossener Job — sammelt all das in einer Datei mit jeweils anderen Feldern, was als Stream sinnvoll und als Tabelle unhandlich ist.

Die Umwandlung sammelt jeden Schlüssel, der irgendwo in der Datei vorkommt, und macht daraus eine Spalte, leer dort, wo eine Zeile nichts dazu hatte. Nichts geht verloren, das Ergebnis kann aber sehr dünn besetzt sein: vierzig Spalten, von denen jede Zeile nur acht nutzt. Trifft das zu, hilft eher, die Datei vorher auf einen Ereignistyp zu filtern, als die Tabelle breiter zu machen — jq mit einem select auf den Ereignistyp dauert Sekunden und liefert eine Tabelle, die tatsächlich lesbar ist.

Ist eine Zeile kein gültiges JSON, läuft die Umwandlung nicht daran vorbei. Die Meldung nennt die Zeile: „Diese Datei konnte nicht als NDJSON gelesen werden — Zeile 3 ist kein gültiges JSON." Das ist bewusst so gebaut, nicht ein Zufall, und es ist das Verhalten, das man sich wünschen sollte.

Eine defekte Zeile in einem Log bedeutet fast nie ein einzelnes verirrtes Zeichen. Sie bedeutet meist einen abgebrochenen Schreibvorgang — ein Prozess, der mitten im Flush beendet wurde, eine Rotation, die genau an dieser Stelle geschnitten hat, ein unvollständiger Upload —, und alles danach ist verdächtig. Eine Zeile still zu überspringen, würde eine Tabelle liefern, der eine unbekannte Anzahl Datensätze fehlt, ohne dass etwas darauf hinweist. Mit der Zeilennummer in der Hand ist das Kürzen oder Reparieren des Endes eine Sache eines einzigen Befehls.

Strukturierte Protokollierung verschachtelt fast immer: ein request-Objekt mit einer Methode, ein user-Objekt mit einer ID, ein context-Block mit einer Trace-Kennung. Das wird zu Spalten aufgelöst, die nach dem Pfad benannt sind — request.method, user.id —, eine Spalte je Blattwert.

Ein bis zwei Ebenen ergeben eine Tabelle, mit der sich arbeiten lässt, und das deckt die Voreinstellungen der meisten Logging-Bibliotheken ab. Tiefere Strukturen weiten sich schnell aus, und eine Log-Zeile mit einer ganzen serialisierten Nutzlast erzeugt eine Spalte je enthaltenem Feld. In dem Fall ist die ehrliche Antwort, dass der interessante Teil der Datei ein einzelner Unterbaum ist — den vor der Umwandlung herauszulösen, ergibt eine deutlich bessere Tabelle, als hinterher Spalten auszublenden.

Ein Datensatz mit einer Liste — Tags, Fehler-Frames, ein Satz angewandter Regeln — wird in nummerierte Spalten aufgelöst: tags.0, tags.1, tags.2. Jeder Wert bleibt erhalten, und die Tabelle bekommt eine Spalte für die längste Liste in der Datei, die meisten davon leer.

Für eine Auswertung ist das selten das, was gebraucht wird. Ist die Liste nebensächlich, ergibt das Zusammenfügen zu einer einzigen Zeichenkette vor der Umwandlung eine lesbare Spalte. Ist die Liste der eigentliche Untersuchungsgegenstand — etwa das Zählen von Fehler-Frames —, ist eine Zeile je Element die passende Form, was ein vorheriges Auffalten der Datei bedeutet. Beides ist ein einziger jq-Ausdruck und schneller, als eine Tabelle nach tags.3 zu sortieren.

Typen sind der eigentliche Verlust, und der entsteht am Ziel, nicht auf dem Weg dorthin. Die Werte werden getreu geschrieben — eine Zahl als Ziffern, ein Wahrheitswert als true oder false, ein Null-Wert als leere Zelle —, aber CSV kennt kein Typsystem, also entscheidet das öffnende Programm, was aus jedem Feld wird.

Excel entscheidet dabei berechenbar falsch: führende Nullen verschwinden aus Kennungen, alles Datumsförmige wird zum Datum, lange numerische IDs verlieren ihre letzten Stellen. Die Abhilfe ist Importieren statt Öffnen — Daten, dann Aus Text/CSV, mit Kennungsspalten auf Text gesetzt — oder eine Umwandlung nach XLSX, wo die Typen in der Datei stehen und nichts geraten werden muss.

Werte mit einem Komma, einem Anführungszeichen oder einem Zeilenumbruch werden in doppelte Anführungszeichen gesetzt, interne Anführungszeichen verdoppelt — das ist die RFC-4180-Konvention und wird von jedem brauchbaren Importer korrekt gelesen. Alles andere bleibt unquotiert, damit die Datei lesbar bleibt.

Log-Daten nutzen diese Regel stärker aus als die meisten anderen Quellen. User-Agents, Anfragepfade mit Query-Strings, Fehlermeldungen und Stack-Traces stecken voller Kommata und Anführungszeichen. Führt der Weg in eine Shell-Pipeline statt in eine Tabellenkalkulation — awk, cut, ein naives Trennen an Kommata —, ist genau diese Quotierung das, was solche Werkzeuge nicht beherrschen, und eine Umwandlung nach tabgetrennten Werten umgeht die ganze Diskussion.

Das Einlesen ist schnell, die Grenze ist der Arbeitsspeicher, weil die ganze Datei zu Datensätzen eingelesen und die vollständige Spaltenmenge feststehen muss, bevor die erste Zeile geschrieben werden kann. Die freie Version nimmt bis zu 100 MB an; einige Dutzend Megabyte laufen ohne Weiteres, mehrere Hundert bringen einen Browser-Tab an seine Grenze.

Darüber hilft das Quellformat selbst. NDJSON lässt sich an jeder Zeilengrenze gefahrlos teilen — split -l 500000 erzeugt gültige Dateien —, ein sehr großes Log in Teilen umzuwandeln ist also ein legitimer Weg und kein Behelf, und die Teile haben identische Kopfzeilen, solange die Ereignisformen gleich bleiben. Für eine Datei im Gigabyte-Bereich ist ein Streaming-Werkzeug das richtige Instrument, diese Seite nicht mehr.

Eine reine Fehlerdiagnose an einem Zugriffslog — warum eine Anfrage fehlschlägt, welcher Endpunkt langsam ist — berührt in aller Regel keine Mitbestimmungsrechte, weil sie sich auf das System und nicht auf die Beschäftigten richtet. Sobald dieselben Log-Daten aber danach ausgewertet werden, wer wann worauf zugegriffen hat, ist die Schwelle zur Verhaltens- oder Leistungskontrolle schnell überschritten, und der Betriebsrat ist nach § 87 Abs. 1 Nr. 6 BetrVG zu beteiligen, bevor eine solche Auswertung als feste Praxis eingeführt wird.

Diese Umwandlung selbst trifft keine Entscheidung darüber — sie macht ein Log lediglich lesbar. Die Einordnung, ob eine geplante Auswertung mitbestimmungspflichtig ist, bleibt eine Frage für die eigene IT- oder Personalabteilung, aber ein Werkzeug, das die Datei nirgends hochlädt, verhindert wenigstens, dass diese Frage durch einen fremden Serverbetreiber vorweggenommen wird.

Die CSV ist eine Ansicht, kein Ersatz. Sie hat die Typen verloren, die Struktur abgeflacht und Datensätze vereinheitlicht, die nie verpflichtet waren, sich zu ähneln, und nichts davon lässt sich aus der Tabelle zurückgewinnen.

Die Ursprungsdatei ist außerdem für das Nächste besser geeignet: Sie wächst durch Anhängen ohne Neuschreiben, sie lässt sich mit jq filtern, ohne vollständig geladen zu werden, und sie lässt sich mit einem anderen herausgelösten Unterbaum erneut umwandeln, wenn sich die Frage ändert. Die CSV ist die Antwort auf die heutige Frage, die NDJSON bleibt die Datenbasis.

Die Umwandlung ist reines JavaScript, das in diesem Browser-Tab läuft. Keine Anfrage trägt die Datei irgendwohin, es gibt kein Konto und kein Tageslimit, und das lässt sich im Netzwerk-Tab der Entwicklerwerkzeuge während einer Umwandlung selbst nachprüfen.

Das ist bei dieser Datenart keine Nebensächlichkeit. Ein Produktionslog enthält IP-Adressen, Sitzungskennungen, Anfragepfade, User-Agents und häufig einen Query-String mit einem Token darin — genau die Kategorie, deren Hochladen in einen fremden Webdienst in vielen deutschen IT-Abteilungen ein meldepflichtiger Vorfall wäre und die Mitbestimmung des Betriebsrats berühren kann. Hier gibt es nichts hochzuladen.