結論：専用環境と空のDBで、provider非接続の負荷試験だけに使う
Claude Apps Gatewayのload_test_modeは、Gatewayがprovider向けrequestを通常どおり構築・署名しながら送信せず、canned replyを返す負荷試験用の設定です。モデルproviderを呼ばないため、BedrockやClaude Platformの推論経路を測る機能ではありません。Claude Code 2.1.282以降を全replicaへ揃え、load test専用の空のdatabaseを使い、本番利用者から隔離して実行します。
公式設定文書では、既定値の例として約750 tokenを約9.5秒で返す設定を示し、モード有効時は起動warning、inference audit eventのload_test: trueを記録すると説明しています。開発者が利用するGatewayへ有効化すると、すべてのrequestがcanned replyになり、モデルは呼ばれません。性能試験の目的、対象経路、終了時刻、解除担当を先に固定してください。
一次情報はClaude Apps Gateway configuration公式文書とGateway overview公式文書、更新の発表はClaude Code公式changelogです。既存のPostgres接続待ちガイドが起動時のDB接続を扱うのに対し、この記事はproviderを呼ばない負荷試験の隔離境界に絞ります。
測れるものと測れないものを比較する
| 確認対象 | load_test_modeで確認できること | 別試験が必要なこと |
|---|---|---|
| Gateway入口 | 認証、rate limit、request受付、session、応答stream | 実providerのlatency、拒否、model品質 |
| 署名・構築 | provider requestを組み立てて署名する経路 | provider到達後の署名検証、料金、quota |
| 監査 | warning、audit event、load_test: trueの識別 | 本番telemetryとの相関、契約上の保存要件 |
この分離をしないと、「canned replyが返ったのでBedrock接続も正常」と誤判定します。DNS、TLS、OIDC、session token、Postgres、アクセス制御、Gatewayのstream処理を検証したい時に使い、providerのmodel access、region、IAM trust policy、推論時間、出力品質は通常環境の小さな実リクエストで別に確認します。実providerを呼ぶ試験は、予算・個人情報・監査承認を分けてください。
また、load_test_modeは既存spendがあるDBで気軽にONにする設定ではありません。公式文書は、modeを有効にしたGatewayが、developerのspendが既にあるdatabaseに接続すると起動を拒否すると説明しています。spend meterやsession情報を本番DBと混ぜないため、専用の空DB、専用OIDC client、専用DNS、専用の監視dashboardを用意します。
安全な負荷試験の8手順
- 試験目的を固定する。入口の同時接続、stream、auth、DB、rate limitなど、測定項目と合格条件を一文にします。
- versionを揃える。Gateway serverと全replicaが2.1.282以降であることを
claude --versionなどで確認します。 - 環境を分離する。productionのpublic URL、OIDC、secret、database、telemetryへ接続しないload-test環境を作ります。
- 空のDBを用意する。spendやdeveloperの履歴を持たない専用Postgresを使い、接続先を起動ログとsecret参照で確認します。
- 設定をレビューする。
load_test_mode.enabled: true、reply_tokens、reply_seconds、他のupstream、access controlを二人で確認します。 - 小さい試験から始める。canned replyの識別、latency、status、stream終了、audit eventを確認してから同時数を上げます。
- 混入を監視する。ログのwarning、
load_test: true、host、database、client groupを監視し、本番利用者のrequestが来たら即停止します。 - 解除と再起動を検証する。blockを削除して全replicaを再起動し、通常のprovider経路へ戻ったことを一件のreadbackで確認してから試験結果を確定します。
開始前・終了後チェックリスト
- providerへ送らない試験であることを関係者が理解している。
- 2.1.282以降のversionを全replicaで確認した。
- 空の専用database、OIDC、secret、DNS、監視を用意した。
- 本番利用者と本番spendがload-test環境へ流れない。
- canned replyと実provider replyをテストデータ上で識別できる。
- warningと
load_test: trueを保存する。 - 終了時刻、停止担当、rollback、通常経路のreadbackを決めた。
試験結果は「何requestを送れたか」だけでなく、どの層が律速になったかを残します。OIDCの認証時間、session tokenの発行、Postgresのread/write、Gatewayのqueue、canned replyのstream、clientの再試行を分けて計測してください。reply_tokensとreply_secondsを変えた場合は、設定値、同時数、測定結果を同じrun IDへ紐づけます。provider非接続であることがわかるイベントも、成功結果と同じ重要度で保存します。
終了処理では、設定を消しただけで安心しないことが大切です。全replicaの再起動状態、ロードバランサーのtarget、DNS、secret参照、監視アラート、databaseの利用者を順番にreadbackします。通常経路の代表requestを一件だけ確認し、実providerへ送る試験を別承認で行う場合は、今回のload test結果と混ぜずに別レポートへ分けます。
よくある質問と次の行動
load_test_modeでBedrockのIAMも検証できますか？
providerへrequestを送らないため、Bedrockのmodel access、STS、assume_role、region、実際の推論latencyは確認できません。別の低リスク実provider試験が必要です。
本番Gatewayを短時間だけ切り替えてもよいですか？
避けてください。公式文書が「developers useするGatewayへ有効化しない」と警告しており、すべてのrequestがcanned replyになります。
試験設計が大きくなりすぎます。
まず認証・受付・DB・streamの4境界に分け、必要なものだけを順に測ります。Miraigentの無料診断では、Gatewayの変更範囲と停止条件を業務要件から整理できます。
Gatewayの料金表示はGateway料金を実測と一致させるガイド、Postgresの接続待ちはPostgres timeoutの設計ガイド、AWS側のrole境界はBedrock assume_roleのガイドも参照してください。Miraigentの無料診断で、試験環境と本番環境を分ける最小構成を確認できます。