NDJSON naar YAML omzetten

Gestructureerde logging stopt hele documenten in losse velden. Een stacktrace, een SQL-statement, een request-body — elk is tekst met regeleinden erin, en JSON heeft precies één manier om een regeleinde vast te leggen: het teken \n. Een stacktrace van veertig frames komt daardoor binnen als één regel van duizenden tekens met \n tussen elk frame.

YAML heeft een ander middel en deze omzetting gebruikt het. Elke tekenreeks met een regeleinde erin wordt geschreven als blokscalair: de sleutel, dan |-, dan de echte regels ingesprongen eronder. De trace leest weer als een trace, zonder dat er iets aan de waarde zelf verandert.

Wie YAML kent, verwacht misschien een multidocumentstroom bij een regelgescheiden bron: elk record een eigen document, gescheiden door drie streepjes. Dat is niet wat hier ontstaat. Het hele bestand wordt één document met daarin een reeks, elk record met een streepje ervoor.

Deze site leest een YAML-stroom met meerdere documenten trouwens niet in, dus de enkeldocumentvorm is meteen ook de vorm die weer terug ingelezen kan worden. Een YAML-lader in een script krijgt zo een gewone lijst terug, geen generator om apart te doorlopen.

Een kale YAML-waarde wordt door de lezer geïnterpreteerd, dus een schrijver moet alles tussen aanhalingstekens zetten waarvan de kale vorm als iets anders zou terugkomen. Een cijferreeks, een waarde die met een hekje of sterretje begint, en een waarde met een dubbele punt en spatie erin worden hier tussen aanhalingstekens gezet — een ordernummer opgeslagen als "00412" komt zo met de voorloopnullen intact terug.

Dat is zorgvuldigheid van de schrijver, geen garantie van het formaat zelf. Verwijder de aanhalingstekens rond "00412" met de hand en de volgende keer dat iets het bestand inleest, wordt het het getal 412.

Het bestand wordt geschreven volgens YAML 1.2, waarin alleen true en false booleans zijn. NO, yes, on en off zijn daar gewone tekenreeksen en worden dus terecht zonder aanhalingstekens geschreven. Lees hetzelfde bestand in met PyYAML, Ruby’s Psych of een oudere Go-lader, en die volgen YAML 1.1, waarin het wél booleans zijn.

Voor een landcode-kolom met ergens een NO tussen dertigduizend rijen valt dat niet op tot het bij het inladen stilletjes False wordt. Is het doel een YAML 1.1-lezer, zet die kolom dan zelf tussen aanhalingstekens vóór het inladen, of blijf bij JSON.

CSV, TSV, XLSX, SQL en Parquet maken van een geneste request-structuur kolommen als request.method en request.path. Hier gebeurt niets van dat soort.

Een record met een vier niveaus diepe context-structuur komt vier niveaus diep ingesprongen terug. Arrays worden lijsten met streepjes. Records met verschillende velden houden hun eigen velden — er is geen samengevoegde kolomset en geen lege cel.

Een tekenreeks zonder regeleinden maar met veel lengte — een user agent, een lange URL — wordt rond de tachtig kolommen afgebroken op ingesprongen vervolgregels. YAML behandelt de regeleinden van zo’n gevouwen scalair als spaties, dus de waarde verandert niet bij het opnieuw inlezen.

Het betekent wel dat een URL in het bestand over twee regels verdeeld kan staan, wat de eerste keer verwarrend oogt maar geen beschadiging is. Moet je zo’n waarde letterlijk kopiëren, haal hem dan uit de ingeladen structuur in plaats van uit de tekst.

Een YAML-bestand dat iemand onderhoudt, dankt zijn waarde vaak aan de #-regels die uitleggen waarom een waarde is zoals ze is. Een geconverteerde export heeft die regels niet, omdat de bron er geen plek voor had.

Voor een bestand dat je één keer leest en dan weggooit is dat prima. Gaat het bestand gecommit worden, dan is het de moeite waard om er eerst drie regels commentaar boven te zetten: welk systeem het produceerde, wanneer de export werd genomen, welk filter is toegepast.

Lege regels worden overgeslagen, inclusief de afsluitende regel die bijna elke schrijver achterlaat, dus het aantal lijst-items komt overeen met het aantal niet-lege regels in de bron. Een regel die geen geldige JSON is, stopt de omzetting met het regelnummer erbij in plaats van stilletjes overgeslagen te worden.

Voor een export van fouten telt dat: de laatste regel van een log van een proces dat crashte, is vaak half geschreven, en met het regelnummer erbij kun je beslissen of die staart nog de moeite waard is voordat je conclusies trekt uit de rest.

De gratis grens ligt op honderd megabyte en het hele bestand wordt eerst volledig in het geheugen ingelezen voordat er iets wordt weggeschreven, dus de praktische grens is het browsertabblad eerder dan een quotum. Tientallen megabytes converteert zonder klagen.

Het zinvolle limiet ligt lager, want het doel van dit doelformaat is lezen. Filter eerst — een paar seconden met jq levert een bestand op dat je daadwerkelijk kunt doorlezen in plaats van een export die in theorie leesbaar is en in de praktijk ongelezen blijft.

In dit browsertabblad, door gewone JavaScript. Er wordt niets geüpload, er is geen engine om eerst te downloaden en geen account, en het netwerktabblad tijdens een omzetting bevestigt dat beter dan deze alinea.

Dat telt hier zwaarder dan bij de meeste paren. De bestanden die hier omgezet worden zijn foutexports en incidentdumps, en die dragen precies wat er onderweg was toen iets kapotging: request-paden, sessie-ID’s, af en toe een token in een querystring dat daar niet had moeten staan.