容量の計画と変更

作業内容見出しのリンクをコピー

同時セッション数、worker メモリ、ノード数を計画し、対応する値を変更します。transcript と成果物の固定上限はストレージ契約が正本です。

準備見出しのリンクをコピー

実際のノード allocatable、他の Pod requests、slot limit、workspace 使用量を確認します。transcript のサイズと compaction の有無で復元 peak が異なるため、平均使用量だけを見てサイズを小さくしないでください。

手順見出しのリンクをコピー

1. 復元コストと安全余裕見出しのリンクをコピー

基準は、compaction していない transcript の resume 時の最悪 peak が worker メモリ上限の半分以下であることです。残り半分は、最初の turn の作業、測定していない transcript の形状、エンジンのバージョン差に備える余裕です。

開発用の .env.example は WORKER_MEMORY_MB=2048 を設定しています。そのままでは上記の半分という基準を満たしません。大きな transcript の resume 試験では、その行を削除するか WORKER_MEMORY_MB=4608 に変更します。実際のデプロイ入力で適用される値も確認します。

測定方法見出しのリンクをコピー

比較条件は fake model・cgroup v2 の Compose 環境です。source worker が合成 transcript を mirror に入れ、checkpoint を作って pause します。続いて新しい worker がその checkpoint を復元し、最初の resume turn を実行します。その間、0.5 秒ごとに worker コンテナの cgroup（memory.peak、anon、file、shmem、swap、oom_kill）とプロセスごとの VmHWM を記録しました。memory.peak には回収可能な page cache（file）も含まれますが、基準にも含めました。worker イメージは claude-agent-sdk 0.3.270、Claude Code CLI 2.1.270 です。

4608MiB 上限（現在の既定値）見出しのリンクをコピー

6144MiB 上限（比較測定）見出しのリンクをコピー

表の読み方見出しのリンクをコピー

• worker(bun) は transcript のサイズにかかわらず 440–720MiB を使います。restore を part 単位でストリーミングするためです。
• サイズに比例するのはエンジン（CLI）の使用量です。compaction なしでは、およそ 210 + 1.85 × T MiB を使います（T は transcript の MiB）。511MiB では式の値は 1155MiB、実測は 1129MiB でした。compaction があれば、エンジンの使用量はサイズによらず約 235MiB です。
• 全体 peak は page cache を加えると、150–800MiB の範囲で transcript 1MiB あたり約 3MiB 増加します（150.2MiB で 828MiB、600MiB で 2178MiB、800MiB で 2785MiB）。次の表の 256・400MiB は、この直線で補間した推定値です。

2. transcript 上限とメモリの選択見出しのリンクをコピー

候補となる上限ごとに必要メモリとノードごとのセッション数を比較しました。メモリは 2 × peak を 512MiB 単位で切り上げた値です。セッション数は allocatable 30GiB（30720MiB）のノードを基準としています。標本が小さいため、この表だけで運用環境の上限を決めないでください。

• 512MiB には観測した 12 件のうち 11 件が収まります。二番目に大きい 400.1MiB のセッションも警告に達しません。超えるのは 591.8MiB の一件です。このようなセッションは 409.6MiB で警告を受け、新しいセッションへ移ります。
• 400MiB なら 400.1MiB セッションの checkpoint が直ちに拒否されます。256MiB なら 217MiB セッションも警告範囲に入ります。
• メモリは 4096MiB ではなく 4608MiB です。512MiB の実測 peak 1970MiB に対し、4096MiB の半分（2048）では余裕が 78MiB しかありません。4608MiB なら 334MiB の余裕があります。

3. ノードごとの同時セッション数見出しのリンクをコピー

sessions per node = floor((node allocatable memory - sum of other Pod requests on the node) / worker.memoryMb)

worker 専用ノードグループ（worker.nodeSelector、worker.tolerations）なら、他の Pod は DaemonSet 程度です。30GiB allocatable のノードで DaemonSet の使用分を 0 とすると次のとおりです。

CPU も同じ式で数えます（worker.cpus、既定 1）。通常はメモリが先に埋まります。セッションごとに workspace PVC（worker.workspace.quotaMb、既定 4096MiB）も一つ付きます。復元した transcript（最大 512MiB）は作業ツリー、git objects、restore spool とともにこの中へ収まる必要があります。

local Docker 実行基盤では、一台のメモリを EXECUTION_SLOT_LIMIT（既定 10）個の worker で分け合います。上限は cgroup の制限であり予約ではないため、同時に使い切らなければ合計が超過していても動作します。それでも slot 数 × 4608MiB がマシンのメモリを大幅に超えれば OOM が起きます。

変更方法の選択と対応状況見出しのリンクをコピー

上限（MAX_TRANSCRIPT_BYTES）だけを上げてメモリを据え置くことは推奨しません。compaction なしの大きな transcript の resume が上限に達すると、worker が再起動を繰り返し、セッションが recovery_required になります。上限変更時はこの文書の方法で再測定します。

メモリ値は次の launch から適用され、実行中の worker は置き換わりません。上限を変更する自前ビルドでは API と worker を同じリリースにする必要があるため、アップグレードゲートに従います。

API だけが小さい transcript 上限を使うと、worker では上限以内の checkpoint も finalize が拒否し、transcript_too_large を記録して新しい turn を止める場合があります。API と worker の上限を揃えます。新しい transcript reason を知らない以前の API は報告を 400 で拒否するため、migration → API 全インスタンス → worker の順を守り、その reason を知るビルドまでしか rollback しません。

4. provider 費用と上限の照合見出しのリンクをコピー

使用量と費用の計測で推定・fallback 単価・再認可の境界を確認し、実際の provider 請求と比較します。設置上限の変更・適用には、モデル接続と backend ごとのアップグレード手順に従います。

確認見出しのリンクをコピー

変更前後に同じ checkpoint を新しい worker で復元し、turn 完了、memory.peak、OOM、ディスク、inode、queue wait を比較します。表の数値は記載した SDK・CLI・合成 transcript の条件でのみ観測した値であり、運用環境や新しい runtime の実測の代わりにはなりません。

よくある問題見出しのリンクをコピー

transcript 上限だけを上げてメモリを据え置くと、再起動後に recovery_required になる場合があります。requests を limits より小さくするオーバーコミットと、セッションサイズ別の Pod サイズには現在対応していません。

元に戻す見出しのリンクをコピー

新しい launch に適用するメモリ、slot、ノード数を以前の値に戻します。既存 workspace の byte quota を勝手に変更したり volume を削除したりしないでください。quota 契約の変更は workspace の移行に従います。

次に読む見出しのリンクをコピー

ストレージと上限、メトリクス収集、隔離の説明。