NDJSON in YAML umwandeln

Ein Fehlerprotokoll, das personenbezogene Daten enthält — eine IP-Adresse in einer Request-Zeile, eine E-Mail in einer fehlgeschlagenen Registrierung, einen Namen in einer Support-Nachricht —, darf nicht einfach unbegrenzt aufbewahrt werden. Wer vor dem Löschen kurz prüfen will, was in einem Export überhaupt steckt, öffnet die Datei üblicherweise nicht mit einem Skript, sondern mit den eigenen Augen.

Genau dafür ist NDJSON denkbar ungeeignet. Jede Zeile ist ein vollständiges JSON-Objekt, und ein Feld mit einem Stacktrace oder einem SQL-Statement steht darin als eine einzige, mehrere tausend Zeichen lange Zeile mit `\n` zwischen jedem Absatz. Bevor überhaupt beurteilt werden kann, ob eine Zeile etwas Schützenswertes enthält, muss man sie erst lesbar machen.

Jeder String mit einem Zeilenumbruch wird als Block-Skalar geschrieben: der Schlüssel, dann `|-`, dann die echten Zeilen darunter eingerückt. Ein vierzig Frames langer Python-Stacktrace liest sich dann als Stacktrace, statt als eine Zeile voller Escape-Sequenzen, die man erst im Terminal breitziehen müsste.

Am Wert selbst ändert sich nichts — dieselben Zeichen gehen hinein und kommen heraus —, aber die Datei hört auf, gegen einen zu arbeiten. Für einen Export, den man einmal durchsieht und danach löscht, ist das der ganze Sinn dieser Umwandlung.

Wer YAML gewohnt ist, würde bei einer zeilenweisen Quelle einen Strom mehrerer Dokumente erwarten, jeweils durch drei Bindestriche getrennt. Das ist nicht das Ergebnis. Die ganze Datei wird zu einem Dokument mit einer Sequenz, jeder Eintrag mit einem Bindestrich eingeleitet und seine Felder darunter eingerückt.

Das hat Folgen, die vor dem Weiterverarbeiten wichtig sind: Diese Seite liest umgekehrt keinen mehrteiligen YAML-Strom — diese Umwandlung bricht ab, statt ein Dokument beliebig auszuwählen —, also ist die Einzeldokument-Form die, die tatsächlich wieder eingelesen werden kann. Ein `yaml.safe_load` in Python liefert damit eine Liste, kein Generator-Objekt, das man extra durchlaufen müsste.

Ein unmarkiertes YAML-Skalar wird vom Parser interpretiert, also muss ein Schreiber alles in Anführungszeichen setzen, dessen unmarkierte Form als etwas anderes zurückkäme. Eine Zeichenkette aus Ziffern, ein Wert, der mit Raute oder Sternchen beginnt, ein Wert mit Doppelpunkt und Leerzeichen, alles mit führenden oder folgenden Leerzeichen — genau diese Fälle werden hier gequotet. Eine Bestellnummer, die als String „00412" vorlag, kommt in Anführungszeichen zurück und behält ihre führende Null.

Das ist Sorgfalt beim Schreiben, keine Eigenschaft des Formats. Wer die Anführungszeichen später von Hand entfernt, macht aus „00412" beim nächsten Einlesen die Zahl 412. Wird die YAML-Datei später bearbeitet und dann wieder von einem Programm gelesen, trägt die Quotierung tatsächlich Bedeutung.

Die Datei wird nach YAML 1.2 geschrieben, wo die einzigen Wahrheitswerte `true` und `false` heißen. Nach dieser Regel sind `NO`, `yes`, `on` und `off` gewöhnliche Zeichenketten und werden folgerichtig unquotiert geschrieben. Lädt man dieselbe Datei mit PyYAML, Rubys Psych oder einem älteren Go-Loader, gelten diese Implementierungen noch YAML 1.1, und dort werden sie zu Wahrheitswerten.

Für eine handgepflegte Konfigurationsdatei würde man das bemerken, weil man sie liest. Bei einem Export nicht: Eine Ländercode-Spalte enthält irgendwo unter dreißigtausend Zeilen ein `NO`, und beim Laden wird daraus kommentarlos `False`. Geht die Datei an einen 1.1-Parser, entweder diese Spalte vorher quoten oder gleich bei JSON bleiben, das keine solche Mehrdeutigkeit kennt.

Jedes andere populäre Ziel für einen zeilenweisen Export flacht ab. CSV, TSV, XLSX, SQL und Parquet verwandeln ein verschachteltes `request`-Objekt in Spalten wie `request.method` und `request.path` und gleichen die Zeilen gegen einen gemeinsamen Spaltensatz ab. Nichts davon passiert hier.

Ein Datensatz mit einem vier Ebenen tiefen `context`-Block kommt vier Ebenen tief eingerückt an. Arrays werden zu Bindestrich-Listen. Datensätze mit unterschiedlichen Feldern behalten ihre unterschiedlichen Felder — es gibt keine Vereinigungsmenge der Schlüssel, keine leeren Zellen, keine dünn besetzte Tabelle. Für einen Export, dessen interessanter Teil ein Unterbaum ist, ist das genau richtig, und deshalb gilt dieses Ziel als verlustfrei, während die Tabellenziele es nicht sind.

Ein String ohne Zeilenumbruch, aber mit beträchtlicher Länge — ein User-Agent, eine URL mit langer Query-String, eine einzeilige Fehlermeldung — wird bei etwa achtzig Zeichen umgebrochen und in Folgezeilen eingerückt fortgesetzt. YAML behandelt Zeilenumbrüche in einem gefalteten Skalar als Leerzeichen, der Wert ist beim Wiedereinlesen also unverändert.

Das bedeutet, eine URL kann in der Datei über zwei Zeilen verteilt erscheinen, was beim ersten Mal irritiert und keine Beschädigung ist. Wer einen solchen Wert herauskopieren muss, nimmt ihn aus der geladenen Struktur statt aus dem Text, oder wandelt stattdessen nach JSON um, wo jeder Wert auf seiner eigenen Zeile bleibt.

Keiner. Eine YAML-Datei, die jemand pflegt, verdankt ihren Nutzen den `#`-Zeilen, die erklären, warum ein Wert so gesetzt ist, und ein konvertierter Export hat solche Zeilen nicht, weil die Quelle nirgends Platz dafür hatte. Herauskommt wohlgeformtes YAML ohne jede Annotation.

Für eine Datei, die einmal gelesen und danach gelöscht wird, ist das genau richtig. Für eine YAML-Datei, die gleich in ein Repository eingecheckt werden soll, ist es das falsche Ergebnis, weil die nächste Person keine Herkunftsangabe findet — kein Hinweis, welches System die Daten erzeugt hat, wann der Export gezogen wurde oder welcher Filter angewendet war. Drei Kommentarzeilen am Anfang vor dem Commit kosten nichts und sind der ganze Unterschied zwischen einer Datendatei und einem Rätsel.

Leere Zeilen werden übersprungen, einschließlich des abschließenden Zeilenumbruchs, den fast jeder Schreiber am Ende hinterlässt — die Anzahl der Listeneinträge entspricht also der Zahl der nicht leeren Zeilen in der Quelle. Eine Zeile, die kein gültiges JSON ist, bricht die Umwandlung mit ihrer Zeilennummer ab, statt stillschweigend übersprungen zu werden.

Bei einem Export von Fehlern zahlt sich das aus. Die letzte Zeile eines Logs, das von einem abgestürzten Prozess geschrieben wurde, ist sehr häufig unvollständig — ein Konverter, der sie stillschweigend fallen lässt, würde eine Datei liefern, die vollständig aussieht und genau den gesuchten Eintrag vermissen lässt. Mit der Zeilennummer lässt sich entscheiden, ob der Rest noch zu retten ist, bevor man aus dem übrigen Inhalt Schlüsse zieht.

Die kostenlose Obergrenze liegt bei 100 MB, und die ganze Datei wird vor dem Schreiben vollständig in den Speicher geladen, die praktische Grenze ist also der Browser-Tab und keine Quote. Mehrere zehn Megabyte laufen ohne Beanstandung durch.

Die vernünftige Grenze liegt trotzdem niedriger als die technische, weil der Sinn dieses Ziels das Lesen ist. Niemand liest dreißigtausend Datensätze. Vorher filtern — `jq -c 'select(.level=="error")' events.ndjson > errors.ndjson` dauert eine Sekunde und lässt genau die vierzig Zeilen übrig, um die es tatsächlich geht — ergibt eine YAML-Datei, durch die man scrollen und die man nachvollziehen kann. Der ganze Export ergibt eine Datei, die im Prinzip lesbar ist und in der Praxis niemand liest.

In diesem Browser-Tab, mit gewöhnlichem JavaScript. Nichts wird hochgeladen, es gibt keine Engine, die vorher heruntergeladen werden müsste, und kein Konto — der Netzwerk-Tab während einer Umwandlung ist der Nachweis dafür, nicht dieser Absatz.

Das zählt bei dieser Seite mehr als bei den meisten anderen. Die Dateien, die hier landen, sind Fehler-Exporte und Störungsprotokolle, und sie enthalten genau das, was gerade unterwegs war, als etwas kaputtging: Anfragepfade, Sitzungskennungen, gelegentlich ein Token in einer Query-String, das dort nie hätte protokolliert werden dürfen. Das ist genau die Kategorie, die niemand in einen fremden Webdienst einfügen sollte, und hier gibt es nichts einzufügen.

Wer ein Log vor der Löschung durchsieht, will meist zwei Dinge wissen: Steht personenbezogenes Material darin, und wenn ja, wo genau. Die YAML-Form beantwortet die erste Frage schneller, weil jedes Feld auf einer eigenen eingerückten Zeile steht und sich mit den Augen überfliegen lässt, statt zwischen Anführungszeichen und Kommas im JSON gesucht werden zu müssen.

Die zweite Frage — wo genau — beantwortet keine Formatumwandlung, nur das Lesen selbst. Was diese Seite dafür beisteuert, ist, dass das Lesen überhaupt zumutbar wird: eine Handvoll gefilterter Datensätze in YAML lässt sich in wenigen Minuten durchgehen, während dieselben Datensätze als rohes NDJSON eine Suche mit einem Editor-Skript gebraucht hätten, um dieselbe Aussage zu treffen.