planetscale-traffic-control-recommendations

データベースのトラフィック制御に関する推奨事項

目的

PlanetScale Postgres では、暴走クエリ、トラフィックの急増、バッチジョブ、エージェント、サードパーティ連携から重要なトラフィックを保護するためのトラフィック制御の予算とルールを推奨します。承認を得ずに予算を作成または変更しないでください。

前提条件

このスキルは PlanetScale Postgres に対してのみ実行してください。

ルールを推奨する前に、以下を確認してください。

• 現在の予算とルール。
• Insights のクエリパターン。
• 現在のクエリタグ。
• アプリケーションのルートとジョブ。
• 把握している重要な処理経路。
• 把握しているコストの高い重要度の低い処理経路。
• 発生中のインシデントまたは最近の異常。

クエリタグがない場合は、すぐに対応が必要な既知の問題クエリに対してフィンガープリント固有のルールが明らかに必要でない限り、まずタグ付けを推奨してください。

トラフィックの分類候補

以下を確認してください。

• エクスポート。
• レポート。
• 検索エンドポイント。
• 管理ダッシュボード。
• バックフィル。
• ワーカーとキュー。
• サードパーティシステムからの Webhook。
• BI ツール。
• エージェントが生成する読み取りクエリ。
• 高頻度のポーリング。
• コストの高いことが判明しているクエリフィンガープリント。
• 変動が大きい、顧客がトリガーするエンドポイント。

予算モード

次の順序で推奨してください。

1. 通常のロールアウトでは、まず warn モードを使用します。
2. 警告と誤検知を確認します。
3. タグ、フィンガープリント、しきい値を調整します。
4. 明示的な承認と緊急時のロールバック手段がある場合に限り、enforce に移行します。

インシデントが発生中で、オペレーターが緊急の緩和策を明示的に求めている場合を除き、最初から enforce を使用することは推奨しないでください。

ルールの方針

タグが安定しており、値の範囲が限定されている場合は、タグベースのルールを優先してください。

• source=agent
• source=bi
• feature=export
• feature=report
• route=/admin/reports
• job=DailyBackfill
• service=analytics-worker

以下の場合は、フィンガープリントルールを使用してください。

• 特定の既知のクエリパターンが危険な場合。
• タグ付けが欠落している、または信頼性が低い場合。
• クエリの発生元を特定するのが難しい場合。

実質的に異なるトラフィックの種類ごとに、個別の予算を設定してください。

無関係なトラフィックを1つの予算にまとめないでください。誰が予算を消費しているかが分かりにくくなります。

推奨するデフォルトの予算

以下は推奨パターンとして使用し、そのまま適用しないでください。

エージェント用予算

対象：source=agent または source=mcp のタグが付いたクエリ。

目的：エージェントがアプリケーションのトラフィックを圧迫するのを防ぎます。

モード：まず warn を使用します。

推奨事項：エージェントはレプリカと読み取り専用スコープを優先する必要があります。書き込みには人間の承認が必要です。

エクスポート／レポート用予算

対象：feature=export、feature=report、または特定のレポートルート／ジョブ。

目的：顧客がトリガーするレポート処理によって、データベースリソースがすべて消費されるのを防ぎます。

モード：まず warn を使用し、監視後に enforce を検討します。

バックグラウンドジョブ用予算

対象：ワーカーサービス、キュー、またはジョブのタグ。

目的：バックフィルと再試行によって、対話型トラフィックが圧迫されるのを防ぎます。

モード：まず warn を使用します。キューのバックプレッシャーの動作を確認してから、enforce に移行してください。

サードパーティ連携用予算

対象：source=integration、パートナーごとに値の範囲を限定したタグ、または受信連携呼び出しのルートテンプレート。

目的：予測できないパートナーの動作を分離します。

モード：まず warn を使用します。

既知のフィンガープリント用予算

対象：特定のコストの高いクエリフィンガープリント。

目的：コードまたはスキーマの修正を進める間、既知の異常なクエリを封じ込めます。

モード：緊急時を除き、まず warn を使用します。

「タグの値ごとに適用する」方針

PlanetScale が選択したタグの一意な値ごとに別々の予算を適用できる場合は、以下のように値の範囲が限定されたタグでの利用を推奨してください。

• application
• service
• 正規化されている場合の route
• job
• feature
• source

ユーザー ID、リクエスト ID、生のテナント ID、メールアドレス、UUID、生の URL など、値の範囲が限定されていないタグでは推奨しないでください。

含めるべき制限事項と注意点

すべての推奨事項で、次の点を説明する必要があります。

• Traffic Control はリソース使用量を制限しますが、クエリのチューニングに代わるものではありません。
• ウェブアプリケーションファイアウォールではありません。
• アプリケーションレベルのレート制限に代わるものではありません。
• 制限はガードレールであり、あらゆる障害モードにおける厳密な保証ではありません。
• 不適切なタグは、不適切なルールを生みます。
• 強制モードではクエリが拒否され、アプリケーションの動作に影響する可能性があります。

出力形式

提案する予算ごとに、次の項目を記載します。

• 予算名。
• 対象ブランチ。
• モード：off、warn、または enforce。
• マッチしたトラフィックの範囲。
• ルールタイプ：タグ、フィンガープリント、キースペース、クエリ種別。
• 提案するタグまたはフィンガープリント。
• 制限の根拠。
• 根拠となる Insights で確認されたクエリ。
• 安全性のリスク。
• テスト／監視計画。
• ロールバック計画。
• 承認要件。

最後に、次の文を記載します。

「Traffic Control の予算やルールは、作成、更新、削除、強制のいずれも行っていません。」