structured loggingとは何か? 機械可読なlogの解説

structured loggingとは、logエントリを自由形式のテキスト文字列ではなく、機械可読なキーと値のデータ、通常はJSONとして発行することを意味します。

grepできるlogとクエリできるlogの違いは、構造です。structured loggingは、各logの行を名前付きフィールドを持つデータとして扱い、loggingシステムがスケールでフィルタ、集約、相関できるようにします。これは、logを最後の手段からファーストクラスの分析シグナルへと変える実践です。

テキストlogとstructured log

従来のlogの行は、すべてを一文の散文に詰め込みます。structured logは、同じ情報を、レベル、メッセージ、user ID、所要時間といった離散的なフィールドとして、JSONのような形式で記録します。内容は同じですが、違いは機械が任意のフィールドを確実に取り出せることです。

なぜ構造が重要か

logが構造化されると、正確な問いを立てられます。一人の顧客に関するすべてのエラーを表示する、エラーコード別に失敗を数える、一つの操作の平均所要時間を計算する、など。unstructuredなテキストでは、そうした問いは脆いパターンマッチングを要します。構造こそが、loggingのバックエンドを検索ボックスではなくクエリエンジンにするものです。

一貫したフィールドとコンテキスト

フィールドがサービス間で一貫しているとき、見返りが大きくなります。すべてのlogの行に付与された共有のrequestまたはtrace IDにより、一つのリクエストをコンポーネント間で追え、環境やバージョンのようなプロパティにより、metricをスライスするようにlogをスライスできます。この一貫性が、logs、traces、metrics間の相関を可能にします。

CI/CDにおけるstructured logging

pipelineのステップが、job、commit、runner、結果のフィールドを持つstructured logを発行すると、一度に数千の実行をまたいで検索できます。それにより、jobのlogを一つずつ読んで見つかることを期待する代わりに、多くのbuildにわたって断続的に現れる失敗のパターンを検出することが実用的になります。

採用する

ほとんどの言語には、エンコーディングを代行してくれるstructured loggingのライブラリがあります。主な規律は、フィールド名を一貫して選び、フィールドに高cardinalityや機微な値を避けることです。うまくやれば、structured loggingは採用コストが小さく、インシデントを調査するたびに元が取れます。

重要なポイント

structured loggingは、logを散文ではなくキーと値のデータとして発行します。
logを機械でフィルタ可能かつ集約可能にします。
trace IDのような一貫したフィールドが、シグナル間の相関を可能にします。
CI/CDでは、多くの実行にわたって失敗のパターンを検索できるようにします。