メインコンテンツへスキップ

新規ページ

ロギング設計

本章では、本ツールにおけるログの目的、出力先、ログレベル、および 標準出力との役割分担を定義する。

本ツールは CLI ツールであり、 人間が標準出力を見て結果を確認し、ログは問題発生時の調査に使う という役割分離を前提とする。

ロギングの基本方針

  • ログは デバッグ・原因追跡用途に限定する
  • 標準出力は 処理結果（OK / SKIP / ERROR）のみを出す
  • ログと標準出力は 混在させない

ログと標準出力の責務を分離することで、 実行結果の可読性と障害調査のしやすさを両立できる。

ログ出力先

  • ログは 標準エラー出力（stderr） に出力する
  • ファイル出力は行わない（将来拡張は対象外）

CLI ツールとしてのシンプルさを優先し、 ログファイル管理やローテーションは行わない。

ログレベル設計

ログレベルは 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 設計と整合したログレベル構成
  • 秘匿情報は 絶対にログに出さない

本ロギング設計は、 「個人利用・再実行可能・ブラックボックス化しない」 という本ツールの思想と整合している。

上に戻る