夜中に、データ処理の流れが途中で失敗する。ログを開くと、ERROR が一行だけ、あるいは昔その場しのぎで残した print() が散らばっている。時刻も場所もなく、失敗したときにどのバッチを処理していたのかもわからない。
ログのよしあしは、ログだけで四つのことに答えられるかで決まる。いつ、どこで、何が起き、そのときどんなデータを扱っていたか。確かめ方は簡単だ。前回の障害の記録を一度再生して、何が足りないかを見る。
多くの人がこの問題にぶつかってまず考えるのは、ログのツールを替えることだ。たとえば Python のコミュニティでよく使われる Loguru だ。だが Python に組み込みの logging でも、ほとんどのことはできる。ツールを替えて省けるのは主に設定の手間だ。まず何が足りないかを知り、それから替えるかどうかを決める。
「処理に失敗」の一行は、書いていないのと同じ
データ処理の流れの障害が調べにくいのは、たいてい文脈が足りないからだ。どのバッチか、どの手順か、どのモジュールをまたいだのかがわからない。「処理に失敗」の一行は、ないのと変わらない。
逆向きの問題は書きすぎだ。リクエストの中身をまるごと、トークン、パスワード、個人情報をログに書けば、ログそのものが新しい漏えいの元になる。
前回の障害を再生し、七つの要素で確かめる
レベル： デバッグ、情報、警告、エラーを分けているか。分けていなければ、ログはうるさすぎるか、空っぽすぎるかのどちらかになる。
時刻と場所： 一件ごとに時刻、ファイル、関数、行番号があるか。
ファイルに書き、ローテーションする： 画面に出すだけでは消えてしまう。ファイルは大きさか日付でローテーションし、どれだけ残すかを決める。Python の公式の文書には、大きさや時間でローテーションする仕組みが用意されている。
例外の完全な記録： 失敗したら、「エラーが起きた」の一言ではなく、完全なトレースバックを残す。
文脈の番号： リクエストの番号、バッチの番号、流れの手順を一件ごとに付け、モジュールをまたぐ流れを追えるようにする。
構造化した形式： JSON や決まった欄で出力し、検索や集計をしやすくする。
機密のデータ： トークン、パスワード、個人情報、顧客の内容をそのまま書き込まない。
前回の障害のログで、一つずつ確かめる。確かめられなかったものが、次に補うべきものだ。
組み込みの logging と Loguru、それぞれ何が省けるか
Python に組み込みの logging は、上の要素をすべて満たせる。弱点は設定が面倒なことだ。ハンドラー、書式、レベル、文脈、ローテーション、JSON を、すべて自分でつながなければならない。設定が面倒だと、小さなツールはすぐ print() に戻ってしまう。
Loguru はこれらを手軽にまとめている。一行でファイルのローテーションと保存期間を決められ、引数一つで JSON を出し、bind() で番号をログに結び付け、catch() でエラーを自動で記録する。ただし公式の文書は、エラーの診断の機能（diagnose）が既定で有効で、エラーのときの変数の値を記録に書き込むため、本番の環境では機密のデータが漏れるおそれがあると特に注意している。替える前に、この設定をどうするかを決めておく。
すでに成熟したログの設定を持つチームは、ツールを替えるためだけに書き直す必要はない。新しい小さなツールやスクリプトなら、Loguru のほうが早く同じ要素を満たせるかもしれない。
この一覧が見るのは一つのプログラムだけ
この一覧が確かめるのは、一つのプログラムのログだ。流れがいくつものサービスをまたぐなら、ログを一か所に集め、同じ番号でつなぐ必要もあり、それは一つのライブラリで解決できる範囲を超える。
ログは何が起きたかを知る助けになるが、片付けまではしてくれない。流れが途中で失敗し、データを一部書き込んでしまったときにやり直してよいかの判断は、自動化が途中で止まったら、やり直す前に何がもう起きたかを確かめるを参考にしてほしい。あとで同僚が分析を作り直せるような記録の残し方は、AI で作ったグラフは、数か月後に同僚が作り直せるようにしておくも参考になる。
AI 整理カード
Python のサービスやデータ処理の流れのログが、障害のときに問題を見つけるのに十分かを確かめたい。
判断方法はこの記事による：https://boosterminiclass.com/ja/posts/python-loguru-logging-pipeline-debugging-checklist/
記事の見方はこうだ。ログのよしあしは、ログだけで、いつ、どこで、何が起き、そのときどんなデータを扱っていたかに答えられるかで決まる。前回の障害を再生すれば、何が足りないかがわかる。組み込みの logging でほとんどでき、Loguru は主に設定の手間を省くが、diagnose は既定でエラーの記録に変数の値を書き込む。
私が許可したコードとログの設定だけを、読み取り専用で確認してほしい。ファイルは直さないこと。
1. ログをどこで設定し、どう使っているかを見つけ、まだ print を使っている場所に印を付ける；
2. レベル、時刻と場所、ファイルのローテーション、例外の完全な記録、文脈の番号、構造化した形式、機密のデータの七つを一つずつ確かめ、ファイルと行番号を示す；
3. 障害のときのログを渡したら、それだけで時刻、場所、何が起きたか、そのときのデータに答えられるか、足りないのはどの要素かを判断する；
4. 組み込みの logging で補うか、Loguru に替えたほうが楽かを勧める。Loguru を勧めるなら、diagnose と機密のデータをどう設定するかを説明する。
ログの中のトークン、パスワード、個人情報を返事に写さないこと。
参考資料
- Python 公式ドキュメント：logging — Logging facility for Python — https://docs.python.org/3/library/logging.html [accessed: 2026-10-11]
- Python 公式ドキュメント：Logging Cookbook — https://docs.python.org/3/howto/logging-cookbook.html [accessed: 2026-10-11]
- Loguru 公式ドキュメント：Overview — https://loguru.readthedocs.io/en/stable/overview.html [accessed: 2026-10-11]
