プロダクト開発

ログ出力の設計指針。書き方、フォーマットの例

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

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

この記事で対象としている読者の方

この記事はソフトウェア開発に携わるエンジニアの方を対象としています。私はWebエンジニアなので、Webアプリケーションという文脈でログ出力の設計について書いています。

著者
ぜに/Hiroki Zenigami

Webエンジニア&プロダクトマネージャ←プログラミング教育で起業←東大院←熊本高専。 共著に「現場で使えるRuby on Rails 5」。

目次

ログ出力の設計指針とは

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

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

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

ログ出力の設計指針とは

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

なぜログを出力するのか

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

  1. 問題が発生したときに調査するため
  2. 問題の発生を防ぐため
  3. データ分析をとおしてソフトウェアを改善するため
  4. 監査ログとして利用するため

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

1. 問題が発生したときに調査するため

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

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

2. 問題の発生を防ぐため

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

3. データ分析をとおしてソフトウェアを改善するため

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

4. 監査ログとして利用するため

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

ログ出力の設計指針

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

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

項目内容備考
時間ログを記録した時間年月日時分秒ミリ秒
IDイベントのID一連のイベントを関連づけるために必要
ログレベルログのレベルINFOやWARNなど
ユーザ情報リクエストしたユーザの情報ユーザIDやIPアドレスなど
リクエスト対象どこにリクエストしたかURLなど
処理内容どんな処理を行なったか参照や更新、削除など
処理対象なにを処理したかリソースのIDなど
処理結果処理した結果どうなったか成功または失敗、処理件数など
メッセージその他出力したいこと-

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

ログレベル

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

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

レベル概要説明
FATAL致命的なエラーアプリケーション全体が提供できない
ERRORエラーユーザのリクエストが処理できない
WARN警告アプリケーションは提供できるが対応が望まれる
INFO情報記録しておくべき情報
DEBUGデバッグ情報動作に関する情報
TRACEトレース情報動作に関する詳細な情報

たとえば、状況を確認するのに必要な情報をDEBUGレベルにしてしまうと、INFO以上を表示するときに表示されなくなってしまいます。INFOを見るときはどういう状況か、DEBUGを見るときはどういう状況かなど、読み手を想定して適切にログレベルを設定すべきだといえますね。

なにを記録するか

ログ出力のフォーマットについては上で書きましたが、具体的にどのようなイベントを記録すればよいのでしょうか。たとえば、次のようなイベントについてログに出力します。

  • ユーザが画面上で行うイベント全般
  • 認証やサインアウト
  • アカウント管理、パスワード変更
  • 重要な情報へのアクセス
  • エラーが発生したとき

なにを記録しないか

上で記録すべき情報について書きましたが、逆に記録すべきでない情報もあります。主にセキュリティの観点になるのですが、たとえば次のような情報は記録すべきでありません。あるいはマスク処理を行う必要があります。

  • パスワード
  • OAuthなどの認証情報
  • 個人情報

ログ出力を設計するときに注意すること

ログは問題が発生したときの調査や問題の予防などに役立ちますが、一方でサーバに負荷がかかる行為でもあります。ログを出力することでサーバにパフォーマンス上の問題が起きたときは、出力の設計指針を見直す必要がありそうです。

ログ出力設計のスキルを身につける

ログ出力の設計は、いろんな開発の現場にとって重要なスキルです。実際の現場で開発することで、より高いスキルを身につけることができます。ただ、他の現場に出会うには準備が必要になります。

少しでも他の現場が気になるなら、あらかじめ転職サイト・副業サイトに登録しておくといいです。次の記事で、登録しておくべきサイトについて説明しています。

まとめ

アプリケーションのログを出力することで、問題が起きたときの調査に役立ったり、問題の予防につなげることができます。

ログ出力を設計するときは、読み手がほしい情報を想定して、適切な情報をふくめるとよいですね。ログ出力はサーバのパフォーマンスに影響するので、サーバの監視もあわせて行うべきといえます。

参考文献

著者
ぜに/Hiroki Zenigami

Webエンジニア&プロダクトマネージャ←プログラミング教育で起業←東大院←熊本高専。 共著に「現場で使えるRuby on Rails 5」。

関連記事関連書籍人気記事
applis
エンジニアとしてのんびり暮らす
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは下記よりお願いいたします
お問い合わせ
© applis