「あのとき何が起きた？」 を残す僕のログ術

未来の自分への手紙としてのエラー / イベントログ

「fix bug」

git log --oneline を叩くたびに、その 8 文字が僕を無言で責めます。

半年前の自分が残したコミット。
何を直したのか、なぜ直したのか一切分からない。

そして今、似たようなバグが再発していて、過去の自分が何を考えていたかを知る手がかりが何一つ残っていない。

ログとは、自分が今ここにいた証拠ではなく、未来の自分への手紙だと気づいたのは、この深夜のデバッグからです。

console.log 地獄が生んだ検索できないログ

Hono で個人開発の API サーバーを作っていたとき、エラーハンドリングを後回しにしていた時期がありました。

各ルートに気の向くままに console.log を散らばらせ、エラーが出たらターミナルをスクロールして目視で探す。

問題が起きたときのログはこんな状態でした。

undefined
[Object object]
Error: something went wrong
true

これで「あのとき何が起きた？」が分かるわけがありません。

CloudWatch や Datadog でログを検索しようとしても、キーワードが何もない。
ユーザー ID もリクエスト ID も、エラーが起きたコンテキストも何もない。

ログは残っている。
でも、何も分からない。
記録した気になっていただけで、何も記録していなかったという状態です。

エラーログは不幸の手紙じゃない

Sentry を使い始めた頃、通知が怖くてほとんど見ていない時期がありました。

スマホが振動するたびに「また何か壊れたのか」と胸が締まる。
怖いから見ない。
見ないから溜まる。
溜まるから余計怖くなる。
——悪循環です（汗）

転機は、ログを自分への批判状からシステムからの手紙として読み直したことでした。

エラーログが言っているのは「お前のコードが悪い」ではなく、「ここで、こういうことが起きた」です。

ただ、その手紙が読めるためには、送り手（過去の自分）が読める言葉で書いていることが前提条件になります。

ログの書き方を変えることが、デバッグの速さを変える。
そう気づいてから、僕はログの残し方を少しずつ整えていきました。

未来の自分が検索できるログの 3 つのルール

【ルール 1】 「何が起きたか」 より 「なぜそれが問題か」 を書く

悪いログの典型は、出来事だけを記録していることです。

// ❌ 「何が起きたか」しか分からない
console.error('User not found')

// ✅ 「なぜ問題か」まで分かる
logger.error('User not found: expected authenticated user but session expired', {
  userId: session?.userId,
  requestPath: req.path,
  timestamp: new Date().toISOString(),
})

「User not found」という事実より、「セッション切れで認証済みユーザーが見つからなかった」という状況の解釈が大切です。

3 ヶ月後に同じエラーを見たとき、「User not found」では何も分からない。
でも「session expired」があれば、セッション管理を疑うところから始められます。

【ルール 2】 コンテキストを必ずセットで残す

ログのメッセージだけでは半分しか伝わりません。
「誰が、どこで、何をしていたとき」というコンテキストが必要です。

// ❌ コンテキストがない
logger.warn('Rate limit exceeded')

// ✅ コンテキストがある
logger.warn('Rate limit exceeded', {
  userId: user.id,
  endpoint: '/api/posts',
  limit: 100,
  current: 101,
  windowMs: 60000,
})

コンテキストが揃っていると、ログを見た瞬間に「あの時間帯の、あのユーザーの、あの操作」が特定できます。
検索もしやすくなる。
userId: "abc123" で絞れば、そのユーザーの行動ログが全部出てくる。

【ルール 3】 ログレベルを感情で決めない

怖いエラーは全部 error にしたくなる気持ちは分かります。
でもそれをやると、本当に重大なエラーがノイズに埋もれます。

僕が使っているログレベルの判断基準：

| レベル | 基準 | 例 |
|:--|:--|:--|
| `error` | 人間が今すぐ対応すべき | DB 接続失敗、認証トークン不正 |
| `warn` | 放置すると将来問題になる | レート制限超過、設定値が推奨外 |
| `info` | 正常な動作の記録 | ユーザーログイン、注文完了 |
| `debug` | 開発中にだけ見たい詳細 | SQL クエリ、外部 API レスポンス |

error を乱発すると、Sentry や CloudWatch のアラートが狼少年になって誰も信じなくなります。
逆に warn を適切に使うと、障害の予兆が見えてきます。

【実践】 未来の自分への手紙フォーマット

3 つのルールを実装に落とし込んだ、僕が実際に使っているフォーマットです。