Convertire NDJSON in YAML

Il logging strutturato mette interi documenti dentro campi singoli. Una traccia di stack, un’istruzione SQL renderizzata, un corpo di richiesta, un confronto di asserzione — ognuno è testo con ritorni a capo, e il JSON ha esattamente un modo di contenere un ritorno a capo, cioè scrivere i due caratteri barra rovesciata e n. Una traccia Python di quaranta frame arriva quindi come una riga di svariate migliaia di caratteri con \n fra ogni frame.

Il YAML ha un’altra opzione e questa conversione la usa. Qualsiasi stringa contenente un ritorno a capo viene scritta come blocco scalare: la chiave, poi |-, poi le righe vere indentate sotto. La traccia si legge come una traccia. Niente cambia nel valore — gli stessi caratteri entrano ed escono — ma il file smette di combattere con voi.

Chi scrive YAML guardando una sorgente delimitata da nuove righe si aspetterebbe ragionevolmente un flusso multi-documento: ogni record il proprio documento, --- fra loro. Non è quello che viene prodotto. L’intero file diventa un documento contenente una sequenza, con ogni record introdotto da un trattino e i suoi campi indentati sotto.

La scelta ha una conseguenza da sapere prima di costruirci sopra. Questo sito rifiuta del tutto di leggere un flusso YAML multi-documento — quella conversione si ferma invece di scegliere un documento — quindi la forma a documento singolo è quella che va e torna correttamente.

Uno scalare YAML nudo viene risolto dal lettore, quindi chi scrive deve mettere fra virgolette qualsiasi cosa la cui forma nuda tornerebbe come un tipo diverso. Questo mette fra virgolette i casi che contano per i dati esportati: una stringa di cifre, un valore che inizia con un cancelletto o un asterisco, un valore contenente due punti e spazio, e qualsiasi cosa con spazi bianchi iniziali o finali. Un riferimento d’ordine tenuto come stringa "00412" arriva tra virgolette e mantiene i suoi zeri iniziali.

È attenzione di chi scrive, non sicurezza del formato, e la distinzione conta quando qualcuno modifica il file in seguito. Cancellate le virgolette attorno a "00412" e diventerà il numero 412 la prossima volta che qualcosa lo carica.

Il file è scritto per YAML 1.2, dove gli unici booleani sono true e false. Sotto quella regola, NO, yes, on e off sono stringhe ordinarie e vengono correttamente scritte senza virgolette. Caricate lo stesso file con PyYAML, Psych di Ruby o uno dei caricatori Go più vecchi e sono booleani, perché quelli implementano YAML 1.1.

Per un file di configurazione ve ne accorgereste, perché lo leggete. Per un export no: una colonna di codici paese ISO ha un NO da qualche parte fra trentamila righe, e diventa False al caricamento senza nulla che lo indichi. Se il YAML è destinato a un lettore 1.1, mettete fra virgolette quella colonna prima di caricare, oppure tenete il JSON.

Ogni altra destinazione popolare per un export delimitato da nuove righe appiattisce. CSV, TSV, XLSX, SQL e Parquet trasformano tutti un oggetto request annidato in colonne chiamate request.method e request.path, e riconciliano i record contro un unico insieme di colonne. Niente del genere avviene qui.

Un record con un blocco context profondo quattro livelli arriva profondo quattro livelli, indentato. Gli array diventano liste con trattino. I record che portano campi diversi continuano a portare campi diversi — non c’è unione di chiavi, nessuna cella vuota e nessuna tabella sparsa.

Una stringa senza ritorni a capo ma con molta lunghezza — uno user agent, un URL con una lunga query string, un messaggio di errore su una riga — viene avvolta intorno agli ottanta caratteri su righe di continuazione indentate sotto la chiave. Il YAML tratta le interruzioni di riga di uno scalare piatto ripiegato come spazi, quindi il valore resta invariato quando viene riletto.

Significa che un URL può apparire diviso su due righe nel file, il che disorienta la prima volta e non è un danno. Se dovete copiare un valore del genere, prendetelo dalla struttura caricata piuttosto che dal testo, oppure convertite in JSON invece.

Nessuno. Un file YAML che una persona mantiene guadagna il suo formato dalle righe # che spiegano perché un valore è quello che è, e un export convertito non ha righe del genere perché la sorgente non aveva dove tenerle.

È il risultato giusto per un file che leggete una volta e cancellate. È il risultato sbagliato se il YAML sta per essere depositato in un repository, perché il prossimo lettore troverà record senza provenienza — nessuna nota su quale sistema li ha prodotti, quando è stato fatto l’export o quale filtro è stato applicato.

Le righe vuote vengono saltate, incluso il ritorno a capo finale che quasi ogni scrittore lascia alla fine, quindi il numero di voci della lista è il numero di righe non vuote nella sorgente. Una riga che non è JSON valido ferma la conversione con il suo numero nel messaggio invece di essere scartata.

Per un export di fallimenti quel comportamento si guadagna il suo posto. L’ultima riga di un log scritto da un processo andato in crash è molto spesso scritta a metà, e un convertitore che la saltasse in silenzio vi darebbe un file che sembra completo mentre manca il record che cercavate.

Il tetto gratuito è 100 MB e l’intero file viene analizzato in memoria prima che qualcosa venga scritto, quindi il limite pratico è la scheda del browser piuttosto che una quota. Decine di megabyte si convertono senza problemi.

Il limite sensato è comunque più basso di quello tecnico, perché lo scopo di questa destinazione è leggere. Nessuno legge trentamila record. Filtrate prima — jq -c 'select(.level=="error")' events.ndjson > errors.ndjson richiede un secondo e vi lascia con i quaranta record che intendevate davvero.

In questa scheda del browser, da JavaScript ordinario. Niente viene caricato, non c’è motore da scaricare prima e nessun account, e il pannello di rete durante una conversione è il modo per confermarlo.

Conta più per questa coppia che per la maggior parte. I file che le persone convertono qui sono export di errori e dump di incidenti, e portano ciò che era in corso quando qualcosa si è rotto: percorsi di richiesta, identificativi di sessione, occasionalmente un token in una query string che non doveva essere registrato.