トークンバケット：一瞬の集中と、長く続く流量

容量3・毎秒1個補充のバケットで、瞬間的な集中、枯渇、時間経過、満杯を追い、レートと同時実行数の違いを知る。

ためられる量と、増える速さは別

トークンバケットを、APIへのリクエストを通すためのモデルとして使います。容量Bは3、補充速度rは毎秒1個。最初は満杯で、一件を通すたびに一つ消費するものとします。

容量は短時間の集中を受け止める余裕、補充速度は長く続く流量に関わります。トークンは概念上の残高で、実装で毎秒タイマーを動かして物体を追加する必要はありません。

これは説明用の厳密なモデルです。実サービスの制限が同じ精度で適用されるとは限らず、AWS API Gatewayなどはベストエフォートの目標として説明しています。API Gateway：スロットリング

t=0秒に三件が到着します。各リクエストが一つずつ使い、残数は3、2、1、0と減ります。図では説明のため、補充が起こるほどの時間差はないとしています。

補充速度が毎秒1個でも、既に三つためてあったので三件を通せます。「毎秒1件」という言葉だけでは、この瞬間的な許容量は分かりません。

このモデルは「どんな一秒区間でも、必ず一件以下にする」という制限とは異なります。バケットの容量と補充速度をセットで読みます。

同じ時刻に四件目が来ても、残数は0です。この作品ではキューで待たせるのではなく、そのリクエストを拒否する方式を考えます。

HTTP APIなら 429 Too Many Requests で伝える方法があります。応答にRetry-Afterを付けることもできますが、常に付くとは限りません。利用側はサービスの指示に従い、再試行の間隔も考えます。

「通らなかったら間を空けずに連打する」だけでは、混雑を増やします。RFC 6585：429

追加のリクエストがないまま2秒が経過しました。補充速度が毎秒1個なので、残数は2です。そこへ次の一件が到着します。

一般的には、最後の評価時刻と残数を記録し、経過時間に速度を掛けて補充量を計算できます。時刻の進み方や小数の扱いは実装で決めます。

一定時刻に全利用者の枠を一斉に初期化する固定窓の図ではありません。前の状態から、時間の経過で残高が増えると追ってください。

残数2から一つを消費し、残りは1になりました。残数が足りるか確かめることと、消費を記録することを原子的に行わないと、同時の二つの処理が同じ最後の一つを使えてしまいます。

制限を複数のサーバー全体で共有するなら、共有状態や調整の仕組みも必要です。各サーバーが独立した同じ大きさのバケットを持つだけでは、全体の同じ上限にはなりません。

利用者、APIキー、テナント、IPなど、どのキーで分けるかも設計です。例えばIP単位では、同じネットワークを共有する利用者が一緒の枠になることがあります。

t=2秒で残数1のまま、その後10秒使わなかったとします。計算上は11になりますが、容量3で頭打ちになるため、t=12秒の残数は3です。

補充後の残数 = min(B, 前の残数 + r × 経過時間)

十分な残数があれば、ここからそのリクエストの消費量を引きます。長い時間待った利用者が、無限に大きい瞬間負荷をため込めるモデルではありません。

容量と速度を分けることで、短い集中には余裕を持たせながら、続く流量は抑えられます。

答えはいいえです。容量3で満杯なら、同じ時刻の三件を通せます。一方、枯渇した後に長く続けて通せる量は、補充速度に制約されます。

さらに、流量と同時実行数は別です。毎秒一件でも、一件の処理が100秒続けば、処理中の仕事は積み上がり得ます。実行中の数を抑えるには、別の同時実行制限などを検討します。

トークンをためる箱、時間による補充、処理中の仕事。この三つを別々に描くと、「何を制限して守りたいのか」が具体的になります。