既存のバッチやデータ処理スクリプトを運用に回すとき、設定やログ周りでつまずくことがよくあります。動作は一時的に確認できても、引数の優先順やログ肥大、例外未処理で現場運用が止まる――こうした課題に寄り添い、短時間で改善できる手順とテンプレートを示します。
1) なぜ設定とログが必要か（実務シナリオ）
現場では以下のような場面で設定とログが役に立ちます。
- 運用者がパラメータを変えて再実行したい（CLIを優先）
- CI/CDやコンテナ、cronからは環境変数で制御したい
- 問題発生時に原因追跡しやすいログが必要（処理ID、入力ファイル名、タイムスタンプ）
- ログが肥大化しないようにローテーション管理が必要
2) 設定の設計ルール
明確な優先順位を決めると混乱が減ります。ここでは実務でよく使う順です。
| 優先度 | 取得元 | 想定用途 |
|---|---|---|
| 1 | CLI引数（argparse） | 一時的な上書きやサブコマンド操作 |
| 2 | 環境変数 | CI/コンテナ/cronなどの外部制御 |
| 3 | 設定ファイル（YAML/INI） | 頻繁には変えない運用設定 |
| 4 | コード内デフォルト | 最小限の安全な初期値 |
優先順位をコードに明示的に反映させるとトラブル防止になります（例：CLIが指定されれば環境変数は無視）。
3) argparse の実務テンプレート（サブコマンド含む）
コピー＆ペーストで使える最小テンプレートです。main関数を分離してユニットテストしやすくしています。
実装メモ: コード例は環境に合わせて調整してください。例: import argparse
テストしやすくするポイント：main に argv を渡せるようにしておく（依存注入）。処理本体は別関数に切り出すとユニットテストが容易になります。
4) 設定ファイル（INI/YAML）と環境変数の読み方
簡易例を示します。YAML は可読性が高く運用向けです。環境変数は os.environ.get で取得し、CLIの値があればそちらで上書きします。
実装メモ: コード例は環境に合わせて調整してください。例: import yaml
5) logging の実務設定（コンソール・ファイル回転・フォーマット）
最低限入れるべき情報：timestamp、レベル、処理ID（トレース用）、モジュール・メッセージ。RotatingFileHandler でログ肥大を防ぎます。
実装メモ: コード例は環境に合わせて調整してください。例: import logging
運用のヒント：
- ログレベルは環境別に変える（開発は DEBUG、運用は INFO/WARN）。
- ログメッセージに入力ファイル名・処理IDを入れると問題解析が速い。
- 機密情報はログに書かない。必要なら redaction を入れる。
6) 例外・終了コード・簡単な自己診断（ヘルスチェック）
スクリプトは明確な終了コードを返し、呼び出し元（cron/systemd）で判定できるようにします。軽い健常性チェックで依存先の可用性を確認しておくと安心です。
実装メモ: コード例は環境に合わせて調整してください。例: import sys
終了コードの例：
| 終了コード | 意味 |
|---|---|
| 0 | 正常終了 |
| 1 | 一般エラー（非特定） |
| 2 | ヘルスチェック失敗 |
| 3 | 入力ファイルなどのリソース不足 |
7) 実運用チェックリストとデプロイ例（cron/systemd/コンテナ）
導入後に最低限確認すべき項目を表にまとめます。
| 項目 | 確認内容 |
|---|---|
| 設定優先順 | CLI > 環境変数 > 設定ファイル > デフォルト が実装されている |
| ログ回転 | RotatingFileHandler で maxBytes/backupCount が設定されている |
| ログ形式 | timestamp・level・trace_id・処理名が含まれている |
| 例外管理 | 例外はログに残り、終了コードで判定できる |
| 機密情報 | ログにパスワードなどを吐かないフィルタがある |
| 監視接続 | cron/systemd の再試行、Prometheus による簡易ヘルス検出（任意） |
デプロイ例（概要）：
- cron: 定期実行。ログローテートはアプリ側で行い、stderr/stdout はログにまとめる。終了コードでアラート連携。
- systemd: Restart=on-failure や RestartSec を使って自動復旧を設定。
- コンテナ: 健康チェック（HEALTHCHECK）や liveness/readiness を設定し、ログはコンテナ標準出力に出して別サービスで集約。
失敗しやすい点と回避策（短いチェックリスト）
| 失敗 | 対策 |
|---|---|
| 設定の優先順が不明瞭 | コード冒頭で優先順を明示し、ドキュメント化する |
| ログが大量に溜まる | RotatingFileHandler を導入、DEBUG は必要時のみ有効化 |
| 重要情報がログに残る | ログ出力前に redaction ルールを適用 |
| 例外がハンドルされずプロセスが落ちる | トップレベルで例外をログ化し適切な終了コードで終了 |
想定実装時間（既存スクリプトに適用する場合）
| 作業 | 想定時間 |
|---|---|
| 最低限の argparse + logging 導入 | 30分 |
| 設定ファイル・環境変数対応の実装 | 1〜2時間 |
| 運用チェックリスト適用・監視連携 | 半日 |
まとめ
本記事では、短時間で既存スクリプトを運用に耐える形にするための設計ルールとテンプレートを示しました。学習ゴールに沿って整理すると、以下が実践できるようになります。
- CLI > 環境変数 > 設定ファイル > デフォルトの優先順位設計
- argparse を使った実務テンプレート（サブコマンド対応）
- logging の基本設定、RotatingFileHandler、trace_id を含むフォーマット
- 終了コード・例外ハンドリング・簡単なヘルスチェックの導入
まずは「30分で最低限の argparse+logging 導入」から試してみてください。次回は監視と自動復旧（systemd/コンテナでのリトライ設計）について扱い、運用の自動化をさらに進めます。