python-infrastructure

Python インフラストラクチャ

Python サービスのシステム信頼性に関する懸念事項をまとめています。実際のコードではこれらを組み合わせて使うためです。キューに登録したタスク（バックグラウンドジョブ）には、同じ呼び出し経路での再試行（レジリエンス）と計装（可観測性）が必要です。

スコープの振り分け

必要なこと…	参照先
タスクキューを設計する、定期ジョブをスケジュールする、または非同期ワーカーを実行する（Celery、RQ、asyncio タスクプール）	References/background-jobs.md
何を、どのようなバックオフで、いつまで再試行するかを決める（tenacity のパターン、冪等性、サーキットブレーカー）	References/resilience.md
構造化ログ、メトリクス、トレースを使ってサービスを計装する（structlog、OpenTelemetry、4 つのゴールデンシグナル）	References/observability.md

意思決定ツリー

Operation can fail transiently (network/IO/3rd-party API)?
  -> resilience.md (retry policy)
Operation runs out-of-request (email, image processing, batch)?
  -> background-jobs.md (queue + worker)
Need to know what's happening in production?
  -> observability.md (logs/metrics/traces)
All three at once for one feature?
  -> all three references, in that order.

スキルの適用範囲の境界

• writing-python — 関数の書き方。このスキル — 本番環境で関数をどう存続させるか。
• python-error-handling — どの例外を送出するか。このスキル — ネットワーク境界を越えて例外が送出されたときに何をするか。
• python-resource-management — リソースをどうクリーンアップするか（コンテキストマネージャー）。このスキル — リソースの取得に失敗したときに、どう再試行し続けるか。

注意点

• バックオフなしの再試行は、DoS を増幅させます。 下流サービスの障害時に、N 個のクライアントが即座に再試行すると、トラフィックの急増によって下流サービスの停止が続きます。最初から指数バックオフとジッターをデフォルトにしてください。
• 冪等でない操作を再試行すると、副作用が重複します。 POST の失敗後に再試行すると、二重請求が発生する可能性があります。失敗時の再試行には、必ず冪等性キーを組み合わせるか、その操作を再試行不可として指定してください。
• 非同期ワーカー内の同期コードは、イベントループをブロックします。 asyncio ワーカー内での「高速な」requests 呼び出しでも、スループットが低下します。非同期クライアント（httpx、aiohttp）を使用するか、同期コードをエグゼキューターで実行してください。
• 構造化ログとメトリクスは、異なる対象に役立ちます。 ログは「このリクエストで何が起きたか」に答え、メトリクスは「すべてのリクエストで何が起きているか」に答えます。一方から他方を導き出そうとせず、両方を計装してください。
• キュー境界を越えるトレースコンテキストの伝播には、明示的な配線が必要です。 Celery にタスクを渡すと、トレースコンテキストをタスクヘッダーにシリアライズしてワーカーで復元しない限り、現在のトレースが失われます。「何もしなくても動く」と思い込む前に、OpenTelemetry-Celery のプロパゲーターのドキュメントを確認してください。