ログ出力を設計するときのフォーマットの例やメッセージの書き方

本サイトはアフィリエイトプログラムを利用した広告を表示しています

ソフトウェアを開発する上でしっかりと設計しておきたいのがログの出力です。私は以前、運用しているウェブアプリケーションのログ出力のフォーマットが不十分だったため、問題が起きたときに原因の調査ができなかったという苦い経験があります。そのときから、ログの出力の設計について気をつけるようにしています。

この記事ではログの出力を設計する方法について、フォーマットやメッセージの書き方を例をもとに解説します。ログを設計するときの参考になればうれしいです。

ログの設計についての記事を書きました

Software Design 2023年2月号の中で、ログの設計に関する特集記事を執筆しました。詳しくは、次の記事をご覧ください。

Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

ログ出力の設計指針とは

まず、ログとは「アプリケーションやサーバ、ソフトウェアなどが出力する、時系列に記録されたデータ」のことをいいます。例えばアプリケーションが出力するログやデバッグログ、ウェブサーバのアクセスログやエラーログなどがあります。

これをふまえて、ログ出力の設計指針とは、アプリケーションなどのログの出力をどう設計するかという指針のことをいいます。

ログの種類によって、出力の設計指針は変わってくると思います。この記事では、いろんなログに共通する汎用的な内容として、アプリケーションログの出力を例に設計指針について書いていきます。

ログ出力の設計指針は、開発するソフトウェアによっても変わってきます。重要なことは、チームで指針をもってログ出力を行い、しっかりと運用していくことだと思います。

これからログ出力の設計指針について書いていくのですが、そもそもなぜログを出力する必要があるのでしょうか。これは、大きく次の4つがあると考えられます。

ひとつずつ見ていきます。

ウェブアプリケーションを運用していると、サーバがダウンしてしまったり、レスポンスが遅くなったりすることがあります。こういった問題が発生したときに、発生した時間のログを見ることで、原因が分かったりします。

また、ユーザーに問題が起きたときにも役立ちます。ユーザーから問い合わせがあったときに、ユーザーのアカウント情報と突き合わせて調べることで、ユーザーに起きた問題の原因が分かることがあります。

問題が起きていなくても、問題が起きる予兆があったりします。例えば同一のIPアドレスから連続してアクセスを受けることがあります。このときにIPアドレスに対する制限を行うなどすることで、問題の発生を防げることがあります。

ログは、ソフトウェアを改善するためにも役立ちます。ユーザーの行動を分析して学習し、機能や施策につなげることでユーザー体験を向上することができます。

例えばPCI DSSというセキュリティ基準では、監査ログを最低3ヶ月間は保管しなければならないとしています。ソフトウェアによっては、こうした基準を満たすためにログを出力する必要があったりします。

それでは、具体的にどうログ出力を設計すればよいのでしょうか。まず前提として、「ログには読み手がいる」ということを意識します。どういうケースで、どういう読み方を想定しながらログ出力を設計することが重要といえます。

ログ出力は、5W1Hにもとづいて設計するとよいといわれています。例えば、次のような項目をログに出力するようにします。

ログ出力のメッセージは、できるだけシンプルに書くことで読み手に伝わりやすくなります。また、エラーが発生したときはスタックトレースを出力することで調査しやすくなります。

上で書いた項目の中にログレベルというものがあります。これはINFOやWARNなど、そのログのレベルを表します。

ログ出力にはログレベルを書くケースがほとんどだと思います。ログレベルは、読み手がほしい情報を適切に伝えるために役立ちます。ログレベルには、例えば次のような種類があります。