
# isolate のスケーリング

ポートを担当する isolate の数は、サーバーの実行中に変えられます。アプリケーションは `IsolateScaler` Bean を通して変えます。`server.isolates.scaling: auto` のときは、ポリシーも `min` と `max` の間で変えます。

このページは [isolate のプール](isolates.md) を前提にしています。そこで isolate ごとの状態について述べたことは、後から追加された isolate にもすべて当てはまります。

## 使う理由

負荷は一日中同じではありません。ショップは、セールの一時間には八つの isolate が必要で、夜には二つで足ります。各 isolate は独自の Bean をメモリーに持つので、誰も必要としない isolate は、誰も使わないメモリーです。

isolate の追加には、アプリケーションの起動と同じだけ時間がかかります。そして削除のときに、応答中のリクエストを打ち切ってはなりません。プールはその両方を行います。新しい isolate は準備ができてから応答し、離れる isolate は先にリクエストを完了させます。

## 例

```yaml
# lib/resources/application.yml
server:
  isolates:
    count: 2
    min: 2
    max: 8
```

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

@RestController()
class Operations {
  Operations(this.isolates);
  final IsolateScaler isolates;

  // セールが始まる前に。このパスは保護すること: 下記を参照。
  @PostMapping('/internal/scale')
  Future<int> scale(@RequestParam() int to) => isolates.scaleTo(to);
}
```

```console
$ curl -X POST 'localhost:8080/internal/scale?to=8'
8
```

```text
INFO  Scaling 2 → 8 isolates (manual, asked in isolate-1)
INFO  Isolate isolate-2 ready in 0.398 seconds
...
```

リクエストはどの isolate が受け取ることもあります。プールは最初の isolate にあり、他で求められたステップはそこで行われます。ログには、どこで求められたかが出ます。

## IsolateScaler

Bean `isolateScaler` は、サーバーにプールがあるときに存在します。つまり、`server.isolates.count` が 1 より大きい (または `auto`)、`server.isolates.scaling: auto`、または `server.isolates.max` が 1 より大きいときです。そのとき、プールのすべての isolate にあります。最初の isolate ではプールそのもの、他の isolate ではステップをプールに渡す Bean です。

| メンバー | 意味 |
|---|---|
| `count` | 今応答している isolate の数。最初の isolate を含む。ドレイン中のものはもう数えない |
| `min` | `scaleTo` が下げる最小の数 (`server.isolates.min`、少なくとも 1) |
| `max` | 上げる最大の数 (`server.isolates.max`) |
| `Future<int> scaleTo(int count, {String reason})` | プールを `count` 個の isolate にし、応答している数で完了する |
| `Future<int> scaleBy(int delta, {String reason})` | `delta` 個の isolate を追加する。負の値なら削除する |

ルール:

- **数は `min` と `max` の間に保たれます。** `scaleTo(0)` は `min` に、`scaleTo(100)` は `max` になります。どちらもエラーではありません。何が行われたかは、応答を読んでください。
- **最初の isolate は決して削除されません。**
- **`reason` はログのためのものです。** 指定しなければ `Scaling 2 → 4 isolates (manual)` です。最初の isolate 以外で求められたステップには、場所が加わります: `(manual, asked in isolate-2)`。
- **ステップは一つずつ順に実行されます。** 別のステップが進行中に呼ばれた `scaleTo` は、それを待ちます。
- **future はステップが終わったときに完了します。** 新しい isolate の準備ができ、削除された isolate が終了した (リクエストが完了したか、`server.isolates.drain-timeout` が過ぎた) ときです。
- **起動に失敗した isolate は除外されます。** そのとき応答は求めた数より少なくなり、失敗はログに出ます。
- サーバーが待ち受けを始める前と、コンテキストが閉じた後は、`scaleTo` は何も変えず、現在の数を返します。
- 一つの isolate を超えてスケーリングするには、アプリケーションが [再び起動できる](isolates.md#アプリケーションは再び起動できなければならない) 必要があります。そうでなければ `scaleTo` は失敗します。

### すべての isolate で使える

リクエストはどの isolate にも届くので、スケーラーはすべての isolate で機能します。最初の isolate 以外で求められた `scaleTo` は、最初の isolate のプールに送られ ([`PrimaryIsolate`](../../spring-core-dart/isolates/primary-isolate.md) を通して、ハンドラーは `isolates.scale`)、その応答で完了します。

- 他の isolate では、`count`、`min`、`max` は最初の isolate が最後に知らせた値です。最初の isolate は、各ステップの後と、isolate が加わったり終了したりしたときに、すべての isolate に知らせます。
- **スケーリングするエンドポイントは保護してください。** それを呼べる人は、サーバーがどれだけのメモリーといくつのコアを使うかを決められ、isolate をドレインすることもできます。公開のパスから外し、セキュリティスターターのルールの背後に置いてください。
- **リクエストハンドラーでスケールダウンのステップを await しないでください。** スケールダウンのステップはいちばん新しい isolate を削除しますが、そのリクエストを受け取ったのがその一つかもしれません。その isolate は終了する前にリクエストを完了させ、ステップはそれが終了したときに完了し、リクエストはステップを待ちます。どちらもタイムアウトまで動きません。ステップを開始して、すぐに応答してください。

```dart
@PostMapping('/internal/scale')
ResponseEntity<void> scale(@RequestParam() int to) {
  unawaited(isolates.scaleTo(to)); // dart:async
  return ResponseEntity.accepted().build();
}
```

### プールがなければ IsolateScaler もない

`count: 1`、`scaling: manual` で、1 より大きい `max` がなければ、ポートは共有されず、後から何も追加できません。`isolateScaler` Bean はなく、それを必須とする Bean は起動を止めます。一つの isolate でも動くアプリケーション (開発、テスト) は、それをオプションとして受け取ります。

```dart
Operations(this.isolates);
final IsolateScaler? isolates; // プールがなければ null
```

一つの isolate で起動して手でスケーリングするには、`max` を設定します。

```yaml
server:
  isolates:
    count: 1
    max: 4
```

## 追加と削除

**追加** は、新しい isolate を起動します。一つのステップの分はすべて同時です。それぞれがアプリケーション全体を実行し、自分の Bean が立ち上がったときにポートに加わるので、準備のできていない isolate にリクエストが送られることはありません。番号は空いているものが使われます。`isolate-2` が離れた後、次に追加される isolate は再び `isolate-2` です。

**削除** は、いちばん新しい isolate、つまり番号の大きいものを対象にします。それぞれがドレインされます。

1. 接続の受け付けを止めます。新しい接続は他の isolate が受け取ります。
2. 応答中のリクエストを、停止するアプリケーションと同じように完了させます ([シャットダウン](shutdown.md) を参照)。
3. そのイベントストリームと WebSocket セッションが閉じられます。クライアントは再接続し、別の isolate に届きます。
4. その `@PreDestroy` メソッドが実行され、終了します: `Isolate isolate-3 stopped`。

`server.isolates.drain-timeout` (30 秒) を過ぎても終了していない isolate は、警告とともに、それでも停止されます。

```text
Isolate isolate-3 did not stop within 30 seconds (server.isolates.drain-timeout): stopped anyway
```

isolate がメモリーに持っていたものは、一緒に失われます。メモリー上のセッションも、キャッシュされた値もです。

## 自動スケーリング

```yaml
server:
  isolates:
    count: 2
    scaling: auto
    min: 2
    max: 8
```

```text
INFO  Scaling the isolates automatically between 2 and 8 (LagScalingPolicy)
...
INFO  Scaling 2 → 3 isolates (auto: lag 14.2 ms, 180 in flight)
```

プールは二秒ごとに isolate に状況を問い合わせ、その答えをスケーリングのポリシーに見せます。ポリシーは、望む isolate の数を答えるか、何も答えません。プールはその答えを `min` と `max` の間に保ちます。そして、ポリシーによるものでも手によるものでも、スケーリングのステップの後は、`server.isolates.cooldown` だけ待ってから再びポリシーに尋ねます。

- `count` はプールの開始時の数です。ポリシーはそれより下、`min` まで下げることがあります。常に応答していなければならない数を `min` に設定してください。
- `max` が未設定なら、プロセッサーコアの数です。`count` のほうが大きければ `count` です。
- `IsolateScaler` はこれまでどおり機能します。アプリケーションとポリシーがプールを共有します。
- 失敗した確認はログに記録され (`The scaling of the isolates failed`)、次の確認が試みられます。

### デフォルトのポリシー: 遅れによる判断

`LagScalingPolicy` は、isolate がどれだけ遅れているかで判断します。isolate は一度に一つのことを行います。追いついている間は、タイマーは時間どおりに発火します。応答するより速くリクエストが届くと、リクエストは列を作り、イベントループが遅れます。その遅れが [遅れ (lag)](../../spring-core-dart/isolates/load.md#遅れと-busy-の計測方法) で、ポリシーは isolate 全体でのその平均を読みます。

| ステップ | タイミング | 結果 |
|---|---|---|
| アップ | 平均の遅れが `scale-up-after` (5 秒) の間、`scale-up-lag` (5 ms) 以上のままである。一度でもそれを下回る確認があると、待ちは最初からになる | isolate を今の半分だけ増やす: 1 → 2 → 3 → 5 → 8 |
| ダウン | 平均の遅れが `scale-down-after` (2 分) の間、`scale-up-lag` の四分の一未満のままで、プールが `min` より大きく、isolate が一つ少なくてもリクエストが収まる | isolate を一つ減らす |
| どちらでもない | 遅れが `scale-up-lag` の四分の一と `scale-up-lag` の間にある | プールはそのまま |

「収まる」かどうかは、ポリシーが見てきたものから判断されます。

- スケールアップのステップのたびに、その時点で各 isolate が受け取っていた毎秒のリクエスト数を、一つの isolate が受け取れる量として覚えます (その値と、それまで覚えていた値の平均)。
- それがわかった後は、今の毎秒のリクエスト数が、一つ少ない isolate で受け取れる量の 60 % 未満のとき、リクエストは収まります。
- 最初のスケールアップのステップの前は、それがわかりません。そのときは、実行中のリクエストが isolate の数より少なければ、リクエストは収まります。

### ポリシーにできないこと

- **スケールアップは遅れます。** 遅れが示すのは、リクエストがすでに待っているときの過負荷であって、isolate がそれにどれだけ近いかではありません。コンパイルされたプログラムは、自分の isolate がどれだけプロセッサー時間を使っているかを尋ねられません。突然のピークの最初の数秒は遅くなります。五秒間の遅れ、それから新しい isolate の起動です。
- **そのため、予想される負荷に対して `min` を十分に高く保ち**、わかっているピークの前には手でスケーリングしてください。
- **平均を読みます。** 空いている isolate の中で一つだけ遅れている isolate は、しきい値に達しないことがあります。いずれかの isolate が計測した最長の遅れである `maxLag` は、独自のポリシーのために用意されています。
- **待ちではなく、仕事に対してスケーリングします。** リクエストがデータベースを待つサーバーは遅れが小さく、このポリシーからは isolate をもらえません。

## 独自のポリシー

`IsolateScalingPolicy` Bean は `LagScalingPolicy` を置き換えます。

```dart
@Component()
class InFlightPolicy implements IsolateScalingPolicy {
  @override
  int? decide(IsolateScalingState state, Duration now) {
    final each = state.activeRequests / state.count;
    if (each > 200) return state.count + 1;
    if (each < 20 && state.count > state.min) return state.count - 1;
    return null; // プールはそのままにする
  }
}
```

`decide` は、クールダウンの外で二秒ごとに、最初の isolate で、遅れが一度計測された後に呼ばれます。`now` は前にしか進まない時間で、「これがどれだけ続いたか」のためのものです。時刻ではありません。

| `IsolateScalingState` のフィールド | 意味 |
|---|---|
| `count` | 応答している isolate の数 |
| `min`、`max` | 許される最小と最大の数 |
| `lag` | isolate のイベントループの遅れ。isolate 全体での平均 |
| `maxLag` | いずれかの isolate が計測した最長の遅れ |
| `activeRequests` | 実行中のリクエスト。すべての isolate の合計 |
| `requestsPerSecond` | 前回の確認以降に受け取った毎秒のリクエスト数。すべての isolate の合計。最初の確認では `0` |

- 答えはプールによって `min` と `max` の間に保たれ、クールダウンも引き続き適用されます。
- `scale-up-lag`、`scale-up-after`、`scale-down-after` はデフォルトのポリシーのものです。独自のポリシーは独自の設定を読みます。
- ステップは、ポリシーが何によって判断したかにかかわらず、遅れと実行中のリクエストとともにログに記録されます。
- Bean はすべての isolate に存在します。尋ねられるのは最初の isolate のものだけです。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `server.isolates.scaling` | `manual`、`auto` | `manual` | サーバーの実行中に isolate の数を変えるもの: `IsolateScaler` を通したアプリケーションだけか、スケーリングのポリシーもか |
| `server.isolates.min` | `int` | `1` | スケーリングが下げる最小の isolate の数 |
| `server.isolates.max` | `int` | 未設定: プロセッサーコアの数。`count` のほうが大きければ `count` | スケーリングが上げる最大の isolate の数 |
| `server.isolates.scale-up-lag` | `Duration` | `5ms` | デフォルトのポリシーが過負荷とみなす、isolate のイベントループの平均の遅れ。リクエストは、見てもらえるまでにおよそそれだけ待つ |
| `server.isolates.scale-up-after` | `Duration` | `5s` | デフォルトのポリシーが isolate を追加するまでに、isolate が遅れていなければならない時間 |
| `server.isolates.scale-down-after` | `Duration` | `2m` | デフォルトのポリシーが isolate を一つ削除するまでに、isolate が空いていなければならない時間 |
| `server.isolates.cooldown` | `Duration` | `15s` | スケーリングのステップの後、再びポリシーに尋ねるまでの休止時間 |
| `server.isolates.drain-timeout` | `Duration` | `30s` | 離れる isolate が、それでも停止されるまでにリクエストを完了させてよい時間 |

`server.isolates.count` は [isolate のプール](isolates.md#プロパティ) にあります。

## Spring (Java) との対応

Spring に対応するものはありません。いちばん近いのは、JMX でスレッドプールのサイズを変えることです。それは Bean を共有するスレッドを追加します。ここでは、ステップがアプリケーションのコピーを丸ごと追加または削除します。

## 関連項目

- [isolate のプール](isolates.md)
- [過負荷](overload.md)
- [毎秒のリクエスト数](qps.md)
- [isolate の負荷](../../spring-core-dart/isolates/load.md)
- [最初の isolate に問い合わせる](../../spring-core-dart/isolates/primary-isolate.md)
- [`isolates` エンドポイント](../../spring-boot-actuator/isolates.md)
- [シャットダウン](shutdown.md)
- [@Scheduled](../../spring-boot-starter-scheduling/scheduled.md)
- [負荷テスト](../../../docs/load-testing.md)
- [Durations](../../spring-core-dart/conversion/durations.md)
