ログ設計

ログ設計とは

ログは、アプリケーションがいつ・どこで・何をしたかを記録した時系列の証跡です。障害が起きたとき、開発者が頼れるのは基本的にログだけ — 「何を・どう残すか」を決めるログ設計は、地味ながらシステムの調査可能性を左右する重要な仕事です。

行き当たりばったりの print 出力ではなく、ロギングライブラリを使ってレベル・形式・出力先を揃えるのが出発点です。

ログレベル — 重要度で仕分ける

ログにはレベル(重要度の段階)を付け、環境ごとに出力する下限を切り替えます。

レベル	用途	例
ERROR	処理が失敗し対応が必要	決済APIの呼び出し失敗
WARN	失敗ではないが要注意	リトライで回復した・非推奨機能の使用
INFO	正常系の重要イベント	起動完了・注文の受付
DEBUG	開発時の詳細情報	変数の中身・分岐の通過

本番は INFO 以上、開発中は DEBUG まで、が典型的な設定です。ERROR を乱発すると本当の異常が埋もれるため、「その事象は本当に対応が必要か」でレベルを選びます。

構造化ログとコンテキスト

近年の標準は構造化ログ([[JSON]] などの機械可読な形式)です。文章ではなくフィールドで記録することで、検索・集計が容易になります。

{"time":"2026-07-27T02:00:01Z","level":"ERROR","msg":"payment failed","order_id":"o-123","request_id":"req-abc"}

特に重要なのが リクエストID(相関ID)です。1つのリクエストに一意なIDを振り、全ログに付与しておくと、「この注文の処理がどこで失敗したか」を一本の線として追跡できます。[[オブザーバビリティ]] の分散トレーシングにつながる考え方です。

出してはいけないもの

ログは長期間保存され、多くの人の目に触れます。次の情報は記録してはいけません。

パスワード・APIキー・トークンなどの秘密情報
クレジットカード番号などの決済情報
個人情報(必要な場合はマスキングする)

「ログに書いた瞬間、その情報は平文でディスクに残る」と意識しましょう。

初学者向けポイント

ログはファイルや標準出力に出し、収集基盤へ集約するのが現代の構成です。[[Linux]] なら journalctl や /var/log を見る習慣をつけましょう
エラーログには原因調査に必要な文脈(何のIDを処理していたか、入力は何か)を含めます。「Error occurred」だけのログは無いのと同じです
ログは [[監視とアラート]] の入力にもなり、[[インシデント対応]] では時系列整理の主資料になります

関連技術とのつながり

[[オブザーバビリティ]] — ログはメトリクス・トレースと並ぶ三本柱の一つ
[[監視とアラート]] — ERROR ログの発生数はアラートの定番条件
[[Linux]] — ログファイルの置き場所と閲覧コマンドは運用の基本
[[インシデント対応]] — 障害の時系列整理はログが主資料
[[マイクロサービス]] — サービスをまたぐ処理は、共通のリクエストID付きログでしか一本の線として追えない
[[エラーハンドリングとリトライ設計]] — 失敗と再試行の記録はログ設計と対で決める

Q: ログレベルの使い分けとして適切なのはどれ?
- [ ] すべてのログをERRORで出力して目立たせる
- [x] 対応が必要な失敗はERROR、正常系の重要イベントはINFOと重要度で分ける
- [ ] 本番環境ではログを一切出力しない
解説: レベルは重要度による仕分けです。ERROR の乱発は本当の異常を埋もれさせます。

Q: 構造化ログの利点はどれ?
- [ ] ファイルサイズが必ず小さくなる
- [ ] 人間にしか読めない形式になりセキュリティが上がる
- [x] フィールド単位で記録され、検索・集計がしやすくなる
解説: JSON などの機械可読な形式で出すことで、リクエストIDでの追跡や集計が容易になります。

Q: ログに記録してはいけない情報はどれ?
- [x] パスワードやAPIキーなどの秘密情報
- [ ] リクエストID
- [ ] エラーの発生時刻
解説: ログに書いた秘密情報は平文でディスクに残り続けます。秘密情報・決済情報・個人情報は出力禁止です。