NDJSON naar CSV omzetten

De rekensom is hier eenvoudiger dan bij elke andere bron op deze site. NDJSON garandeert één compleet record per regel, dus het aantal rijen dat je krijgt is het aantal regels in het bestand — wc -l op de opdrachtregel, of de regelteller in elke editor die het kan openen. Er kan niets in de data een regeleinde veroorzaken, want een nieuwe regel binnen een tekstwaarde wordt binnen de JSON ontsnapt.

Dat maakt de omzetting voorspelbaar op een manier die een JSON-array niet is. Heeft het bestand 412.000 regels, dan krijg je 412.000 rijen plus een kopregel. Lege regels worden overgeslagen, inclusief de afsluitende regel die bijna elke schrijver achterlaat.

Elke regel in een NDJSON-bestand staat op zich, en niets verplicht de tweede regel de sleutels van de eerste te dragen. Een logstroom die meerdere gebeurtenistypen uitzendt — een verzoek, een fout, een voltooide taak — zet die allemaal in één bestand met elk andere velden.

De omzetting verzamelt elke sleutel die ergens in het bestand voorkomt en geeft elk een kolom, met lege cellen waar een regel niets had. Er gaat niets verloren, en het resultaat kan erg schaars zijn: veertig kolommen waarvan elke rij er acht gebruikt. Is dat je uitvoer, dan is filteren op één gebeurtenistype voor het omzetten nuttiger dan het spreadsheet verbreden.

Is een regel geen geldige JSON, dan gaat de omzetting daar niet voorbij. De melding zegt welke regel: dit bestand kon niet als NDJSON gelezen worden — regel 3 is geen geldige JSON. Dat is bewust en niet fragiel.

Een kapotte regel in een log betekent bijna nooit een verdwaald teken. Het betekent meestal een afgebroken schrijfactie — een proces dat halverwege gedood werd, een geroteerd bestand dat op een grens is afgesneden — en alles na dat punt is verdacht. Met het regelnummer in de hand is de staart repareren of verwijderen één opdracht.

Gestructureerd loggen nest meestal: een verzoekobject met een methode en een pad, een gebruikersobject met een id. Die worden platgeslagen tot kolommen genoemd naar het pad — request.method, user.id — met één kolom per bladwaarde.

Eén of twee niveaus geven een tabel waar iedereen mee kan werken, en dat dekt de meeste standaardinstellingen van logbibliotheken. Diepere structuren verbreden snel, en een logregel met een hele geserialiseerde payload geeft een kolom per veld erin. Het interessante deel van het bestand is dan meestal één subboom, en die eerst eruit halen geeft een veel betere tabel.

Een record met een lijst — tags, foutframes, een set toegepaste regels — wordt platgeslagen tot genummerde kolommen: tags.0, tags.1, tags.2. Elke waarde blijft bewaard en de tabel krijgt een kolom voor de langste lijst in het bestand, de meeste leeg.

Voor analyse is dat zelden wat je wilt. Is de array bijzaak, dan geeft hem samenvoegen tot één tekst voor het omzetten één leesbare kolom. Is de array juist het onderwerp, dan wil je één rij per element, wat betekent dat het bestand eerst uitgevouwen moet worden.

Typen zijn het grootste verlies, en het gebeurt bij de bestemming, niet onderweg. De waarden worden trouw geschreven — een getal als cijfers, een boolean als true of false, een null als lege cel — maar CSV heeft geen typesysteem, dus wat het opent beslist wat alles is.

Excel beslist slecht en voorspelbaar: voorloopnullen verdwijnen uit identificatienummers, alles wat op een datum lijkt wordt een datum, en lange numerieke id’s verliezen hun laatste cijfers. Het middel is importeren in plaats van openen — Gegevens, dan Uit tekst/CSV, met identificatiekolommen ingesteld als tekst — of omzetten naar XLSX, waar typen expliciet in het bestand staan.

Waarden met een komma, een aanhalingsteken of een regeleinde worden tussen dubbele aanhalingstekens gezet met interne aanhalingstekens verdubbeld, de RFC 4180-conventie die elke degelijke importeerfunctie correct leest. Al het andere wordt kaal geschreven, zodat het bestand leesbaar blijft.

Logdata leunt daar zwaarder op dan de meeste bronnen. Useragents, verzoekpaden met querystrings, foutmeldingen en stacktraces zitten vol komma’s en aanhalingstekens. Is de bestemming een shellpijplijn in plaats van een spreadsheet, dan doet geen van die gereedschappen precies deze aanhalingstekens, en tab-gescheiden waarden omzeilt het probleem.

Het inlezen is snel en de grens is geheugen, omdat het hele bestand in records wordt gelezen en alle kolommen worden bepaald voordat de eerste rij geschreven kan worden. De gratis laag accepteert tot 100 MB; tientallen megabytes gaat zonder problemen en bij honderden begint een tabblad te haperen.

Daarboven is het bronformaat in je voordeel. NDJSON splitst veilig op elke regelgrens — split -l 500000 geeft geldige bestanden — dus een zeer groot logbestand in stukken omzetten is een legitieme aanpak en geen noodoplossing.

De CSV is een aanzicht, geen vervanging. Ze is de typen kwijt, heeft de structuur platgeslagen en records verzoend die nooit verplicht waren het eens te zijn, en niets daarvan is uit de tabel terug te halen.

Het oorspronkelijke bestand is ook beter in wat je hierna wilt: het groeit zonder herschrijven, filtert met jq zonder helemaal geladen te worden, en kan opnieuw omgezet worden met een andere subboom zodra de vraag verandert.

De omzetting is gewone JavaScript in dit browsertabblad. Er gaat geen verzoek de deur uit dat het bestand draagt, er is geen account en geen daglimiet, en dat is te controleren door het netwerktabblad te openen en iets om te zetten.

Dat is voor dit paar geen bijzaak. Een productielog bevat IP-adressen, sessie-identificatoren, verzoekpaden, useragents en vaak genoeg een querystring met een token erin — precies de inhoud die een log naar een converter uploaden bij de meeste organisaties meldingsplichtig maakt.