python-runtime-operations

Python Runtime Operations

概要

すべてのサービス、ワーカー、CLI エントリーポイントは、実際の処理を開始する前に環境を検証し、あらゆる終了経路で適切にシャットダウンし、実行時の動作を可視化できる構造化シグナルを出力する必要があります。 これらは推奨される既定の方法として扱ってください。プロジェクトの制約により変更が必要な場合は変更してもかまいませんが、トレードオフと、それを補う対策を明示してください。

使用する場面

• 処理の開始後に設定が検証されるため、起動時の失敗が遅れて発生する。
• シャットダウン時に接続が開いたままになる、子プロセスが残る、またはトランザクションが未完了になる。
• デッドレターや終端状態の処理がないまま、ジョブの再試行がいつまでも続く。
• ログが構造化されていない、相関 ID がない、またはサービス間で一貫していない。
• ヘルスプローブやレディネスプローブがない、または実態を反映していない。
• シグナル処理（SIGTERM、SIGINT）がない、または競合状態が発生しやすい。

使用しない場面

• プロセスのライフサイクルに関する懸念がない、純粋なライブラリコードやデータモデルコード。
• ビルド、パッケージング、CI/CD パイプラインの設定。
• 実行時の対象範囲を伴わないアルゴリズムやビジネスロジックの設計。

クイックリファレンス

• すべての実行時設定を起動時に検証し、実際の処理を始める前に明確なエラーを表示して速やかに失敗させます。
• シグナルハンドラーを登録し、上限時間を設けたクリーンアップによってグレースフルシャットダウンを実現します。
• 各ジョブシステムで、再試行の上限、バックオフ、デッドレターや終端状態の動作を明示します。
• 一貫した重大度レベルと相関 ID を含む、構造化ログ（JSON）を出力します。
• 実際の依存関係の状態を反映するヘルス、レディネス、ライブネスプローブを公開します。
• 起動レイテンシ、キューの深さ、エラー率、シャットダウン所要時間など、主要な実行時シグナルを追跡します。

よくある間違い

• 設定を遅延検証する — 起動時ではなく、環境変数やシークレットを初めて使用する際に確認するため、実行開始から数分または数時間後に失敗します。
• クリーンアップに上限がない — シャットダウンハンドラーが接続の排出やバッファーのフラッシュをいつまでも待ち続け、クリーンな再起動がプロセスのハングにつながります。
• 再試行の上限到達を記録しない — 失敗したジョブを無期限に再試行し、最終的な失敗をログに記録したり、デッドレターキューに送ったりしません。
• 構造化せずにログを出力する — 本番環境で解析、フィルタリング、相関付けができない、プレーンテキストの print や構造化されていない logging.info の呼び出しを使用します。
• 実態と異なるヘルスプローブ — 下流の依存関係を確認せずにヘルスエンドポイントから 200 OK を返し、連鎖的な障害を覆い隠します。

適用範囲に関する注意

• これらの推奨事項は、よくあるケースでの推奨される既定の方法であり、普遍的なルールではないものとして扱ってください。
• 既定の方法がプロジェクトの制約と衝突する場合や、結果を悪化させる場合は、より適した代替案を提案し、このケースで優れている理由を説明してください。
• 既定の方法から変更する場合は、トレードオフと、それを補う対策（テスト、可観測性、移行、ロールバック）を明示してください。

呼び出しに関する通知

• このスキルが python-design-modularity の名前で呼び出されたことをユーザーに知らせます。

参考資料

• references/runtime-behavior.md
• references/logging-metrics-tracing.md
• references/process-lifecycle-and-cleanup.md