Converter NDJSON para YAML

Logging estruturado coloca documentos inteiros dentro de campos únicos. Um stack trace, uma instrução SQL renderizada, um corpo de requisição, um diff de asserção — cada um é texto com quebras de linha, e o JSON só tem um jeito de guardar uma quebra de linha: escrever os dois caracteres barra invertida e n. Um traceback Python de quarenta quadros chega, portanto, como uma linha só de vários milhares de caracteres com `\n` entre cada quadro.

O YAML tem outra opção, e esta conversão usa ela. Qualquer string contendo uma quebra de linha é escrita como um bloco escalar: a chave, depois `|-`, depois as linhas de verdade indentadas embaixo. O trace lê como um trace. Nada no valor muda — os mesmos caracteres entram e saem — mas o arquivo para de brigar com você.

Alguém acostumado a YAML olhando para uma origem separada por linha esperaria razoavelmente um fluxo multidocumento: cada registro seu próprio documento, `---` entre eles. Não é o que é produzido. O arquivo inteiro vira um documento contendo uma sequência, com cada registro introduzido por um traço e seus campos indentados embaixo.

A escolha tem uma consequência que vale conhecer antes de construir em cima. Este site se recusa a ler um fluxo YAML multidocumento — essa conversão para em vez de escolher um documento — então a forma de documento único é a que faz ida e volta. Também significa que a saída é um valor único, o que um carregador de YAML num script espera: `yaml.safe_load(open(f))` te dá uma lista, não um gerador que você tem que lembrar de iterar.

Um escalar YAML sem aspas é resolvido pelo leitor, então um gravador precisa colocar aspas em qualquer coisa cuja forma sem aspas voltaria como um tipo diferente. Este coloca aspas nos casos que importam para dado exportado: uma sequência de dígitos, um valor começando com um cerquilha ou asterisco, um valor contendo dois-pontos e espaço, e qualquer coisa com espaço em branco no início ou fim. Uma referência de pedido guardada como a string "00412" chega com aspas e mantém os zeros à esquerda.

É o gravador sendo cuidadoso, não o formato sendo seguro, e a distinção importa quando alguém edita o arquivo depois. Apague as aspas ao redor de "00412" e vira o número 412 na próxima vez que algo carregar. Se o YAML vai ser editado à mão e depois lido de volta por um programa, as aspas são estruturais, não decorativas.

O arquivo é escrito em YAML 1.2, onde os únicos booleanos são `true` e `false`. Sob essa regra, "NO", "yes", "on" e "off" são strings comuns e são escritos corretamente sem aspas. Carregue o mesmo arquivo com PyYAML, o Psych do Ruby ou um dos carregadores Go mais antigos, e eles são booleanos, porque implementam YAML 1.1.

Para um arquivo de configuração você notaria, porque lê ele. Para uma exportação, não: uma coluna de país com códigos ISO tem um "NO" em algum lugar entre trinta mil linhas, e ele vira `False` ao carregar sem nada indicar isso. Se o YAML vai para um leitor 1.1, coloque aspas nessa coluna antes de carregar ou mantenha o JSON.

Todo outro destino popular para uma exportação separada por linha achata. CSV, TSV, XLSX, SQL e Parquet transformam um objeto `request` aninhado em colunas chamadas `request.method` e `request.path`, e reconciliam os registros contra um conjunto de colunas único. Nada disso acontece aqui.

Um registro com um bloco `context` de quatro níveis de profundidade chega quatro níveis de profundidade, indentado. Arrays viram listas com traço. Registros que carregam campos diferentes continuam carregando campos diferentes — não há união de chaves, nem célula vazia, nem tabela esparsa. Para ler uma exportação onde a parte interessante é uma subárvore, isso é exatamente o que você quer.

Uma string sem quebras de linha mas com bastante comprimento — um user agent, uma URL com string de consulta longa, uma mensagem de erro de uma linha — é quebrada em torno de oitenta colunas em linhas de continuação indentadas sob a chave. O YAML trata as quebras de linha de um escalar simples dobrado como espaços, então o valor volta inalterado quando lido de novo.

Isso significa que uma URL pode aparecer dividida em duas linhas no arquivo, o que é estranho na primeira vez e não é dano. Se você precisa copiar tal valor, pegue da estrutura carregada em vez do texto, ou converta para JSON, onde todo valor fica na linha em que começou.

Nenhum. Um arquivo YAML que uma pessoa mantém ganha do formato justamente as linhas com `#` explicando por que um valor é o que é, e uma exportação convertida não tem essas linhas porque a origem não tinha onde guardá-las. O que você recebe é YAML bem formado sem anotação nenhuma.

É o resultado certo para um arquivo que você vai ler uma vez e apagar. É o resultado errado se o YAML está prestes a ser versionado, porque o próximo leitor vai encontrar registros sem proveniência nenhuma. Acrescentar três linhas de comentário no topo antes de versionar não custa nada.

Linhas vazias são ignoradas, inclusive a quebra de linha final que quase todo gravador deixa no fim, então o número de entradas da lista é o número de linhas não vazias na origem. Uma linha que não é JSON válido para a conversão com o número dela na mensagem em vez de ser descartada.

Para uma exportação de falhas, esse comportamento se justifica. A última linha de um log escrito por um processo que travou frequentemente está pela metade, e um conversor que a pulasse silenciosamente entregaria um arquivo que lê como completo enquanto falta justo o registro que você procurava.