深夜のデスクで、ログの画面を見ながら手がかりを探して考え込んでいる開発者
テスト・品質約19分

AIにログ出力の不足を指摘させる｜障害調査で困らない設計

「昨日の夕方、注文が通らなかったお客様がいるそうです」

朝いちばんにそう言われて、ログを開く。該当しそうな時間帯までさかのぼって、目で追って、そして手が止まります。残っているのは、エラーが発生しました の1行だけ。

誰の注文なのか。どの処理まで進んでいたのか。何を渡して、何が返ってきたのか。どれも書いてありません。調べる気がないわけではなく、調べるための材料が、その場に残っていなかっただけです。

ログは、動いているときはほとんど誰も見ません。見るのは、困ったときだけです。だから「足りているか」は、いつも足りなかったと分かった後に判明します。

この記事では、その順番をひっくり返す方法——AIにログの不足を先に指摘させる進め方を整理します。コードを書き直す話ではありません。いま出しているログで、昨日の障害を説明できるかを確かめる話です。

結論：見るのは3つだけです。①たどる——1件の処理を、入口から出口まで1本の線でつなげるか。相関ID（同じ処理に付けて回す1つの目印）が入っていないと、ここで止まります。②わかる——ログ1行から、いつ・誰の・何の処理が・どうなったかが復元できるか。③出さない——個人情報・秘密情報・巨大なデータを、ログに書かないと決められているか。

覚え方は たどる → わかる → 出さない。①がないと②をいくら足しても線にならず、③を後回しにすると、増やしたログがそのままリスクになります。

そしてAIに頼むときのコツは1つ。「ログを足して」と頼まないことです。そう頼むと、関数の入口と出口すべてに1行ずつ、という案が返ってきます。量は10倍になり、調査は逆に遅くなります。頼むのは、「この障害を再現なしで説明するには、どの情報が足りないか」です。

全部を今週やる必要はありません。①の相関IDを1つ通すだけでも、次の調査の景色が変わります。

何が起きているのか——ログは「書いた人」の視点で残ってしまう

同じ番号札を付けた荷物が受付から配達まで一本の道を進む場面、1枚のメモを読んで納得している場面、書類の一部を目隠しシールで隠してから箱に入れる場面を並べた図
ログを見直す順番。たどる→わかる→出さない。①がないと②を足しても線にならず、③を後回しにすると増やしたログがリスクになる

打ち手の前に、なぜ足りなくなるのかを整理します。原因が分かっていると、AIに渡す前提も書きやすくなります。

1つ目は、ログを書くのが「実装している最中」だということ。実装中は、自分がいま何をしているか全部わかっています。だから 処理開始 の3文字でも困りません。困るのは、半年後に、別の人が、状況を知らないまま読むときです。ログの不足は、腕前の話ではなく、書く時点と読む時点で持っている情報が違うという話です。

2つ目は、成功したときのログばかり残ること。ハッピーパス（うまくいく道筋）はテスト中に何度も通るので、自然とログも整います。一方、めったに通らない分岐は、通らないまま本番に出ます。調査で見たいのは、まさにその通らなかった側です。

3つ目は、例外の情報が途中で削れること。catch したあと、ログ.error("失敗しました") とだけ書いて、元の例外を渡し忘れる。よくある形です。スタックトレース（どこで落ちたかの経路）が消えると、原因の場所そのものが分からなくなります（AIにエラーハンドリング方針を相談する｜握りつぶさない設計）。

4つ目は、多すぎて読めないこと。足りないのと同じくらい厄介なのが、多すぎるログです。1リクエストで数百行出ていると、必要な1行がその中に埋もれます。しかも保存料金がかさむので、「量を減らそう」という話になり、大事な行まで一緒に消えたりします。

5つ目は、処理が分かれていて線にならないこと。画面、API、非同期のワーカー、外部サービス。ログはそれぞれの場所に、それぞれの時刻で残ります。同じ処理だと分かる目印がないと、突き合わせは人の勘に頼ることになります（AIに非同期・並行処理を書かせる｜競合とデッドロックの確認）。

6つ目は、AIに頼むとまさに量が増えること。「ログが足りないので足してください」と頼むと、律儀に全関数へ入口・出口のログを入れてくれます。動きますし、レビューでも指摘しにくい。でも調査は速くなりません。AIが悪いのではなく、「調査で何を知りたいか」を渡していないからです。ここは前提の渡し方でほぼ決まります（AIにコードを書かせる前に渡す前提と制約｜伝え方の型）。

裏を返せば、これは注意力の問題ではなく、見る順番の問題です。順番が決まっていれば、AIはかなり役に立つ相談相手になります。

具体例——つい、こうなりがちという形

どれも「まず動くものを」という自然な流れから生まれます。心当たりのある行があれば、そこだけ見れば十分です。

影響——「調査できない」は、静かにコストになる

急いで全部直さないと危ない、という話ではありません。ただ、出方が地味で、出たときに時間を持っていかれる種類の問題なので、書いておきます。

少し安心できる話をすると、この領域は費用対効果がはっきりしています。作り替えは要りません。相関IDを1つ通して、ログの形を揃えるだけで、次の調査は目に見えて楽になります。

明日からやること（たどる・わかる・出さない）

上から順に、小さく始められます。今日は①だけで構いません。

1. たどる——1件の処理を、1本の線にする

ここを飛ばして情報量だけ増やしても、点が散らばるだけです。逆に、ここさえ通れば、後の作業は楽になります。

2. わかる——1行から、状況が復元できるようにする

情報を足す工程ですが、足すのは「行数」ではなく「1行の中身」です。

3. 出さない——書いてはいけないものを、先に決める

②で情報を増やすなら、③は同時にやります。順番を逆にすると、消す作業が発生します。

AIに相談するときのプロンプト（コピーして使えます）

前提を渡さないと、AIは素直に「全関数にログを追加」を出してきます。調査の場面を先に渡すのがコツです。

いま動いているコードのログ出力に不足がないかを点検したいので、相談に乗ってください。目的は量を増やすことではなく、障害調査を速くすることです。

①まず、この処理で起こりうる失敗を、思いつく限り挙げてください（入力不正、外部サービスの失敗・遅延、権限不足、データ不整合、タイムアウト、想定外の状態など）。
②その失敗が実際に起きたとき、いまのログだけで原因を説明できるかを1件ずつ判定し、説明できないものだけ「何の情報が足りないか」を書いてください。
③「すべての関数の入口と出口にログを足す」案は出さないでください。読む量が増えて調査が遅くなるためです。足すなら、失敗の分岐と外部との境界に絞って提案してください。
④1件の処理を最初から最後まで追えるか（相関IDが引き継がれているか）を確認し、切れている箇所を指摘してください。とくに非同期処理・キュー・外部呼び出しの前後を見てください。
⑤ログに出してはいけない情報が混ざっていないかを指摘してください（個人情報、認証情報、リクエスト本文の全文など）。
⑥逆に、多すぎて減らしてよいログがあれば挙げてください。
⑦最後に、この点検では分からないことを正直に挙げてください。

なお、確実でない部分は「不明」と書いてください。埋めなくて構いません。

対象の処理：（　）　言語・ログの仕組み：（　）　外部連携：（　）　実際に起きた障害（あれば）：（　）

```
（対象のコードと、いま出ているログの実例を貼る。個人情報・鍵は外してから）
```

③と⑥が効きます。「増やすな」と「減らせ」を同時に言うと、返ってくる指摘がぐっと実務的になります（設計レビューの見落としをAIに洗わせる｜プロンプトの型）。

もうひとつ、実際に効く使い方があります。過去に起きた障害を1件持ってきて、そのときのログだけをAIに渡し、「これで原因を説明できますか」と聞く。説明できないと返ってきたら、その「足りない」がそのまま改善リストです。仮の話より、実際に困った1件のほうが、はるかに正確に不足を炙り出せます。

出てきた指摘は、次の3点だけ自分の目で確かめます。（1）相関IDが本当に非同期の先まで届いているか、（2）例外がスタックトレースごと残っているか、（3）増やそうとしているログに、出してはいけない情報が混ざっていないか。この3点は、もっともらしい説明で埋まっていても抜けていることがあります（AIにコードレビューの一次チェックを任せる｜範囲と注意点）。

ログを見直すチェックリスト（コピーして使えます）

全部に○が要るわけではありません。気になった行だけで十分です。

① たどる

② わかる

③ 出さない

この記事のまとめ

ログの不足は、書いた人の腕前ではなく、書く時点と読む時点のズレから生まれます。だから、実装中に気をつけるより、あとから点検して埋めるほうが確実です。

見るのは3つ。①たどる——相関IDを1つ通して、非同期の先まで引き継ぐ。②わかる——1行の中身を揃え、失敗の側を厚くし、例外はスタックトレースごと1回だけ出す。③出さない——出してはいけない情報を具体名で決め、マスクを共通の場所に寄せる。

AIに頼むときは、「ログを足して」ではなく「この障害を説明できるか」と聞く。そして「全関数に入口と出口のログを足す案は出さないで」と先に一言添える。それだけで、返ってくる指摘の質が変わります。

朝のオフィスで、画面を指しながら同僚と落ち着いて話している開発者

ログが足りなかった朝、たぶん「なんで自分は書いておかなかったんだろう」と思ったはずです。でも、実装していたときのあなたは、その障害をまだ知りませんでした。知らないことは、書けません。

ログは、一度で完成させるものではありません。困るたびに1か所ずつ厚くしていくものです。今回困った場所は、次の人が困らない場所になります。

今日は、直近で調べにくかった障害を1件だけ思い出して、「あのとき何が残っていれば早かったか」を1行書いてみる。それだけで、次の朝のログは、少し親切になっています。

よければ、こちらも

関連用語