NDJSON を YAML に変換

構造化ログはスタックトレースや SQL 文、リクエスト本文といった長いテキストを一つのフィールドに丸ごと詰め込みます。JSON は改行を \n という二文字でしか表現できないので、数十行のトレースが数千文字の一行として出力され、そのままでは読めません。

YAML には別の書き方があります。改行を含む文字列はブロックスカラーとして書かれ、キーの下に本当の改行を持つ形で表示されます。値そのものは一切変わりませんが、ファイルが読みやすい形になります。読むための書き出しでは、これが JSON より YAML を選ぶ主な理由です。

行区切りのファイルなので、レコードごとに --- で区切られた複数ドキュメントの形を想像するかもしれませんが、実際には全体が一つのドキュメントになり、各レコードがダッシュ付きの項目として並びます。

このサイトでは複数ドキュメントの YAML ストリームを読み込む変換自体を扱っていないため、一つのドキュメントにまとまった形が、そのまま読み込みにも使える形になります。スクリプトの yaml.safe_load はリストを一度に受け取れます。

注文番号のような「00412」という値は、そのまま書くと数値として解釈されてしまいます。書き出しの際は数字だけの文字列や、コロンとスペースを含む値などを引用符で囲むので、先頭のゼロも失われずに残ります。

ただしこれは書き出し側の配慮であって、フォーマット自体が安全という意味ではありません。ファイルを手で編集して引用符を消してしまうと、次に読み込んだときにただの数値に変わってしまいます。

このサイトの書き出しは YAML 1.2 に沿っていて、真偽値は true と false だけです。NO や yes、on、off はただの文字列として扱われ、引用符なしで正しく出力されます。

ただし PyYAML や Ruby の Psych、一部の古い Go 実装は YAML 1.1 の解釈をするため、同じ NO が真偽値の false として読み込まれます。国コードの列に NO が含まれるログを、それらのパーサーで読む予定があるなら注意が必要です。

CSV や TSV、XLSX、SQL、Parquet といった表形式の変換先はすべて、入れ子になったオブジェクトを request.method のようなドット区切りの列名に平坦化します。ここではその処理は一切行われません。

四階層深いオブジェクトはそのまま四階層深くインデントされ、配列はダッシュ付きの一覧になります。レコードごとに持っているフィールドが違っていても、そのまま違う形で出力されます。ログの一部分を読みたいときには、これがそのまま欲しい形です。

改行は含まないものの長さのある値、たとえば長いクエリー文字列付きの URL などは、およそ 80 文字あたりで折り返されて次の行に続きます。YAML では折り畳まれたプレーンスカラーの改行はスペースとして扱われるため、読み込んだときの値は変わりません。

ファイルを見た目のまま流用したい場合には注意が必要です。値を正確に取り出したいときは、読み込んだ構造から取得するか、JSON の変換を使うほうが確実です。

書き出された YAML には注釈が一切ありません。ソースの NDJSON にコメントを保持する仕組みがそもそもないためです。

一度読んで捨てるファイルであればこれで問題ありませんが、リポジトリにコミットするつもりなら、どのシステムが出力したものか、いつ取得したものかを、先頭に数行書き加えておく価値があります。

空行は読み飛ばされ、ほとんどの書き出しツールが残す末尾の改行も無視されるので、レコード数は空でない行の数と一致します。JSON として解釈できない行があると、そこで変換が止まり、行番号とともにエラーが表示されます。

途中で落ちたプロセスが書いたログの最後の行は、書きかけのまま終わっていることがよくあります。行番号が分かれば、その行を救う価値があるかどうかを判断できます。

ファイルの読み込みも書き出しも、このページの中で、あなたのブラウザーの JavaScript が行います。エンジンのダウンロードもアカウント登録も不要で、変換中のネットワークタブを見れば送信が発生していないことが確認できます。

無料枠は 100 MB までで、ファイル全体が一度メモリーに読み込まれるため、実質的な上限はブラウザータブの側にあります。数万件を人が読むことはまずないので、jq などで先に絞り込んでから変換するのが現実的です。