7. ロギング設計
ロギング設計
本章では、本ツールにおけるログの目的、出力先、ログレベル、および 標準出力との役割分担を定義する。
本ツールは CLI ツールであり、 人間が標準出力を見て結果を確認し、ログは問題発生時の調査に使う という役割分離を前提とする。
ロギングの基本方針
- ログは デバッグ・原因追跡用途に限定する
- 標準出力は 処理結果（OK / SKIP / ERROR）のみを出す
- ログと標準出力は 混在させない
ログと標準出力の責務を分離することで、 実行結果の可読性と障害調査のしやすさを両立できる。
ログ出力先
- ログは 標準エラー出力（stderr） に出力する
- ファイル出力は行わない（将来拡張は対象外）
CLI ツールとしてのシンプルさを優先し、 ログファイル管理やローテーションは行わない。
ログフォーマット
ログは以下のフォーマットで出力する。
%(asctime)s %(levelname)s %(name)s %(message)s
ログレベル設計
ログレベルは Python 標準の logging レベルに準拠する。
| レベル | 用途 |
|---|---|
| DEBUG | 内部状態・API リクエスト単位の詳細 |
| INFO | 処理フェーズの開始・終了などの補足情報 |
| WARNING | 想定内だが注意が必要な状態 |
| ERROR | API エラー・処理失敗 |
| CRITICAL | 想定外エラー（即終了） |
DEBUG
- YAML 読み込み結果（構造のみ、内容全文は出さない）
- API 呼び出し種別（list / create など）
- SKIP 判定理由（既存検出など）
DEBUG ログに 認証情報や秘匿情報を含めてはならない。
INFO
-
処理フェーズの区切り
- YAML バリデーション開始／完了
- Book 直下ページ処理開始
- chapters 処理開始 など
INFO ログは 標準出力に出さない補足情報として位置づける。
WARNING
-
許容されたが注意が必要な状態
- 推奨ルール違反だが処理を継続する場合（※将来拡張想定）
-
現行仕様では 基本的に使用しない
現行仕様は fail-fast のため、 WARNING が出るケースはほぼ存在しない。
ERROR
-
API エラー（リトライ失敗含む）
-
入力エラー検出時の詳細ログ
-
標準出力には簡潔な
ERROR:行を出し、 ログには原因を詳細に残す。
CRITICAL
- 想定外エラー
- スタックトレースを含めてログ出力する
CRITICAL ログ出力後は 必ず即時終了する。 例外を握りつぶして処理を継続してはならない。
標準出力との役割分担
| 出力先 | 内容 |
|---|---|
| 標準出力 | OK / SKIP / ERROR の結果通知 |
| ログ | 原因分析に必要な詳細情報 |
この分離により、 通常運用では標準出力のみを見る 問題発生時のみログを見る という自然な使い分けが可能になる。
例外とログの関係
- 例外は必ずログに記録する
- main（CLI）で最終捕捉し、ログ出力後に終了コードを返す
- スタックトレースは 想定外エラーのみで出力する
入力エラーや API エラーは原因が明確なため、 スタックトレースは不要とする。
ログレベルの制御
- デフォルトのログレベルは INFO
- 開発・デバッグ時はコード側で DEBUG に切り替える
CLI オプションでログレベルを切り替える機能は持たない。 運用の複雑化を避けるためである。
設計上のまとめ
- ログは stderr に出力
- 標準出力とは完全に分離
- fail-fast 設計と整合したログレベル構成
- 秘匿情報は 絶対にログに出さない
本ロギング設計は、 「個人利用・再実行可能・ブラックボックス化しない」 という本ツールの思想と整合している。